Architecture Overview
GritCert runs on a single Node.js/Express backend serving both the student app and the platform admin console. The database is PostgreSQL. Authentication is handled by two Clerk instances: one for students, one for platform admins.
Key Principles
- DB-canonical roles: the database
users.roleis the sole source of truth for authorization. Clerk is a display hint only. - Org scoping on every tenant route: all tenant-scoped queries route through
scopeToOrg(req)middleware. Fail-closed in production. - Platform routes are separate:
/api/platform/*routes requirerequirePlatformAdminand are completely isolated from tenant-scoped routes. - BYPASS_AUTH is permanently false: in every environment, including local dev.
Services
| Service | URL | Hosting |
|---|---|---|
| Student App (React SPA) | app.{slug}.gritcert.com or custom domain | Railway |
| Platform Admin Console | admin.gritcert.com | Railway |
| API (Node/Express) | app.gritcert.com/api | Railway |
| Database | PostgreSQL | Railway |
| Documentation | docs.gritcert.com | Vercel |
Student app URL is tenant-specific. Default: {slug}.gritcert.com. Custom domains supported.
Last updated on