septm-backend

septm-backend is a NestJS HTTP API that powers a Seven Wonders score tracking backend (users, games, scoring, and extensions) backed by PostgreSQL and Prisma.

The goal of this documentation is to make it fast to:

• Run the project locally
• Contribute without breaking things
• Understand the main architectural decisions

For detailed documentation, see docs/README.md.

---

Quickstart

• Node.js: 20+
• Package manager: pnpm (see packageManager field in package.json)
• Database: PostgreSQL (a local instance can be started via Docker)

Install dependencies

pnpm install

Configure environment

Create a .env file at the root of the project (or reuse your own mechanism) with at least:

DATABASE_URL=postgresql://postgres:postgres@localhost:5432/septm
PORT=3000
JWT_SECRET=change-me

Adapt DATABASE_URL and JWT_SECRET to your environment.

Start local database (Docker)

pnpm run start:local:database

This uses docker-compose.local.yml to start a PostgreSQL instance suitable for local development.

Run migrations and seed

pnpm run prisma:migrate:dev -- <migration-name>
pnpm run prisma:db:seed

The Prisma schema and seed live under prisma/. See docs/architecture/prisma.md for conventions.

Start the API

# development (no watch)
pnpm run start

# development with watch
pnpm run start:dev

# production build
pnpm run build
pnpm run start:prod

Once running, the API is exposed (by default) on:

• Base URL: http://localhost:${PORT}/api/v1
• Health check: http://localhost:${PORT}/health

---

NPM scripts (summary)

• Project
  • start, start:dev, start:prod: run the NestJS application
  • build: compile TypeScript to JavaScript
• Database / Prisma
  • start:local:database: start local Postgres via Docker
  • stop:local:database: stop the local Postgres container
  • prisma:generate: generate Prisma client
  • prisma:migrate:dev: run dev migrations
  • prisma:db:seed: seed the database
  • prisma:db:push: push the schema without migrations (dev only)
• Code quality / tests
  • lint: run ESLint with --fix
  • format: run Prettier on src/ and test/
  • test, test:watch, test:cov, test:e2e: Jest test commands

---

Documentation

All project documentation lives under docs/:

• docs/README.md: documentation index and philosophy
• docs/architecture.md: high-level NestJS and system architecture
• docs/architecture/prisma.md: Prisma and database conventions
• docs/api.md: API conventions, base URLs, error format
• docs/adr/: Architecture Decision Records (ADRs)
• docs/runbook.md: operational notes for running/debugging the service

If you add or change any significant behaviour or architecture, please:

• Update the relevant section under docs/
• Add or update an ADR under docs/adr/ if the decision is important or hard to reverse