Add docker-compose.dev.yml hot reload (Mongo, uvicorn --reload, Vite); SERVE_FRONTEND_STATIC; API_PROXY_TARGET

.env.example

@@ -10,6 +10,9 @@ ACCESS_TOKEN_EXPIRE_MINUTES=10080
 
 CORS_ORIGINS=http://localhost:5173,http://localhost:3000
 
+# Set to false when using Vite dev server (hot reload); API then skips serving frontend/dist.
+# SERVE_FRONTEND_STATIC=true
+
 # Optional Google Sheets (service account JSON path or raw JSON in env)
 # GOOGLE_SERVICE_ACCOUNT_FILE=
 # GOOGLE_SERVICE_ACCOUNT_JSON=

Dockerfile.backend-dev

@@ -0,0 +1,9 @@
+# Python API only — source mounted at runtime for uvicorn --reload (see docker-compose.dev.yml)
+FROM python:3.12-slim-bookworm
+RUN apt-get update && apt-get install -y --no-install-recommends ffmpeg \
+    && rm -rf /var/lib/apt/lists/*
+WORKDIR /app/backend
+COPY backend/requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+ENV PYTHONPATH=/app/backend
+EXPOSE 8000

README.md

@@ -8,27 +8,45 @@ Recruitment and tooling site for **non-technical** CU students joining a Collabo
 - **Backend:** FastAPI, Motor (MongoDB), Google Gemini API (`GEMINI_API_KEY`)
 - **Deploy:** Docker (single image: API + static SPA); suitable for Hugging Face Spaces or any container host
 
-## Local development
+## Local development (hot reload)
 
-1. **MongoDB** — install locally or use Docker only for DB:
+### Option A — Docker Compose (matches other Neon demos: Mongo + API reload + Vite HMR)
 
-   ```bash
-   docker compose up mongo
-   ```
+From the repo root, with `.env` configured (at least `GEMINI_API_KEY`, `JWT_SECRET_KEY`):
+
+```bash
+docker compose -f docker-compose.dev.yml up --build
+```
+
+| Service | URL | Notes |
+|--------|-----|--------|
+| **UI (Vite)** | http://localhost:5173 | Hot reload (HMR); proxies `/api` → backend |
+| **API** | http://localhost:8000 | `uvicorn --reload`; OpenAPI at http://localhost:8000/docs |
+| **MongoDB** | localhost:27017 | Data volume `cu_student_mongo_dev` |
+
+The dev stack sets `SERVE_FRONTEND_STATIC=false` so FastAPI does **not** serve `frontend/dist` and you always use the Vite dev server. The frontend container sets `CHOKIDAR_USEPOLLING=true` so file watches work on Docker Desktop (Windows/macOS).
+
+PowerShell:
+
+```powershell
+docker compose -f docker-compose.dev.yml up --build
+```
+
+### Option B — Processes on your machine (no API container)
+
+1. **MongoDB** — e.g. `docker compose -f docker-compose.dev.yml up mongo -d` or a local MongoDB on `27017`.
 
-2. **Backend** — from repo root:
+2. **Backend** — repo root `.env` should include `SERVE_FRONTEND_STATIC=false` (or omit `frontend/dist` so static is not mounted). Then:
 
    ```bash
    cd backend
    python -m venv .venv
    .venv\Scripts\activate   # Windows
    pip install -r requirements.txt
-   copy ..\.env.example .env   # or copy to repo root; config loads either
-   # Set GEMINI_API_KEY, JWT_SECRET_KEY, MONGODB_URL=mongodb://localhost:27017
    uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
    ```
 
-3. **Frontend** — separate terminal:
+3. **Frontend** — second terminal:
 
    ```bash
    cd frontend
@@ -36,9 +54,9 @@ Recruitment and tooling site for **non-technical** CU students joining a Collabo
    npm run dev
    ```
 
-   Vite proxies `/api` to `http://127.0.0.1:8000`. Open `http://localhost:5173`.
+   Open http://localhost:5173 — Vite proxies `/api` to `http://127.0.0.1:8000`.
 
-Without a built `frontend/dist`, the API still serves OpenAPI at `/docs`. After `npm run build`, run uvicorn from repo root context so `frontend/dist` exists — or use Docker below.
+Without mounting static, the API exposes OpenAPI at `/docs` on port 8000.
 
 ## Configuration
 
@@ -51,6 +69,7 @@ See [.env.example](.env.example). Important variables:
 | `MONGODB_URL` / `MONGODB_DB` | User accounts and saved drafts |
 | `JWT_SECRET_KEY` | Sign auth tokens |
 | `CORS_ORIGINS` | Frontend origins (dev: `http://localhost:5173`) |
+| `SERVE_FRONTEND_STATIC` | `true` (default): serve `frontend/dist` from FastAPI. `false`: use Vite dev server only (hot reload). |
 | `GOOGLE_*` / SMTP | Optional submission pipeline (see `app/routers/submit.py`) |
 
 **Speech:** Mic input is sent to `POST /api/transcribe` (Gemini multimodal). “Read aloud” uses the browser **Web Speech API** (no extra key).

backend/app/config.py

@@ -1,5 +1,7 @@
 from pathlib import Path
+from typing import Any
 
+from pydantic import field_validator
 from pydantic_settings import BaseSettings, SettingsConfigDict
 
 # backend/app/config.py -> parents: app, backend, repo root
@@ -27,10 +29,30 @@ class Settings(BaseSettings):
     access_token_expire_minutes: int = 60 * 24 * 7
 
     cors_origins: str = (
-        "http://localhost:5173,http://localhost:3000,"
+        "http://localhost:5173,http://127.0.0.1:5173,"
+        "http://localhost:3000,"
         "http://localhost:7860,http://127.0.0.1:7860"
     )
 
+    # When false, API does not mount frontend/dist — use Vite dev server (hot reload) on :5173.
+    serve_frontend_static: bool = True
+
+    @field_validator("serve_frontend_static", mode="before")
+    @classmethod
+    def _coerce_serve_static(cls, v: Any) -> bool:
+        if isinstance(v, bool):
+            return v
+        if v is None:
+            return True
+        if isinstance(v, str):
+            s = v.strip().lower()
+            if s in ("0", "false", "no", "off"):
+                return False
+            if s in ("1", "true", "yes", "on"):
+                return True
+            return True
+        return bool(v)
+
     google_service_account_file: str | None = None
     google_service_account_json: str | None = None
     google_spreadsheet_id: str | None = None

backend/app/main.py

@@ -24,8 +24,9 @@ async def lifespan(app: FastAPI):
     get_client().close()
 
 
-_docs = None if FRONTEND_DIST.is_dir() else "/docs"
-_redoc = None if FRONTEND_DIST.is_dir() else "/redoc"
+_should_mount_static = settings.serve_frontend_static and FRONTEND_DIST.is_dir()
+_docs = None if _should_mount_static else "/docs"
+_redoc = None if _should_mount_static else "/redoc"
 
 app = FastAPI(
     title="CU Student AI Project Helper",
@@ -58,5 +59,5 @@ async def health():
     }
 
 
-if FRONTEND_DIST.is_dir():
+if _should_mount_static:
     app.mount("/", StaticFiles(directory=str(FRONTEND_DIST), html=True), name="static")

docker-compose.dev.yml

@@ -0,0 +1,67 @@
+# Hot reload: Mongo + FastAPI (uvicorn --reload) + Vite dev server.
+# Usage: docker compose -f docker-compose.dev.yml up
+# App UI: http://localhost:5173  |  API: http://localhost:8000  |  /docs when static is off
+
+name: cu-student-helper-dev
+
+services:
+  mongo:
+    image: mongo:7
+    ports:
+      - "27017:27017"
+    volumes:
+      - cu_student_mongo_dev:/data/db
+
+  api:
+    build:
+      context: .
+      dockerfile: Dockerfile.backend-dev
+    ports:
+      - "8000:8000"
+    env_file:
+      - .env
+    environment:
+      MONGODB_URL: mongodb://mongo:27017
+      SERVE_FRONTEND_STATIC: "false"
+      CORS_ORIGINS: http://localhost:5173,http://127.0.0.1:5173,http://localhost:8000,http://127.0.0.1:8000
+    volumes:
+      - ./backend:/app/backend
+    command:
+      [
+        "uvicorn",
+        "app.main:app",
+        "--host",
+        "0.0.0.0",
+        "--port",
+        "8000",
+        "--reload",
+        "--reload-dir",
+        "/app/backend/app",
+      ]
+    depends_on:
+      - mongo
+
+  frontend:
+    image: node:20-bookworm
+    working_dir: /app/frontend
+    ports:
+      - "5173:5173"
+    volumes:
+      - ./frontend:/app/frontend
+      - frontend_node_modules:/app/frontend/node_modules
+    environment:
+      CHOKIDAR_USEPOLLING: "true"
+      WATCHPACK_POLLING: "true"
+      API_PROXY_TARGET: http://api:8000
+    command:
+      [
+        "sh",
+        "-c",
+        "test -d node_modules/react || npm ci; npm run dev -- --host 0.0.0.0 --port 5173",
+      ]
+    depends_on:
+      - api
+
+volumes:
+  cu_student_mongo_dev:
+  frontend_node_modules:

frontend/vite.config.ts

@@ -1,13 +1,21 @@
 import { defineConfig } from 'vite'
 import react from '@vitejs/plugin-react'
 
+// In Docker Compose dev, API_PROXY_TARGET=http://api:8000 (Vite proxies /api → backend).
+// Local (no Docker): default http://127.0.0.1:8000
+const apiProxy = process.env.API_PROXY_TARGET || 'http://127.0.0.1:8000'
+
 export default defineConfig({
   plugins: [react()],
   server: {
     port: 5173,
+    strictPort: true,
+    watch: {
+      usePolling: process.env.CHOKIDAR_USEPOLLING === 'true',
+    },
     proxy: {
       '/api': {
-        target: 'http://127.0.0.1:8000',
+        target: apiProxy,
         changeOrigin: true,
       },
     },

scripts/dev-docker.ps1

@@ -0,0 +1,7 @@
+# Hot-reload stack: Mongo + uvicorn --reload + Vite — http://localhost:5173
+Set-Location (Join-Path $PSScriptRoot '..')
+if ($args.Count -eq 0) {
+  docker compose -f docker-compose.dev.yml up --build
+} else {
+  docker compose -f docker-compose.dev.yml @args
+}