Technical Documentation

How StreamLog is built — architecture, data model, API, and operations. StreamLog is a free shared movie, TV, and anime watchlist; this page documents the system for developers and contributors.

1. Overview & tech stack

StreamLog is a server-rendered Next.js application. Pages render on the server (mostly static or short-revalidate), while the authenticated app talks to a REST API under /api backed by PostgreSQL through Prisma. Expensive third-party media lookups are cached in memory and in a database table, and every mutating endpoint sits behind a distributed rate limiter.

2. Getting started

Prerequisites: Node.js 20+, a PostgreSQL database, a Firebase project with email/password auth enabled, and TMDB/OMDb API keys.

# install dependencies
pnpm install

# apply database migrations
pnpm db:migrate

# start the dev server
pnpm dev

# other scripts
pnpm lint        # eslint
pnpm test        # vitest run
pnpm build       # prisma generate && next build
pnpm db:studio   # prisma studio

Environment variables

3. Project structure

src/
├─ app/                  # App Router pages & API routes
│  ├─ (app)/             # Authenticated shell (dashboard, lists)
│  ├─ api/               # REST endpoints (see §6)
│  ├─ about|blog|docs|terms|privacy/   # Public static pages
│  ├─ layout.tsx         # Root layout, fonts, theme init script
│  ├─ sitemap.ts         # Generated sitemap
│  └─ robots.ts
├─ components/
│  ├─ ui/                # Design-system primitives (button, dialog…)
│  └─ *.tsx              # Feature components (board, dialogs, feed…)
├─ lib/
│  ├─ access.ts          # Membership/auth guards for routes
│  ├─ api.ts             # Typed client-side fetch wrapper
│  ├─ cache.ts           # memoWithDb: memory + MediaCache two-tier cache
│  ├─ discovery.ts       # Discover layout & genre configuration
│  ├─ http.ts            # JSON helpers, error envelope, zod parsing
│  ├─ lists.ts           # List queries & cache invalidation
│  ├─ media-details.ts   # Upstream detail merging (per-source)
│  ├─ rate-limit.ts      # Upstash sliding-window limiter (fail-open)
│  ├─ search-order.ts    # Cross-source result preference logic
│  ├─ session.ts         # getCurrentUser/requireUser + profile caches
│  ├─ theme.ts           # Client theme store (system/light/dark)
│  ├─ title-dedupe.ts    # Title identity keys
│  └─ firebase/          # Client SDK + server token verification
└─ generated/prisma/     # Generated Prisma client (do not edit)

4. Data model

The Prisma schema lives at prisma/schema.prisma. All child rows cascade on delete, so removing a list or user cleans up everything underneath it.

5. Authentication & sessions

1. 1. The client authenticates against Firebase with email/password and receives an ID token.
2. 2. POST /api/auth/session verifies the token server-side (RSA-SHA256 against Google's public keys), upserts the user row, and sets an HTTP-only cookie containing the user id and their current tokenVersion, signed with HMAC-SHA256 using SESSION_SECRET.
3. 3. Every request resolves the user via getCurrentUser(): verify the HMAC, then confirm the cookie's tokenVersion still matches the database.
4. 4. Signing out bumps tokenVersion, instantly invalidating every cookie ever issued for that account — no session table required.

To keep request handling cheap, profiles are cached in-memory for 60 seconds and token versions for 5 seconds, so a logout propagates across serverless instances within seconds. Password resets go through Firebase; changing passwords re-authenticates before updating.

6. API reference

All endpoints are JSON-in/JSON-out under /api, require the session cookie unless noted, and return errors in a common envelope ({ error: string }). The Group column is the rate-limit bucket (§8).

7. Upstream APIs & caching

Search

Movies and TV prefer TMDB results and fall back to OMDb when TMDB returns nothing (pickSearchResults in lib/search-order.ts). Anime queries AniList first, then Jikan. A title's identity is always the pair (source, externalId), so the same movie added twice resolves to one row.

Details

getMediaDetails merges per-source payloads into one shape: TMDB supplies genres/runtime/trailer and optionally an IMDb rating via OMDb cross-lookup; AniList supplies anime scores and episode counts. Upstream failures are retried with exponential backoff and then remembered for 5 minutes to avoid hammering a struggling provider.

Two-tier cache

memoWithDb checks an in-process Map first, then the durable MediaCache table (which survives cold starts and is shared across instances), then hits the provider. Writes are best-effort and never block the response. Detail payloads live for 24 hours; watch-provider links attach automatically (up to 2) when a title is added.

8. Rate limiting

Every API request passes through a distributed sliding-window limiter backed by Upstash Redis, keyed by user id (or IP pre-auth). Limits are global across all serverless instances. The limiter is fail-open: if Redis is unreachable the request proceeds, because availability outranks hardening.

When a client exceeds a limit, the API responds 429 with a Retry-After header; the UI surfaces the friendly "You're moving too fast" dialog.

9. Theming

The UI ships light and dark palettes as CSS variables (:root and .dark) consumed by Tailwind v4 semantic tokens. Users pick System default, Light, or Dark from the avatar menu; the choice persists in localStorage["streamlog-theme"].

• An inline script in the root layout applies the resolved theme class to <html> before first paint, preventing flashes.
• lib/theme.ts exposes a useSyncExternalStore-based store; OS scheme changes are followed live in system mode and other tabs sync via the storage event.
• Surfaces use semantic tokens (bg-surface, border-border, ring-border) rather than hardcoded colors; scrims over poster imagery intentionally stay dark in both themes.

10. Testing

Unit tests run with Vitest (pnpm test). Coverage focuses on pure decision logic that is easy to get subtly wrong:

• search-order — cross-source result preference and dedupe identity
• rate-limit — pathname-to-bucket mapping and rule coverage
• discovery — genre layout invariants
• blog — article integrity and canonical metadata
• http, cache, watch-providers — envelopes, TTL behavior, provider filtering

11. SEO

• app/sitemap.ts emits every public page; blog slugs are derived from BLOG_ARTICLES so new posts are included automatically.
• app/robots.ts allows all crawlers and points at the sitemap.
• Auth-gated routes (/login, /app, /lists, /join) emit noindex metadata and stay out of the sitemap.
• Marketing pages ship canonical URLs, Open Graph and Twitter cards, and JSON-LD structured data.

12. Deployment

1. 1. Provision PostgreSQL (Neon, Supabase, RDS…) and set DATABASE_URL in the hosting dashboard.
2. 2. Configure every environment variable from §2 — secrets stay out of the repo.
3. 3. Apply migrations with pnpm db:migrate (Prisma migrate deploy) before shipping a release that changes the schema.
4. 4. Deploy to Vercel; pnpm build runs Prisma generate automatically. Add the Upstash Redis REST credentials to enable rate limiting (it fails open without them).
5. 5. Verify /sitemap.xml and /robots.txt after the first deploy and submit the sitemap in Google Search Console.