Architecture Documentation

This section is the engineering source of truth for platform architecture decisions and implementation guidance.

Scope

This documentation is for engineering implementation only:

• Data model architecture
• Backend/frontend contract and schema strategy
• Offline sync topology
• Standards integration architecture
• Operational runbooks

This section intentionally excludes end-user documentation.

Platform Design Direction

The platform is designed as a generic learning system with language-learning as the initial specialization.

Core requirements:

• Support independent learners, one-on-one instruction, teacher-to-class, and MOOC-scale offerings
• Keep learner history person-centric and portable across institutions and role transitions
• Allow the same person to be a learner and teacher over time
• Keep a generic core model while supporting domain-specific extensions

Two configuration concepts sit on top of the generic core and are kept orthogonal — what a subject offers (subject pack) and how an activity is presented (surface layout, a presentation layer distinct from the QTI / competency-framework / xAPI standards models). See Surface Layout and Subject Packs.

Reading Order

1. Core Model
2. Competency Framework Model
3. Entity Lifecycle
4. Data Invariants
5. Extension Architecture
6. Schema Strategy
7. Relational Blueprint V1
8. Migration Sequencing V1
9. Person–Auth Decoupling V1
10. Sync Topology
11. Sync Write Model V1
12. Sync Write Enforcement V1 (Lite)
13. Standards
14. Externalisation Boundary V1
15. Surface Layout and Subject Packs
16. Language Module Migration V1
17. Integration Mappings
18. Implementation Patterns
19. Runbooks

Implementation Anchors

• Domain contracts: packages/domain
• Relational schema and migrations: packages/db
• Offline/sync plumbing: packages/offline-data
• Service boundaries and API behavior: apps/api

Documentation Conventions

Every architecture document should include:

• Intent and non-goals
• Terminology section
• Design decisions and rationale
• Invariants and constraints
• Implementation anchors to repository packages
• Open decisions and confirmation needed

Confirmed Baseline Decisions

The initial implementation baseline is confirmed as:

• Person-centric identity is the primary invariant
• Unified time-bounded membership is the baseline participation model
• Neutral learning-structure terms are used internally with aliases for LMS-specific terms
• Person-portable exports include full attempt-level and feedback-level history by default
• Concrete competency framework modeling is part of v1 core architecture
• Syncable domain-table writes use a single ingress (POST /api/mutations) in pgxsinkit bulk-plpgsql-artifact mode

If these assumptions change, update Core Model, Data Invariants, and Schema Strategy together.