Skip to content

Development Guide

This guide describes the repository workflow for changing the Django backend, Next.js frontend, documentation, and deployment tooling.

Local Setup

  1. Fork or clone the repository and enter its root directory.
  2. Start Docker Desktop.

  3. Run the supported setup command:

    ./manage.sh setup

Use ./manage.sh setup --quick to skip optional prompts or ./manage.sh setup --skip-seed when catalog seed data is unnecessary. 4. Start both application servers with ./manage.sh start and check them with ./manage.sh status.

The setup script creates backend/venv, copies backend/.env.example when needed, installs backend and frontend dependencies, starts the PostgreSQL, Redis, and RabbitMQ development services, runs migrations, and can import seed data. See Installation and Configuration for the expanded setup.

Build Commands

Commands that act on the frontend must be run from frontend/ unless the command starts with ./manage.sh.

Command Description
./manage.sh start Start the local backend and frontend processes after checking services and dependencies.
./manage.sh stop Stop the local application processes.
./manage.sh restart Stop and start the local application processes.
./manage.sh status Show backend, frontend, Docker-service, and URL status.
./manage.sh ci-check Run the repository's local CI-oriented checks.
npm run dev Start the Next.js development server.
npm run build Create the production Next.js build.
npm run start Serve the production Next.js build.
npm run lint Run ESLint.
npm run check:env:staging Validate the frontend variables required by a staging image build.
npm run generate:api-types Regenerate TypeScript API types from the Django OpenAPI schema.
npm test Run Jest unit tests.
npm run test:ci Run Jest in CI mode with coverage.
npm run test:watch Run Jest in watch mode.
npm run test:coverage Run Jest and write a coverage report.
npm run test:e2e Run the Playwright projects.
npm run test:e2e:ui Open Playwright's interactive runner.
npm run test:e2e:headed Run Playwright with visible browsers.
npm run storybook Start Storybook on port 6006.
npm run build-storybook Generate the static Storybook site.
npm run docs:typedoc Generate TypeDoc output.

For backend development, activate backend/venv and run Django or pytest commands from backend/.

Code Style

  • Frontend linting uses ESLint 9 with frontend/eslint.config.mjs; run npm run lint from frontend/.
  • TypeScript is checked with npx tsc --noEmit. The pre-push hook and CI both run this check.
  • Backend CI runs flake8's error rules and reports complexity/style findings with a 127-character line limit. There is no repository-wide autoformatter configuration.
  • Match nearby code and test conventions. Do not commit generated directories such as frontend/.next/, coverage output, Playwright reports, or local virtual environments.

Branch Conventions

main is the default branch, while staging is the integration and automatic staging-deployment branch. Existing work uses descriptive prefixes such as feature/, fix/, test/, chore/, and dependabot/. Keep each branch focused on one change and open ordinary feature or fix pull requests against staging; promotion from staging to main is handled separately.

PR Process

  • Complete exactly one source reference in .github/PULL_REQUEST_TEMPLATE.md: either a Freeze Design feedback issue or a pending internal todo.
  • Explain what changed and why in the Wat / waarom section.
  • Add reproducible staging verification steps as checkboxes.
  • Run relevant backend, frontend, and E2E tests locally; the pre-push hook runs a backend subset, TypeScript, and Jest coverage.
  • Open the pull request against staging unless it is the explicit staging to main promotion.
  • Address CI and review findings without bypassing checks except when a documented incident procedure requires it.

API Contract Changes

When Django serializers, routes, or schemas change, regenerate the frontend contract before committing:

cd frontend
npm run generate:api-types

CI repeats this generation and fails when the committed TypeScript output has drifted. See the API Reference for authentication and endpoint conventions.