Architecture to Code Mapping

Intent

Map architecture concerns to repository packages so implementation work lands in the right place.

Mapping Table

Concern	Primary location	Notes
Person identity and roles contracts	packages/domain	Shared type and validation surface
Shared browser auth clients and session primitives	packages/domain	Supabase browser env, cached client bindings, snapshots
Shared auth providers and screen composition	packages/ui	Cross-app React auth providers, login, and reset UI
Core relational entities and constraints	packages/db	Drizzle schema and migrations
Competency framework entities and inference contracts	packages/domain and packages/db	Versioned framework, evidence, and derived state model
Sync collections and conflict logic	packages/offline-data	PGlite/Electric integration layer
Append-only sync operation log engine	external pgxsinkit npm package	External project under team control, major-versioned
Authorization and mutation orchestration	apps/api	Enforces policy and emits side effects
Learner experience UI state	apps/learner-web	Role-specific frontend behavior
Teacher workflow UI state	apps/teacher-portal	Class orchestration and grading UX
Platform administration UI state	apps/admin-console	Invite-only administrative operations and access checks

Data Model Execution Guidance

When adding a new core model capability:

1. Update architecture docs if semantics change
2. Add or update domain contracts in packages/domain
3. Add or update schema in packages/db
4. Add sync behavior in packages/offline-data
5. Add API orchestration in apps/api
6. Add app-specific consumption in learner/teacher apps

Extension Execution Guidance

For extension features:

1. Define extension namespace and ownership
2. Add typed contracts
3. Add typed extension schema
4. Add sync and conflict policy
5. Add integration mapping implications

Anti-Pattern Guardrails

• Do not put cross-app domain semantics directly in frontend apps
• Do not bypass packages/domain for cross-surface validation
• Do not scatter sync logic outside packages/offline-data
• Do not encode standards-specific semantics directly into core identity entities
• Do not use per-route CRUD write paths for syncable domain tables; use pgxsinkit batch ingress in artifact mode