What EpisodeTracker is actually built from

Yes — this is a full-stack app, not a frontend

A lot of small web projects are just a frontend calling somebody else's API. This one is not.

There is a Fastify server written in TypeScript that you control, sitting in front of your own PostgreSQL database, on your own DigitalOcean droplet. Every account, tracked show, watched episode and notification lives in tables you designed.

The only things you do not own are the TV data (TVmaze), the model that suggests shows (Groq, then Gemini), and mail delivery (Brevo). All three are wrapped in your own code, so the rest of the app never touches them directly.

That line count excludes dependencies and build output: 4,588 lines of API, 7,196 of web, 496 of shared types, 199 of database schema.

The stack, layer by layer

Read this top to bottom and you have the whole thing. Nothing else is in play.

This is a deliberately small dependency list. The API has 10 runtime dependencies and the web app has 3. Fewer libraries means fewer things that break on upgrade, and it is the reason a project this size still typechecks and builds in under a minute.

What happens when someone opens the site

This is a genuine sequence — each hop hands off to the next. Knowing it is how you debug anything.

1. Cloudflare — DNS, TLS termination, proxy. It forwards to the droplet and injects its analytics beacon, which is why the app's Content-Security-Policy explicitly allows static.cloudflareinsights.com.
2. Nginx, port 443 on the droplet — reverse-proxies everything to 127.0.0.1:3001. The app binds to loopback only, so nothing on the internet can reach the Node process directly; it has to come through Nginx.
3. Fastify, apps/api/src/index.ts — one single Node process. If the path starts with /api it is the JSON API; otherwise it serves files from apps/web/dist, and for a known app route like /history it hands back index.html so React takes over.
4. Session lookup — before any route runs, loadCurrentUser reads the sid cookie, finds the matching Session row and attaches the user to the request. Protected routes then simply check that it is there.
5. Route handler, e.g. shows/routes.ts — the actual logic: reading tracked shows, computing how many episodes behind you are, calling TVmaze if the cache is stale.
6. Prisma to Postgres — Prisma turns the typed query into SQL. Postgres runs on the same droplet and listens on localhost, so the database is not exposed to the network at all.
7. JSON back to React, apps/web/src/api/client.ts — one fetch wrapper handles every call. It always sends credentials: "include" so the session cookie travels, and throws ApiRequestError on any non-2xx so screens can show a real message.

The design decision behind this. Web and API share one origin — one process serves both. That is why every API route lives under /api (so it can never collide with a page URL like /settings), and why the session cookie can stay sameSite: lax instead of needing looser cross-site settings.

Three workspaces in one repository

It is an npm-workspaces monorepo: one npm install at the root wires all three together.

The rule that keeps both sides honest

Because both apps import the same types, changing an API response shape without updating the UI is a compile error, not a runtime surprise. Two conventions make that work: dates are always ISO string in shared types (JSON has no date type), and the shared User type deliberately omits passwordHash, so it is impossible to accidentally send a hash to the browser.

All 33 API routes

Everything is mounted under /api. Anything marked session needs the sid cookie — that is 27 of the 33.

Accounts and sessions

Finding shows

Your library

Push, public and operations

Eight tables, and what each one is for

Defined in prisma/schema.prisma. Every table except ShowCache uses a cuid string as its primary key.

The one structural quirk to remember

TrackedShow and ShowCache have no database foreign key between them, on purpose — you can track a show before it has been cached. The dashboard joins them in application code (loadTrackedShows()), not in SQL. If a tracked show ever renders with missing artwork or a blank next episode, that join is where to look.

The four services it depends on

Each one is isolated behind a single file, so the rest of the app never sees their raw responses.

TVmaze — all the TV data

Free, no API key. Wrapped in apps/api/src/tvmaze/client.ts, which exposes six functions and maps everything into the app's own types. Show details are fetched with ?embed[]=nextepisode&embed[]=episodes so one call gets both.

Groq, then Gemini — the suggestions engine

Both are OpenAI-compatible chat endpoints, so ai/client.ts is one generic caller with an ordered provider chain: try Groq, retry a couple of times on rate limits, then fall through to Gemini. Two things make this safe. Every AI pick is resolved against TVmaze by name, so hallucinated shows drop out. And the whole path never throws — if AI is down you get popular-airing-today picks, and the response says source: "popular" so the UI can be honest about it.

Brevo — email delivery

An HTTPS API rather than SMTP, and that is the point: most VPS providers block outbound mail ports, and this one does. The mailer is pluggable — getEmailer() picks the first configured option in order (Brevo, then Gmail SMTP, then Resend, then console), so local development can just print emails to the terminal.

Cloudflare — DNS, TLS, proxy

Sits in front of the droplet, and is the reason the CSP has that one allowance for the analytics beacon it injects at the edge.

Cost. TVmaze, Groq and Gemini are free tiers. Brevo is free to roughly 300 emails a day. Cloudflare is the free plan. The only thing being paid for is the droplet.

Running it, testing it, shipping it

Local development

npm install                  # installs all three workspaces
npm run db:up                # Postgres in Docker (Docker Desktop must be running)
npm run dev                  # API on :3001 + web on :5173, together

npm test                     # 7 test files, Node's built-in runner
npm run db:studio            # browse the database in a GUI
npm run db:migrate -- --name add_thing

Deploying

Deployment is a manual command, never an automatic push. Work happens on develop; when a change is confirmed it is fast-forwarded to main, and then deploy-oyware is run from the Mac. Pushing to main on its own changes nothing on the live site. The deploy script backs up the database before it touches anything, then runs prisma migrate deploy on the droplet.

What runs on its own

One thing: the daily notification job, scheduled by node-cron inside the running server at 0 12 * * * in Asia/Amman. It refreshes the show caches, finds episodes airing today, and emails or pushes each tracker once per episode.

Because it lives in the process, a deploy restart across that exact minute can skip a day — which is the one gap the (currently disabled) GitHub Action was kept around to cover.

What GitHub checks

On every push to develop or main, CI installs, generates the Prisma client, runs the tests, typechecks all three workspaces and builds the web app. No secrets and no database needed — they are all offline checks.

Terms you will hit in your own codebase

Coming from mobile development, most of this maps onto something already familiar.

One thing that has drifted

The repository's CLAUDE.md still says "No Web Push yet (email is still the notification path)". That is out of date. Web Push shipped: there is a PushSubscription table, a 20260620130000_web_push migration, three push endpoints, a push-sw.js service worker, and per-channel dedupe in NotificationLog.

Worth correcting, because that file is what any future session reads first.