ADR-002 — Development Stack (MVP Local)

ADR-002 — Development Stack (MVP Local)

Status

Accepted

Context

The local development stack must allow fast iteration without friction: spin up the database, backend, and frontend with the minimum number of commands, without installing system dependencies outside of Docker and Node.

Decision

The local environment runs with two concurrent processes:

1. Docker Compose — spins up PostgreSQL 16 + Django API in containers. A single command from the project root:

   docker compose up -d

   The api container entrypoint runs migrations, collectstatic, and superuser seeding automatically on startup.

2. Angular dev server — runs outside Docker, directly on Node:

   cd frontend && bun start

   Proxy configured in angular.json: all /api/* requests are redirected to localhost:8000.

Environment variables: a single .env at the root, copied from .env.example. There is no .env in frontend/ or backend/; Docker Compose injects them into the container.

Stack verification:

curl http://localhost:8000/api/health/   # {"status":"healthy","database":"connected"}
curl http://localhost:4200/api/health/   # same JSON, via Angular proxy

Sub-decisions

• [[adr-002-a-backend-dev-stack|ADR-002-a]] — Backend Development Stack. Pins Python, Django, DRF, psycopg, uvicorn, django-fsm-2, and PostgreSQL versions for reproducibility between dev and prod Docker images.
• [[adr-002-b-frontend-dev-stack|ADR-002-b]] — Frontend Development Stack. Pins Bun, Angular, TypeScript, PrimeNG, Tailwind, and Vitest versions; establishes Bun as the sole package manager and script runner.

Consequences

• Neither PostgreSQL nor Python is installed directly on the host system.
• Hot-reload is active on both sides: --reload in uvicorn, ng serve in Angular.
• Version and dependency sub-decisions are in [[adr-002-a-backend-dev-stack|ADR-002-a]] (backend) and [[adr-002-b-frontend-dev-stack|ADR-002-b]] (frontend).