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, auth sessions, exports, SSE
apps/worker	Optional background jobs
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. Microsoft Graph is used for Outlook calendar write-back and optional Entra profile photos. See SSO setup, SCIM, Microsoft profile photos, 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 checkout provisioning in another product, read Platform framework (canonical copy: docs/PLATFORM_FRAMEWORK.md).

Related

• Platform framework
• Scheduling engine
• Stakeholder deck: presentation/index.html