System Flow

Request Flow

1. Student or admin browser makes HTTPS request
2. Cloudflare proxies to Railway
3. Express middleware resolves organization_id from hostname (4-strategy resolver)
4. Clerk JWT verified → DB user fetched by clerk_id → req.user attached
5. Route handler applies scopeToOrg (tenant routes) or requirePlatformAdmin (platform routes)
6. PostgreSQL query executes with org scoping enforced
7. Response returned

Auth Middleware Chain

Request
└── hostnameResolver (org_id from hostname)
└── resolveClerkSecretKey (routes JWT to correct Clerk instance)
└── requireAuth (verifies token, attaches req.user)
└── requireAdmin | requireOrgAdmin | requirePlatformAdmin (role gate)
└── scopeToOrg (WHERE organization_id = req.user.organizationId)

Two Clerk Instances

Tokens from each instance are distinguished by the JWT iss claim. resolveClerkSecretKey() routes verification to the correct instance automatically.