- TypeScript 92.3%
- Python 7.4%
- JavaScript 0.2%
- Dockerfile 0.1%
Sandro Alves
811ffd5b22
Add a Script checks section to testing.md covering test_scripts.py, unit_test.py and diagnostics.py, trim the index intro and align the setup install wording with install.py. |
||
|---|---|---|
| .husky | ||
| .yarn/releases | ||
| docs | ||
| prisma | ||
| scripts | ||
| src | ||
| test | ||
| .dockerignore | ||
| .env.example | ||
| .gitignore | ||
| .node-version | ||
| .oxlintrc.json | ||
| .prettierrc | ||
| .yarnrc.yml | ||
| AGENTS.md | ||
| commitlint.config.ts | ||
| docker-compose.yml | ||
| Dockerfile | ||
| eslint.config.mjs | ||
| LICENSE | ||
| nest-cli.json | ||
| openapi.json | ||
| package.json | ||
| prisma.config.ts | ||
| README.md | ||
| tsconfig.build.json | ||
| tsconfig.json | ||
| yarn.lock | ||
OpenLearn API
NestJS REST API for the OpenLearn learning platform. It serves PostgreSQL data through Zod-validated endpoints, protects them with JWT authentication and rate limiting, runs the lesson content, progress, XP and AI features, and documents every route in Swagger.
Stack
| Layer | Technology |
|---|---|
| Runtime | Node.js 24, NestJS 11 |
| Language | TypeScript |
| Database | PostgreSQL via Prisma |
| Validation | Zod, nestjs-zod |
| Auth | JWT access tokens, rotating refresh tokens |
| Cache and queue | Redis (optional), BullMQ |
| Docs | Swagger at /api/docs |
| Linting | oxlint, then ESLint |
| License | AGPL-3.0-or-later |
Prerequisites
- Node.js
24.14.0(see.node-version) and Yarn 4 - Docker and Docker Compose v2, for PostgreSQL and Redis
Quick start
yarn install
docker compose up -d postgres redis
cp .env.example .env
yarn prisma:generate
yarn prisma:migrate
yarn prisma:seed
yarn start:dev
The API listens on http://localhost:4000; Swagger is at
http://localhost:4000/api/docs. A fresh admin password is generated and
printed on each boot unless ADMIN_PASSWORD is set; production requires the
variable and never prints it (see
Operations).
Redis is optional for the API to boot but required for the AI verdict cache and
the AI job queue. Set AI_API_KEY to grade answers with a model. See
Setup for the full clone-to-running walkthrough.
Commands
| Command | Purpose |
|---|---|
yarn start:dev |
Dev server with watch |
yarn build |
Compile to dist/ |
yarn start:prod |
Run dist/cmd/server/main |
yarn test |
Jest unit suite |
yarn test:e2e |
E2E suite |
yarn check |
Lint, unit tests, build and OpenAPI drift check |
yarn prisma:migrate |
Run pending migrations (dev) |
yarn prisma:migrate:deploy |
Apply migrations in deployed environments |
yarn prisma:seed |
Upsert canonical content, roles, ladder and users |
yarn openapi:check |
Regenerate openapi.json and fail on drift |
The full environment variable reference is in
.env.example and Setup.
Documentation
| Document | Contents |
|---|---|
docs/README.md |
Index of the documentation set |
docs/setup.md |
Prerequisites, environment variables, local and Docker setup |
docs/architecture.md |
Modules, request flow, auth, AI, courses, XP, runtime configuration |
docs/authoring.md |
Server-side lesson XML validation contract |
docs/operations.md |
Deploy, rate limits, AI configuration, Redis, security, backups |
docs/testing.md |
Jest, E2E and the OpenAPI drift check |
scripts/README.md |
Python helper scripts and OpenAPI tooling |
AGENTS.md |
Machine-facing invariants and the verification gate |
License
AGPL-3.0-or-later. See LICENSE.