Δv Engineering: Dev Container Boilerplate

Welcome to the Δv Engineering Dev Container Boilerplate. This repository provides a professional-grade, zero-friction local development environment designed specifically for model-first engineering.

The goal of this setup is to provide instant hot-reloading, and give your agent harness (e.g., Claude Code) a standardized, containerized playground to build, test, and iterate.

🏗 Architecture

This stack uses docker compose to orchestrate four services:

Browser (localhost:3000)
    |
  nginx (proxy) — routes traffic
    |          \
frontend      backend --- db (PostgreSQL 17)
(React/Vite)  (FastAPI)

1. proxy (Nginx): Reverse proxy on port 3000. Routes /api/* to the backend and everything else to the frontend. Handles WebSocket connections for hot-reloading.
2. frontend (React + Vite + Tailwind CSS v4): The UI layer, written in TypeScript. Vite provides hot module replacement (HMR) so changes appear instantly in the browser.
3. backend (Python/FastAPI): The API layer. Includes JWT authentication, bcrypt password hashing, and SQLAlchemy ORM. Runs database migrations automatically on startup.
4. db (PostgreSQL 17): Persistent relational database with a health check — the backend waits for it to be ready before starting.

🚀 Quick Start

Prerequisites

• Docker Desktop (or Docker Engine + Docker Compose)
• make (usually pre-installed on macOS/Linux)

1. Environment Variables

cp .env.example .env

The defaults work out of the box for local development. The only variables are for the database connection.

2. Start the Stack

make build-stack

This builds the Docker images and starts all services. Once running:

• App: http://localhost:3000 (frontend + API via nginx)
• API directly: http://localhost:8000 (bypasses nginx)
• API docs: http://localhost:8000/docs (auto-generated by FastAPI)

3. Make Commands

Command	What it does
make stack	Start all services in the background
make build-stack	Build images and start (use after changing dependencies)
make rebuild-stack	Full clean rebuild — no cached layers
make down	Stop all containers (keeps database data)
make logs	Stream live logs from all services

To wipe the database and start fresh: docker compose down -v

🔥 Hot Reloading

Hot reloading is configured out of the box. Local ./frontend and ./backend directories are mounted directly into the containers, so any code changes are reflected immediately — no rebuild needed.

• Backend: Uvicorn runs with --reload, auto-restarting on Python file changes.
• Frontend: Vite's HMR updates React components in the browser without a full page refresh.

When to rebuild: If you change requirements.txt or package.json (dependencies are baked into the Docker image, not the mounted volume), run make build-stack.

📡 API Endpoints

Method	Path	Auth	Description
GET	/api/health	No	Health check — returns {"status": "ok"}
POST	/api/register	No	Create account — send {email, name, password}
POST	/api/login	No	Log in — send {email, password}
GET	/api/me	Yes	Get current user — send Authorization: Bearer <token>

🗄 Database Migrations

This project uses Alembic for database migrations. Migrations run automatically when the backend container starts (alembic upgrade head).

To create a new migration after changing models:

docker compose exec backend alembic revision --autogenerate -m "description of change"

To roll back the last migration:

docker compose exec backend alembic downgrade -1

🤖 Agent Context (CLAUDE.md)

⚠️ Warning: Proceed with caution. Recent research (arXiv:2602.11988) suggests that maintaining global instruction files like CLAUDE.md or AGENT.md may actively harm agent performance by introducing context drift and rigid logic loops.

If you choose to use one, keep it extremely short. Document only specific architectural constraints or make commands. Otherwise, it is often better to rely on dynamic, scoped prompting within your harness.