Three apps sharing one contract, on free-tier hosting

Meducation. Private study portal for medical students.

Role
Solo engineer
Team
Solo
Status
In use, 233 student accounts.
Stack
  • TypeScript
  • NestJS
  • Next.js
  • PostgreSQL
  • Supabase
  • React
  • Vite
  • TanStack
  • Tailwind CSS
  • pnpm
  • Vercel
  • Render
  • Playwright
The subject library, with the student's own year first. From the live portal, cropped to leave out the signed-in student.
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.

The admin dashboard on the live portal. It checks the published content and lists what students would find missing, each with a link to fix it. Another admin's username is removed from the subtitle.

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.
Meducation: three apps that share one contract, on three free tiers.Student webNext.js + NextAuthAdmin webVite + RefineShared contractstypes + error catalogVercelhosting, /api/v1 proxyAPINestJS on RenderPostgresSupabase, SQL migrations
Meducation: three apps that share one contract, on three free tiers. Hover a box, or pick a flow above to step through it.
Text description of this diagram

Student request

  1. A student signs in with OAuth through NextAuth. The session check is cached so the app doesn’t ask the API on every navigation.
  2. Requests go to the versioned REST API on Render, behind global validation and a standard response envelope.
  3. The API reads from Supabase Postgres. A student may hold up to three active sessions.

Admin sign-in

  1. 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.
  2. The guard validates the session against the database on privileged requests: one active admin session, no more.

Changing a contract

  1. 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.