Architecture

Before changing app structure, route boundaries, or shared ownership rules, read and follow b2b2c-architecture-contract.md.

Workspace Shape

• apps/app Unified product app for org, portal, and platform.
• apps/marketing Optional public marketing surface.
• apps/docs Docusaurus app that publishes docs/app only.
• packages/backend Convex backend package.
• packages/* Shared typed packages and repo-wide infrastructure.

There is no separate apps/web or apps/admin app in this starter.

Product App Shape

The product app is surface-first.

• apps/app/src/app/[locale]/* Owns route entrypoints, layouts, and route-local page composition.
• apps/app/src/app/[locale]/org/** Owns organization-staff routes, supporting components, hooks, and helpers.
• apps/app/src/app/[locale]/portal/** Owns tenant portal routes and portal-specific UI.
• apps/app/src/app/[locale]/platform/** Owns platform-operator routes and platform-specific UI.
• apps/app/src/app/[locale]/_components/*, _hooks/*, _lib/* Own app-shared modules only after reuse is proven across surfaces.

Default placement rule:

1. Start in the owning route tree.
2. Keep the page body in page.tsx by default.
3. Keep route-local support code in underscored folders next to the route.
4. Promote code into app-shared folders only when it is intentionally shared across surfaces.

Import Rules

• Use @/ for cross-boundary imports inside apps/app.
• Use relative imports only for tightly-coupled local files in the same module area.
• Do not deep-import another route tree's private _components/*, _hooks/*, or _lib/*.

Convex Rules

All authored Convex source lives in packages/backend/convex.

• apps/app/src/** may import app-facing references from @convex/*.
• @convex/* resolves into packages/backend/convex/* through the app TypeScript config.
• apps/app/convex is generated-only and exists for app-side generated imports. Do not author backend code there.
• Inside packages/backend/convex/**, use local generated imports such as ./_generated/server.

Root files in packages/backend/convex should stay runtime-global only:

• auth.ts
• auth.config.ts
• http.ts
• crons.ts
• schema.ts

Everything else belongs in an owning namespace such as org/, portal/, platform/, notifications/, or system/.

Shared Packages

Use packages/* for typed configuration, shared primitives, and cross-app infrastructure.

Promotion rule:

1. Start app-local.
2. Move into packages/* only after reuse is real or the module is clearly repo-wide infrastructure.

Docs Split

• docs/app Durable starter docs for product-facing architecture and app extension.
• docs/dev Developer, backend, integration, deployment, and operations docs.

Older client-specific planning and product docs are archived from the main app-docs sidebar and should not be treated as starter-kit source of truth.