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 enables the shared git hooks, 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. It installs missing prerequisites with Homebrew (macOS). 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 Local approximation of CI: migrations, python manage.py test (the Django runner, not pytest), tsc --noEmit, Jest, ESLint.
./manage.sh review [type] [base] CodeRabbit review of local changes (all, uncommitted, committed, plain, prompt).
./manage.sh loadtest [suite] Run the k6 scripts in loadtests/ against the running backend (all, products, cart, upload).
./manage.sh magic-links [email] List active magic-link codes for debugging authentication.
./manage.sh createsuperuser Create a Django superuser.
./manage.sh export-seed-data / import-seed-data / update-catalog Catalog export and import; see Seed Data.
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/. Work on a feedback issue uses fix/feedback-<N>-<slug> or feature/feedback-<N>-<slug>; work on an internal todo uses fix/<todo-slug> or feature/<todo-slug> (see .claude/CLAUDE.md). Automation uses claude/dagplanning-<date>, claude/websitecheck-<date> and vrt/update-baselines-<timestamp>. 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. Only staging and release/* may target main (enforced by enforce-pr-base.yml; a PR opened against main from any other branch is retargeted to staging by dependabot-retarget.yml).

PR Process

  • Complete exactly one source reference in .github/PULL_REQUEST_TEMPLATE.md: Feedback: Voorman/freezedesign-feedback#<N> for a feedback issue or Ref: .planning/todos/pending/<slug>.md for an internal todo.
  • Explain what changed and why in the Wat / waarom section.
  • Add reproducible staging verification steps as checkboxes under Verify on staging; feedback-retest-comment.yml copies them to the feedback issue after the staging deploy.
  • Put anything only Ivar can do (secrets, accounts, decisions) under Voor Ivar; voor-ivar-lijst.yml adds those lines to the pinned "Voor Ivar" issue on merge.
  • 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. Merge is squash.
  • A PR built from the daily plan carries the line Dagplanning: <date> and gets auto-merge from dagbouw-bewaker.yml; never enable auto-merge on such a PR yourself (see GitHub Workflow).
  • Address CI and review findings without bypassing checks except when a documented incident procedure requires it.
  • Where a todo or feedback issue stands (who is next, open PR, deployed where) is read-only in python3 scripts/werkoverzicht.py (JSON or Dutch Markdown); scripts/werkbord.py renders the same as the Kanban page "Werkbord". Both only read (gh api GET, read-only git).

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.