diff --git a/CLAUDE.md b/CLAUDE.md
index 96ad0ac..4ae5a9e 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -6,6 +6,18 @@ Visualizes a codebase's function call graph as draggable Blueprint-style cards.
Run from the repo root unless noted. Dev machine is Windows; both PowerShell and Git Bash work.
+```sh
+# Preferred: Docker Compose (no local venv or node_modules to manage)
+docker compose up # backend on :8000 (--reload), frontend on :5173 (HMR)
+docker compose up --build # after changing backend/requirements.txt or frontend/package.json
+```
+
+`compose.yaml` and `backend/Dockerfile.dev` / `frontend/Dockerfile.dev` are dev-only — they're
+unrelated to the root `Dockerfile` used for the Render deploy (see CI/CD below).
+
+
+Fallback: running without Docker
+
```sh
# Backend (Python 3.10+; CI and Docker use 3.11)
pip install -r backend/requirements.txt
@@ -22,13 +34,15 @@ npm run lint # oxlint
python -m backend.analyzer sample_project
```
+
+
## Verifying a change
There is **no test suite**. Verify by hand:
-- Frontend: `npm run build` and `npm run lint` in `frontend/`.
-- Backend: start uvicorn and `GET /api/health`.
-- Analyzer or language-plugin changes: run `python -m backend.analyzer` on `sample_project`, `sample_rust_project` and `sample_typescript_project` before and after, and compare function and edge counts. An unexplained drop in edges is a regression.
+- Frontend: `docker compose exec frontend npm run build` and `docker compose exec frontend npm run lint` (or run them in `frontend/` without Docker).
+- Backend: with `docker compose up` running, `GET localhost:8000/api/health`.
+- Analyzer or language-plugin changes: `docker compose exec backend python -m backend.analyzer ` on `sample_project`, `sample_rust_project` and `sample_typescript_project` before and after, and compare function and edge counts. An unexplained drop in edges is a regression.
CI (`.github/workflows/pr-checks.yml`) only runs the frontend build and the backend health check. It does not lint and does not exercise the analyzer, so green CI says little about analysis correctness.
diff --git a/backend/.dockerignore b/backend/.dockerignore
new file mode 100644
index 0000000..7a60b85
--- /dev/null
+++ b/backend/.dockerignore
@@ -0,0 +1,2 @@
+__pycache__/
+*.pyc
diff --git a/backend/Dockerfile.dev b/backend/Dockerfile.dev
new file mode 100644
index 0000000..46229e8
--- /dev/null
+++ b/backend/Dockerfile.dev
@@ -0,0 +1,6 @@
+FROM python:3.11-slim
+WORKDIR /app
+COPY requirements.txt ./
+RUN pip install --no-cache-dir -r requirements.txt
+EXPOSE 8000
+CMD ["uvicorn", "backend.main:app", "--reload", "--reload-dir", "backend", "--host", "0.0.0.0", "--port", "8000"]
diff --git a/compose.yaml b/compose.yaml
new file mode 100644
index 0000000..9c8325a
--- /dev/null
+++ b/compose.yaml
@@ -0,0 +1,24 @@
+services:
+ backend:
+ build:
+ context: ./backend
+ dockerfile: Dockerfile.dev
+ volumes:
+ - .:/app
+ ports:
+ - "8000:8000"
+
+ frontend:
+ build:
+ context: ./frontend
+ dockerfile: Dockerfile.dev
+ volumes:
+ - ./frontend:/app
+ - frontend_node_modules:/app/node_modules
+ ports:
+ - "5173:5173"
+ environment:
+ - VITE_USE_POLLING=true
+
+volumes:
+ frontend_node_modules:
diff --git a/frontend/.dockerignore b/frontend/.dockerignore
new file mode 100644
index 0000000..b947077
--- /dev/null
+++ b/frontend/.dockerignore
@@ -0,0 +1,2 @@
+node_modules/
+dist/
diff --git a/frontend/.oxlintrc.json b/frontend/.oxlintrc.json
index 6fa991d..980fe9a 100644
--- a/frontend/.oxlintrc.json
+++ b/frontend/.oxlintrc.json
@@ -1,6 +1,7 @@
{
"$schema": "./node_modules/oxlint/configuration_schema.json",
"plugins": ["react", "typescript", "oxc"],
+ "ignorePatterns": ["node_modules", "dist"],
"rules": {
"react/rules-of-hooks": "error",
"react/only-export-components": ["warn", { "allowConstantExport": true }]
diff --git a/frontend/Dockerfile.dev b/frontend/Dockerfile.dev
new file mode 100644
index 0000000..5719c83
--- /dev/null
+++ b/frontend/Dockerfile.dev
@@ -0,0 +1,6 @@
+FROM node:20-alpine
+WORKDIR /app
+COPY package.json package-lock.json ./
+RUN npm ci
+EXPOSE 5173
+CMD ["npm", "run", "dev", "--", "--host", "0.0.0.0"]
diff --git a/frontend/vite.config.ts b/frontend/vite.config.ts
index 26d1dc3..6b47319 100644
--- a/frontend/vite.config.ts
+++ b/frontend/vite.config.ts
@@ -6,4 +6,9 @@ export default defineConfig({
// Render serves dist/ at "/"; GitHub Pages serves it under "/function-viewer/" (set via VITE_BASE_PATH).
base: process.env.VITE_BASE_PATH ?? '/',
plugins: [react()],
+ server: {
+ // Docker Desktop bind mounts don't reliably forward native FS change events; polling
+ // is what makes HMR work for the frontend dev container (see compose.yaml).
+ watch: process.env.VITE_USE_POLLING ? { usePolling: true } : undefined,
+ },
})