Architecture overview

Who this is for: Developers
What you'll achieve: Orient yourself in the monorepo and request flow

Modular monolith

flowchart TB
  Browser[Browser tenant portal] --> Web[apps/web Next.js]
  Web --> TRPC[tRPC routers]
  TRPC --> Domain[packages/domain]
  TRPC --> DB[packages/db Drizzle]
  Web --> SSE[SSE /api/sse]
  Worker[apps/worker BullMQ] --> Domain
  Worker --> DB

Package / app	Responsibility
apps/web	UI, tRPC API, /api/mobile/v1, auth sessions, exports, SSE
apps/mobile	Staff companion (Expo). CI typechecks and unit-tests it; native binaries are EAS.
apps/worker	Optional background jobs, including staff-app push drain
packages/domain	Scheduling engine, RBAC, analytics pure logic
packages/db	Schema, migrations, seed
packages/emails	Email templates

Tenancy

School portals live at /t/{subdomain}/…. Platform operator UI is at /operator.

Auth

Custom session cookie (schoolrota_session) with bcrypt passwords, TOTP MFA for privileged local accounts, per-tenant OIDC SSO, and SCIM 2.0 directory sync. The staff app uses hashed rotating tokens at /api/mobile/v1 after the same school SSO or password login. Microsoft Graph is used for Outlook calendar write-back and optional Entra profile photos. See SSO setup, SCIM, Microsoft profile photos, Staff app, and Platform framework.

Canonical engineering spec

For domain model, invariants, and roadmap detail, read docs/SYSTEM_PLAN.md in the repository. This docs site does not replace that document: it summarises for day-to-day onboarding.

To reuse hosting, tenancy, auth, SCIM, and verified signup and subscription conversion in another product, read Platform framework (canonical copy: docs/PLATFORM_FRAMEWORK.md) and No-card trial playbook.

Related

• Platform framework
• Staff app
• No-card trial playbook
• Scheduling engine
• Stakeholder deck: presentation/index.html