Monorepo shape

Application boundaries

• apps/learner-web is the primary product surface and should be scaffolded first.
• apps/teacher-portal is a separate frontend with a different workflow focus, but it should reuse shared UI and domain packages.
• apps/api hosts backend endpoints and sync services.

Shared package boundaries

• packages/ui for reusable presentational components and hooks
• packages/domain for language-learning entities, validation, and shared business types
• packages/db for Drizzle schema and migrations
• packages/offline-data for offline-first, pgxsinkit and PGlite logic
• packages/config for shared env/config helpers

API ingress and function paths

• Public function endpoints should use the canonical /functions/v1/<function-name> path on the API host. This will be stripped by the supabase/istio proxy, so runtime handlers should only accept /<function-name>.
• Workflow state endpoints follow this convention as /workflow/state (canonical).

Naming guidance

• repo-wide namespace: emergent
• internal package scope: @emergent/*
• app directory names: role-based and explicit, such as learner-web and teacher-portal