docker-compose.yml

# =============================================================================
# Docker Compose — Orchestrates all services in the stack
# =============================================================================
# This file defines every service (container) in the app and how they connect.
# Run it with: make stack (or: docker compose up -d)
#
# Architecture overview:
#
#   Browser (localhost:3000)
#       |
#     nginx (proxy) — routes traffic
#       |          \
#   frontend        backend --- db (PostgreSQL)
#   (React)        (FastAPI)
#
# All services share a Docker network so they can reach each other by name
# (e.g., the backend connects to "db" on port 5432).
# =============================================================================

services:

  # ---------------------------------------------------------------------------
  # PostgreSQL Database
  # ---------------------------------------------------------------------------
  # Stores all application data (users, etc). Data persists across restarts
  # because it's saved in a named volume (postgres_data).
  db:
    image: postgres:17-alpine          # Alpine = smaller image, same Postgres
    env_file:
      - .env                           # Reads POSTGRES_USER, PASSWORD, DB from .env
    ports:
      - "5432:5432"                    # Expose to host so you can connect with pgAdmin, etc.
    volumes:
      - postgres_data:/var/lib/postgresql/data  # Persist data between container restarts
    healthcheck:
      # The backend waits for this check to pass before starting.
      # pg_isready is a built-in Postgres utility that checks if the DB is
      # accepting connections.
      test: ["CMD-SHELL", "pg_isready -U user -d deltav_db"]
      interval: 5s                     # Check every 5 seconds
      timeout: 3s                      # Give up after 3 seconds per check
      retries: 5                       # Fail after 5 unsuccessful checks

  # ---------------------------------------------------------------------------
  # Python Backend (FastAPI)
  # ---------------------------------------------------------------------------
  # The API server. Handles authentication, business logic, and database access.
  backend:
    build:
      context: ./backend               # Build from the backend/ directory
      dockerfile: Dockerfile
    env_file:
      - .env                           # Passes DATABASE_URL, etc. to the container
    volumes:
      - ./backend:/app                 # Mount local code into the container so edits
                                       # are reflected immediately (hot-reload via uvicorn)
    ports:
      - "8000:8000"                    # Direct access to the API (bypassing nginx)
    depends_on:
      db:
        condition: service_healthy     # Wait for the DB healthcheck to pass before starting

  # ---------------------------------------------------------------------------
  # React Frontend (Vite)
  # ---------------------------------------------------------------------------
  # The UI. Vite serves the React app with hot module replacement (HMR) so
  # changes appear in the browser instantly without a full page refresh.
  frontend:
    build:
      context: ./frontend
      dockerfile: Dockerfile
    env_file:
      - .env
    volumes:
      - ./frontend:/app               # Mount local code for hot-reload
      - /app/node_modules              # Anonymous volume: keeps container's node_modules
                                       # separate from the host mount. Without this, the
                                       # host's (possibly empty) node_modules would overwrite
                                       # the container's installed packages.
    environment:
      - WATCHPACK_POLLING=true         # Forces file-polling for change detection.
                                       # Needed because Docker's filesystem events don't
                                       # always propagate to the container on macOS/Windows.

  # ---------------------------------------------------------------------------
  # Nginx Reverse Proxy
  # ---------------------------------------------------------------------------
  # The single entry point for the browser. Routes requests to the right service:
  #   /api/*  -->  backend (FastAPI)
  #   /*      -->  frontend (Vite/React)
  #
  # This means the frontend and backend share one origin (localhost:3000),
  # which avoids CORS issues.
  proxy:
    image: nginx:alpine
    ports:
      - "3000:3000"                    # The only port you open in your browser
    volumes:
      - ./proxy/nginx.conf:/etc/nginx/conf.d/default.conf:ro  # :ro = read-only mount
    depends_on:
      - backend
      - frontend

# Named volumes persist data even if containers are destroyed.
# To wipe the database: docker compose down -v
volumes:
  postgres_data: