Skip to main content

ADR-002: Hybrid Local Dev Architecture

Status: ✅ Accepted Date: 2026-03-22 Decision Makers: Tilak Kumar

Context​

Local development requires running three components: a PostgreSQL database, a Node.js backend API, and a React frontend. The team debated whether to run everything in Docker Compose or use a hybrid approach.

Running everything in Docker was considered for consistency, but it introduced significant friction:

  • Hot-reload in Docker requires volume mounts and is 3–5× slower than native
  • TypeScript compilation and ts-node-dev/tsx watch mode are noticeably slower inside containers
  • Debugging with breakpoints in VS Code/Cursor requires remote Docker debugger configuration
  • Mac M-series (ARM) chips have Docker networking quirks that cause intermittent port-binding issues

Decision​

Run PostgreSQL in Docker only. Run backend and frontend natively on the host.

Docker Compose:
  - postgres:15 (port 5432)

Host (native):
  - backend  → cd backend && npm run dev  → http://localhost:4005
  - frontend → cd frontend && npm run dev → http://localhost:3005

Rules that follow from this decision:​

  • NEVER run frontend or backend inside Docker locally
  • NEVER run docker-compose up without specifying the postgres service
  • Redis is NOT used locally — the caching layer degrades gracefully
  • DB shell: docker-compose exec -T postgres psql -U tenable -d tenable_dashboard

Consequences​

Positive:

  • Native TypeScript hot-reload is instantaneous vs. 2–5s in Docker
  • Breakpoints and debuggers work out-of-the-box in VS Code/Cursor
  • No Docker networking issues between frontend ↔ backend
  • npm run dev startup is < 2s vs. 10–30s for container startup
  • Logs are readable directly in the terminal (no docker logs needed)

Negative / Trade-offs:

  • Developers must have Node.js 20+ installed on their host machine
  • "Works on my machine" risk is higher than a fully containerized environment
  • PostgreSQL version difference between local Docker image and Supabase cloud (managed by pinning the image tag)
  • Requires two terminals to be open (backend + frontend) — mitigated by a root-level npm run dev:all script

Alternatives Considered​

OptionWhy Rejected
Full Docker Compose (all 3 services)Slow hot-reload, complex debug setup, Docker-on-Mac networking issues
Dev containers (VS Code)Adds another layer of complexity; still slow for heavy TypeScript projects
Fully native (no Docker at all)PostgreSQL installation on dev machines is inconsistent across OS versions; Docker gives a reproducible DB environment
Docker with volume mounts for codeBind mounts on Mac are slow (osxfs/VirtioFS still has overhead); not worth it