Platform API

NestJS REST API for OpenLearn. It serves PostgreSQL data through Zod-validated endpoints, protects them with rate limiting and refresh-token auth, and documents everything in Swagger.

Full documentation lives in docs/ — architecture, setup, scripts, testing and operations.

Quick start

yarn install
docker compose up -d postgres
cp .env.example .env
yarn prisma:generate && yarn prisma:migrate && yarn prisma:seed
yarn start:dev

The API listens on http://localhost:4000. Swagger docs are at http://localhost:4000/api/docs.

Stack

Layer	Technology
Runtime	Node.js 24 + NestJS 11
Language	TypeScript
Database	PostgreSQL via Prisma ORM
Validation	Zod + nestjs-zod
Auth	JWT access + rotating refresh tokens
Docs	Swagger at /api/docs
Linting	oxlint, then ESLint
Formatting	Prettier
License	AGPL-3.0-or-later

Environment variables

Variable	Description
DATABASE_URL	PostgreSQL connection string
PORT	HTTP port (default 4000)
AUTH_SECRET	Secret for signing JWTs (min 32 characters)
FRONTEND_URL	Allowed CORS origin
ADMIN_EMAIL	Admin account email
ACCESS_TOKEN_TTL	Access token lifetime (default 900)
REFRESH_TOKEN_TTL	Refresh token lifetime (default 30 days)
APP_TIMEZONE	Timezone for streak calculations
SWAGGER_ENABLED	Force Swagger UI on/off (off in production by default)
API_KEY_ENCRYPTION_SECRET	Master key for BYOA API keys at rest (AES-256-GCM)

The full reference, including rate limits and AI settings, lives in .env.example.

Scripts

yarn start:dev             # Dev server with watch
yarn build                 # Compile to dist/
yarn start:prod            # Run the compiled server (dist/cmd/server/main)
yarn lint                  # oxlint + ESLint
yarn test                  # Unit tests
yarn test:e2e              # E2E tests
yarn openapi:check         # Regenerate + validate the OpenAPI spec
yarn prisma:migrate        # Run pending migrations
yarn prisma:migrate:deploy # Apply migrations in deployed environments
yarn prisma:seed           # Upsert the canonical learning content
yarn prisma:studio         # Open Prisma Studio

Python helper scripts (API tests, diagnostics, installs, backups, credential collection) are summarized in docs/scripts.md; the full usage reference lives in scripts/README.md.

Project structure

src/
  cmd/                      # Entrypoints (Go-style)
    server/                 # main.ts + swagger-config.ts
    openapi/                # generate-openapi.ts (tooling)
  internal/                 # Application code
    app/                    # app.module.ts (composition root)
    <domain>/               # auth, users, courses, ai, admin, health
      <domain>.controller.ts
      <domain>.service.ts
      <domain>.repository.ts
      <domain>.schemas.ts   # request + response Zod schemas
      <domain>.constants.ts
      swagger.decorators.ts
      *.spec.ts             # co-located tests
    shared/                 # HTTP error helpers, seed helpers
    infra/prisma/           # PrismaModule (global), PrismaService

See docs/architecture.md for the full layout and conventions.