Extension Architecture

Intent

Provide strong extensibility without destabilizing the core data model.

The platform must support specialization for language learning and future domains while preserving a stable, interoperable core.

Extension Strategy

Use a layered extension approach:

1. Core entities remain minimal and durable
2. Low-risk custom attributes can use controlled metadata fields
3. High-value specialization uses typed extension tables and contracts
4. Extension modules declare namespace, ownership, and compatibility rules

Extension Types

Type A: Metadata Extensions

Use for low-criticality, optional display or UX hints.

Characteristics:

• Stored in constrained JSONB metadata fields
• Schema validated by module-specific Zod validators
• Not used for core authorization or grading decisions

Type B: Typed Relational Extensions

Use for domain-critical specialization.

Characteristics:

• Dedicated extension tables with foreign keys to core entities
• Explicit migration ownership
• Strong typing in domain contracts
• Version-aware compatibility rules

Type C: Event Projection Extensions

Use for derived analytics/integration views.

Characteristics:

• Generated from core events and records
• Rebuildable and denormalized when needed
• Never source of truth for core transactional state

Extension Module Contract

Each extension module should define:

• namespace (for example lang.v1)
• owner (team/package)
• entity_targets (which core entities are extended)
• schema_version
• compatibility_policy
• validation_contracts
• migration_policy

Governance Rules

1. No extension may redefine core identity semantics
2. No extension may bypass core audit requirements
3. Critical business decisions must not rely only on untyped metadata
4. Extension migrations require compatibility notes
5. Deprecated extensions require data migration or archival plan

Anti-Patterns

Avoid:

• Single giant JSON blob for all specialization
• Copying core fields into extension tables without provenance
• Extension-only authorization logic that bypasses core membership model
• Versionless extension payloads

Recommended Repository Mapping

• Extension domain types and validators: packages/domain
• Extension schema and migrations: packages/db
• Extension sync projections: packages/offline-data
• Extension APIs and orchestration: apps/api

Rollout Pattern For New Extensions

1. Define extension contract and namespace
2. Add Zod schemas and type exports
3. Add typed Drizzle tables and relations
4. Add sync shape rules and conflict behavior
5. Add integration mapping impact notes
6. Add tests and migration notes

Open Decisions

1. Namespace naming policy granularity (domain.area.vN vs shorter forms)
2. Compatibility guarantees across extension major versions
3. Whether extension registry should be static code-based or persisted in DB