Merge remote-tracking branch 'origin/main' into frontend-eslint

# Conflicts:
#	.github/workflows/ci.yml
#	README.md

Author: ambv

.github/workflows/ci.yml

@@ -6,6 +6,41 @@ on:
   pull_request:
 
 jobs:
+  check-lockfile:
+    name: Check backend lockfile is up to date
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Ensure lockfiles are updated when .in files change
+        run: |
+          BASE=${{ github.event.pull_request.base.sha }}
+          HEAD=${{ github.event.pull_request.head.sha }}
+          CHANGED=$(git diff --name-only "$BASE" "$HEAD")
+          FAIL=0
+          if echo "$CHANGED" | grep -q 'backend/requirements\.in$'; then
+            if ! echo "$CHANGED" | grep -q 'backend/requirements\.txt$'; then
+              echo "::error::backend/requirements.in was modified but backend/requirements.txt was not."
+              FAIL=1
+            fi
+            if ! echo "$CHANGED" | grep -q 'backend/requirements-dev\.txt$'; then
+              echo "::error::backend/requirements.in was modified but backend/requirements-dev.txt was not."
+              FAIL=1
+            fi
+          fi
+          if echo "$CHANGED" | grep -q 'backend/requirements-dev\.in$'; then
+            if ! echo "$CHANGED" | grep -q 'backend/requirements-dev\.txt$'; then
+              echo "::error::backend/requirements-dev.in was modified but backend/requirements-dev.txt was not."
+              FAIL=1
+            fi
+          fi
+          if [ "$FAIL" -eq 1 ]; then
+            echo "::error::Please run pip-compile to regenerate lockfiles. See README for instructions."
+            exit 1
+          fi
+
   frontend-lint:
     name: Frontend Lint & Typecheck
     runs-on: ubuntu-latest

README.md

@@ -13,30 +13,24 @@ This project consists of three main components:
 ## Quick Start
 
 ### Prerequisites
-- Python 3.8+
-- Node.js 16+
-- CPython source repository (for benchmarking)
+- Docker Engine 20.10+ and Docker Compose 2.0+
+- CPython source repository (for benchmarking with the worker)
 
 ### Setup & Installation
 ```bash
-# Install all dependencies and set up database
-make setup
+# Copy environment config
+cp .env.example .env
 
-# Or install components separately
-make install          # Install frontend + backend dependencies
-make init-db         # Initialize SQLite database
-make populate-db     # Add mock data for development
+# Build and start all services
+docker compose -f docker-compose.dev.yml up --build
 ```
 
 ### Development
-```bash
-# Start both frontend and backend servers
-make dev
 
-# Or start them individually
-make dev-frontend    # Frontend on http://localhost:9002
-make dev-backend     # Backend API on http://localhost:8000
-```
+Services start automatically with hot reload:
+- Frontend: http://localhost:9002
+- Backend API: http://localhost:8000
+- API Documentation: http://localhost:8000/api/docs
 
 ## Development Commands
 
@@ -53,16 +47,23 @@ npm run typecheck           # TypeScript type checking
 
 Both checks run in CI on pushes to `main` and on pull requests.
 
-### Database Management
+### Populating Mock Data
 ```bash
-make reset-db               # Drop and recreate database with fresh data
-make populate-db           # Add mock benchmark data
+docker compose -f docker-compose.dev.yml exec backend python scripts/populate_db.py
 ```
 
-### Production
+### Updating Backend Dependencies
 ```bash
-make build                  # Build frontend for production
-make clean                  # Clean up generated files and caches
+# Edit backend/requirements.in, then regenerate both lockfiles:
+docker run --rm -v "$(pwd)/backend:/app" -w /app python:3.13-slim-bookworm \
+  sh -c "pip install --quiet pip-tools && \
+  pip-compile --strip-extras --generate-hashes \
+    --output-file requirements.txt requirements.in && \
+  pip-compile --strip-extras --generate-hashes \
+    --output-file requirements-dev.txt requirements-dev.in"
+
+# Rebuild the backend container:
+docker compose -f docker-compose.dev.yml up --build -d backend
 ```
 
 ## Worker Setup
@@ -98,10 +99,30 @@ memory-tracker benchmark /path/to/cpython HEAD~5..HEAD \
 
 ```bash
 # Development with hot reload
-docker-compose -f docker-compose.dev.yml up
+docker compose -f docker-compose.dev.yml up
 
 # Production deployment
-docker-compose up
+docker compose up
+```
+
+## Local Development (not recommended)
+
+Running services directly on the host is possible but not recommended.
+Docker Compose ensures consistent Python/Node versions, database setup,
+and dependency isolation across all platforms.
+
+### Prerequisites
+- Python 3.13+
+- Node.js 20+
+
+```bash
+make setup        # Install deps, init DB, populate mock data
+make dev          # Start frontend + backend with hot reload
+make test         # Run backend tests
+make reset-db     # Drop and recreate database with fresh data
+make populate-db  # Populate the DB with mock data
+make build        # Build frontend for production
+make clean        # Clean up generated files and caches
 ```
 
 ## Usage Examples
@@ -137,7 +158,7 @@ memory-tracker benchmark ~/cpython HEAD~10..HEAD \
 ## Contributing
 
 1. Follow the existing code style and conventions
-2. Run tests before committing: `make test`
+2. Run tests before committing
 3. Use TypeScript for all frontend code
 4. Follow the repository patterns for new features
 5. Never commit secrets or authentication tokens

backend/Dockerfile

@@ -12,9 +12,6 @@ RUN apt-get update && apt-get install -y \
 # Copy requirements first to leverage Docker layer caching
 COPY requirements.txt .
 
-# Install PostgreSQL adapter
-RUN pip install --no-cache-dir asyncpg psycopg2-binary
-
 # Install Python dependencies
 RUN pip install --no-cache-dir -r requirements.txt
 

backend/Dockerfile.dev

@@ -1,4 +1,4 @@
-FROM python:3.11-slim
+FROM python:3.13-slim-bookworm
 
 WORKDIR /app
 
@@ -7,10 +7,10 @@ RUN apt-get update && apt-get install -y \
     gcc \
     && rm -rf /var/lib/apt/lists/*
 
-COPY requirements.txt .
+COPY requirements-dev.txt .
 
-# Install Python dependencies
-RUN pip install --no-cache-dir -r requirements.txt
+# Install Python dependencies (dev lockfile includes test tooling)
+RUN pip install --no-cache-dir -r requirements-dev.txt
 
 # The source code will be mounted as a volume, so we don't copy it here
 

backend/requirements-dev.in

@@ -0,0 +1,3 @@
+-r requirements.in
+pytest
+pytest-asyncio