Kultrak

Media tracking platform for movies, TV shows, books and video games. Keep a personal collection with ratings and start/end dates, manage a watchlist, browse a calendar of upcoming releases, follow other users via an activity feed, and import or sync titles from Goodreads, TMDB, IGDB, Google Books and OpenLibrary.

Production: https://kultrak.com · API: https://api.kultrak.com

Tech stack

• Backend — NestJS 11, TypeORM 0.3, PostgreSQL 18, Socket.io, JWT + Google OAuth
• Frontend — Angular 21 (standalone components, SSR, PWA), Tailwind CSS 4 with the tw: prefix
• Monorepo — Turborepo + npm workspaces
• Tests — Vitest (unit + integration), Testcontainers for Postgres, Playwright for E2E

Repo layout

apps/
  backend/         NestJS REST API
  frontend/        Angular 21 SPA + SSR + PWA
packages/
  core-domain/     Shared domain types (placeholder)
e2e/               Playwright specs, page objects, mock API server
deploy/            Production docker-compose + sample env files
docs/              Design docs and implementation plans

Prerequisites

• Node >= 18 (Docker images use Node 24-alpine)
• npm 10.2.5 (pinned via packageManager)
• Docker (required for integration tests via Testcontainers and for the E2E stack)
• PostgreSQL 18, if you prefer to run the database directly instead of via Docker

Getting started

npm install

Create apps/backend/.env (no committed example — use deploy/backend.sample.env as a reference) and fill in at least the TMDB, IGDB, Google OAuth and Google Books credentials listed in External integrations.

Then, from the repo root:

npm run dev           # runs backend + frontend together via Turbo

Or run each app individually:

cd apps/backend  && npm run start:dev   # NestJS in watch mode
cd apps/frontend && npm start           # ng serve

Other root tasks: npm run build, npm run lint, npm run check-types, npm run format.

Database & migrations

The TypeORM data source runs with synchronize: false — migrations are authoritative. From apps/backend:

npm run migration:generate -- --name=MyChange
npm run migration:run
npm run migration:revert

Testing

Scope	Command (run from)	Notes
Backend unit	npm test (apps/backend)	Vitest, no DB, no network.
Backend integration	npm run test:int	Real Postgres via Testcontainers. Set USE_LOCAL_TEST_DB=1 to reuse docker-compose.test.yml.
Backend coverage	npm run test:cov	Unit + coverage.
Frontend	npm test (apps/frontend)	Vitest + jsdom.
End-to-end	npx playwright test (e2e)	Boots a full Postgres + backend + frontend + mock-API compose stack.

E2E env flags: E2E_SKIP_COMPOSE=1 if the stack is already running, E2E_KEEP_STACK=1 to leave it up between runs.

External integrations

All external APIs are intercepted by e2e/mock-server during E2E runs.

API	Purpose	Env vars
TMDB	Movies, TV shows	TMDB_APIKEY, TMDB_BASE_URL
IGDB	Video games	IGDB_CLIENT_ID, IGDB_SECRET, IGDB_API_URL
Goodreads (scraped)	Books	GOODREADS_BASE_URL
Google Books	Books enrichment	GOOGLE_BOOKS_API_KEY, GOOGLE_BOOKS_BASE_URL
OpenLibrary	Books	OPENLIBRARY_BASE_URL
Google OAuth	Sign-in	GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, GOOGLE_CALLBACK_URL

Deployment

Each app has its own multi-stage Dockerfile. The frontend image builds an Angular SSR bundle served by Express.

Production compose lives in deploy/docker-compose.yml and orchestrates the backend, the frontend, Postgres 18 and a one-shot migration runner, behind Traefik. Images are published to registry.gitlab.com/olmo/kultrak/{backend,frontend}.

Sample env files: deploy/sample.env, deploy/backend.sample.env, deploy/frontend.sample.env.

CI

• GitLab CI — .gitlab-ci.yml triggers per-app child pipelines; .gitlab-ci.e2e.yml runs the E2E pipeline on MRs to main and pushes to main.
• Forgejo Actions — mirrored workflows live in .forgejo/.

Conventions

In-repo conventions (entity inheritance rules, Tailwind tw: prefix usage, test helpers, commit message style) are documented in CLAUDE.md.

License

UNLICENSED — proprietary, all rights reserved.