Three apps sharing one contract, on free-tier hosting
Meducation. Private study portal for medical students.
- Problem
- Medical students needed one private place to share and review exam-prep resources, with separate student and admin experiences and no budget for infrastructure.
- My role
- Solo engineer. Architecture, API, both front ends, database and deploys.
- Key call
- One shared contracts package for types and error codes, so the three apps can't drift apart silently.
- Outcome
- In use by 233 student accounts, with 682 lectures across 24 subjects, running entirely on Supabase, Render and Vercel free tiers.
A small audience with busy exam weeks
The portal belongs to one medical school’s students and is private to them. Students share video and document links before exams and review what others have shared. Admins curate it. Today it holds 682 lectures across 24 subjects for 233 student accounts.
For most of the year the traffic is quiet. Before an exam, it all arrives at once. The system has to handle that peak on infrastructure that costs nothing.
Constraints
- One engineer, studying full-time.
- Zero budget. Supabase Free, Render Free and Vercel Hobby.
- Two very different users. Many students with low privilege; a few admins who can change what everyone sees.
Key decisions
Contracts are a package, not a convention
- Considered
- Copy the types into each app, or generate them from the database.
- Chose
- One shared package holds the types, DTO-aligned interfaces and an error catalog. The Next.js student app, the Refine admin and the NestJS API all import it.
- Because
- When the API changes shape, the front ends fail to compile instead of failing in front of a student. Error codes mean the same thing in every app.
- Cost
- Every cross-app change starts in the shared package, and all three apps move together.
Two threat levels, two auth models
- Considered
- One sign-in flow for everyone.
- Chose
- Students sign in with OAuth through NextAuth. Admins use a password, a short-lived JWT and rotating refresh tokens, with one active admin session enforced against the database (students may hold three). Auth routes are rate-limited.
- Because
- A stolen admin session can change what every student sees. A stolen student session can't.
- Cost
- Two session systems to build, test and keep secure.
The schema lives in git, in order
- Considered
- Edit tables in the Supabase dashboard.
- Chose
- Ordered SQL migrations tracked in a migrations table, with scripts to apply, inspect, reset and seed. Retention functions delete expired refresh tokens and old auth-audit rows.
- Because
- Schema history is deterministic and reviewable. On a free-tier database, a token table that grows forever is a slow outage.
- Cost
- Slower for quick experiments; every change needs a migration.
Text description of this diagram
Student request
- A student signs in with OAuth through NextAuth. The session check is cached so the app doesn’t ask the API on every navigation.
- Requests go to the versioned REST API on Render, behind global validation and a standard response envelope.
- The API reads from Supabase Postgres. A student may hold up to three active sessions.
Admin sign-in
- An admin signs in with a password. Auth routes are rate-limited; the API answers with a short-lived JWT and a rotating refresh token.
- The guard validates the session against the database on privileged requests: one active admin session, no more.
Changing a contract
- Change a response shape in the shared package and all three apps fail to compile until they agree. Drift surfaces in the editor, not in front of a student.
Handling exam-week traffic
Low average traffic with short bursts favours fewer, cheaper requests over more servers. Session checks on the student app are cached so navigation doesn’t hit the API every time. Responses are compressed, and the API standardizes validation, errors and request tracing, so a problem during exam week can be traced from one log line.
Where it stands
It’s in use by 233 student accounts and costs nothing to run. Because the compiler enforces the contract, not memory, a breaking change between the apps shows up as a type error before it ships.