feat: fold frontend dashboard into the monorepo

.dockerignore

@@ -7,3 +7,6 @@ __pycache__
 *.py[cod]
 argus.db
 *.db
+frontend/node_modules
+frontend/.next
+frontend/out

.github/workflows/ci.yml

@@ -37,3 +37,44 @@ jobs:
         uses: codecov/codecov-action@v7
         with:
           files: coverage.xml
+
+  frontend:
+    name: Frontend
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+
+      - name: Set up Node
+        uses: actions/setup-node@v5
+        with:
+          node-version: "22"
+
+      - name: Enable corepack
+        run: corepack enable
+
+      - name: Install dependencies
+        working-directory: frontend
+        run: pnpm install --frozen-lockfile
+
+      - name: Lint
+        working-directory: frontend
+        run: pnpm lint
+
+      # Scoped to the "unit" vitest project only — the Storybook/Playwright
+      # browser-based component tests require installing a browser and are
+      # deliberately left as a local-only check for now.
+      - name: Test
+        working-directory: frontend
+        run: pnpm test:coverage
+
+      - name: Upload coverage report
+        uses: codecov/codecov-action@v7
+        with:
+          files: frontend/coverage/lcov.info
+          flags: frontend
+
+      - name: Build
+        working-directory: frontend
+        run: pnpm build

.gitignore

@@ -14,3 +14,13 @@ dist/
 .claude/
 CLAUDE.md
 AGENTS.md
+
+# Built frontend, copied into the backend package at build time
+src/argus/dashboard/frontend/
+
+# Superpowers scratch workspaces (SDD ledgers, brainstorm mockups) — local only
+.superpowers/
+
+# Superpowers specs/plans — useful during active design/implementation,
+# not worth keeping once the work they describe has landed
+docs/superpowers/

Dockerfile

@@ -1,3 +1,15 @@
+FROM node:22-slim AS frontend-build
+
+WORKDIR /frontend
+RUN corepack enable && corepack prepare pnpm@10.33.0 --activate
+
+COPY frontend/package.json frontend/pnpm-lock.yaml frontend/pnpm-workspace.yaml ./
+RUN pnpm install --frozen-lockfile
+
+COPY frontend ./
+RUN pnpm build
+
+
 FROM python:3.12-slim-bookworm
 
 LABEL org.opencontainers.image.source="https://github.com/sciwork/argus"
@@ -9,6 +21,7 @@ WORKDIR /app
 
 COPY pyproject.toml README.md ./
 COPY src ./src
+COPY --from=frontend-build /frontend/out ./src/argus/dashboard/frontend
 
 RUN pip install --no-cache-dir .
 

README.md

@@ -68,7 +68,7 @@ URL: `https://your-domain/webhook/kktix/sprint`, env var: `DISCORD_WEBHOOK_SPRIN
 A Google-OAuth-protected web UI for viewing per-event registration time series.
 
 - **Event list:** `/dashboard`
-- **Per-event chart:** `/dashboard/events/{slug}` — line chart of Total + each ticket type, with capacity (horizontal dashed) and event start (vertical dashed) reference lines.
+- **Per-event chart:** `/dashboard/events?slug=<slug>` — line chart of Total + each ticket type, with capacity (horizontal dashed) and event start (vertical dashed) reference lines.
 
 ### One-time Google OAuth setup
 
@@ -87,8 +87,11 @@ A Google-OAuth-protected web UI for viewing per-event registration time series.
 
 ### Try it locally
 
+The dashboard UI is a Next.js app (`frontend/`) built to static files and served same-origin by the backend. `uvicorn` alone won't serve it in a fresh checkout — build the frontend first (or use the `next dev` proxy workflow), see [Development](#development) below.
+
 ```bash
 set -a && source .env && set +a
+cd frontend && pnpm install && pnpm build && cd ..   # one-time (or after frontend changes)
 uv run uvicorn argus.main:app --host 0.0.0.0 --port 8000
 # open http://localhost:8000/dashboard
 ```
@@ -100,6 +103,7 @@ You will be redirected to Google to sign in. Only emails in `ALLOWED_EMAILS` are
 When deploying (e.g. to Railway):
 
 - **Railway builds the Dockerfile** using `python:3.12-slim-bookworm`, installs the package with `pip install .`, and starts uvicorn via `railway.json` `startCommand`. Railway injects `$PORT` and the start command binds to it.
+- **The frontend build is automatic** — the Dockerfile's first stage builds `frontend/` (`pnpm install && pnpm build`) and copies its static export into `src/argus/dashboard/frontend/` before the Python stage installs the package. No manual frontend build step is needed for Docker/Railway deploys.
 - **For SQLite, mount a persistent volume** at `/data` and set `DATABASE_URL=sqlite:////data/argus.db`. SQLite written to the container's local filesystem will be wiped on every redeploy.
 - **`SESSION_SECRET` is required** — the app refuses to boot without it. Generate with `python -c "import secrets; print(secrets.token_hex(32))"`.
 - **Port:** the Dockerfile's `CMD` binds to a fixed port 8000. Railway overrides this via `railway.json`'s `startCommand`, which substitutes its injected `$PORT`. To change the port in non-Railway environments, override the container command (e.g. `docker run … argus-image uvicorn argus.main:app --host 0.0.0.0 --port 9000`).
@@ -124,3 +128,27 @@ uv run ruff format src tests      # format
 # Visual inspection of Discord report (sends a real webhook):
 ARGUS_MANUAL_TEST=1 uv run pytest tests/test_discord_format_manual.py -v -s
 ```
+
+### Frontend (`frontend/`)
+
+The dashboard UI lives in `frontend/` — a Next.js app using `pnpm` (not `npm`), statically exported (`next build`) into `src/argus/dashboard/frontend/`, and served same-origin by the backend under `/dashboard` (no separate frontend server or CORS setup in production). This copy step happens automatically in Docker's multi-stage build; locally you have two options:
+
+1. **Build once, run `uvicorn` normally** — full same-origin experience, matches production:
+   ```bash
+   cd frontend && pnpm install && pnpm build && cd ..
+   uv run uvicorn argus.main:app --host 0.0.0.0 --port 8000
+   # open http://localhost:8000/dashboard
+   ```
+   Re-run `pnpm build` after frontend changes to see them.
+
+2. **`next dev` + dev proxy** — for active frontend development with hot reload, run both processes side by side:
+   ```bash
+   # terminal 1
+   uv run uvicorn argus.main:app --host 0.0.0.0 --port 8000
+   # terminal 2
+   cd frontend && pnpm install && pnpm dev
+   # open http://localhost:3000/dashboard
+   ```
+   `frontend/next.config.ts` proxies `/dashboard/api/*` calls from the `next dev` server (port 3000) to `uvicorn` (port 8000), so no CORS configuration is needed.
+
+Other frontend commands (run from `frontend/`): `pnpm lint`, `pnpm test` (vitest unit/component tests), `pnpm exec tsc --noEmit`.

SPEC.md

@@ -53,9 +53,10 @@ Argus uses a **vertical slice** layout: each feature owns its full stack (HTTP r
 | `GET` | `/dashboard/login` | — | Start Google OAuth flow | [Dashboard](#dashboard) |
 | `GET` | `/dashboard/oauth/callback` | — | OAuth redirect target | [Dashboard](#dashboard) |
 | `GET` | `/dashboard/logout` | — | Clear session, redirect to login | [Dashboard](#dashboard) |
-| `GET` | `/dashboard` | session (HTML) | Event list page | [Dashboard](#dashboard) |
-| `GET` | `/dashboard/events/{slug}` | session (HTML) | Per-event chart page | [Dashboard](#dashboard) |
-| `GET` | `/dashboard/webhook-logs` | session (HTML) | Webhook log viewer page | [Dashboard](#dashboard) |
+| `GET` | `/dashboard` | public (shell) | Event list page (static Next.js export) | [Dashboard](#dashboard) |
+| `GET` | `/dashboard/events` | public (shell) | Per-event chart page, `?slug=<slug>` (static Next.js export) | [Dashboard](#dashboard) |
+| `GET` | `/dashboard/webhook-logs` | public (shell) | Webhook log viewer page (static Next.js export) | [Dashboard](#dashboard) |
+| `GET` | `/dashboard/api/me` | session (401) | JSON: currently authenticated user | [Dashboard](#dashboard) |
 | `GET` | `/dashboard/api/events` | session (401) | JSON: event list | [Dashboard](#dashboard) |
 | `GET` | `/dashboard/api/events/{slug}/timeseries` | session (401) | JSON: per-event time series | [Dashboard](#dashboard) |
 | `DELETE` | `/dashboard/api/events/{slug}` | session (401) | Permanently delete event + its tickets | [Dashboard](#dashboard) |
@@ -66,6 +67,7 @@ Argus uses a **vertical slice** layout: each feature owns its full stack (HTTP r
 
 **Auth column legend:**
 - `x-kktix-secret header` — request must include header matching `WEBHOOK_SECRET` (constant-time compared)
+- `public (shell)` — served with no server-side session check at all; the page itself is a public static shell, and it protects its own data by calling `/dashboard/api/*` routes, which each require the session cookie client-side (a request without a valid session gets a 401 from those API calls, not from the page)
 - `session (HTML)` — protected by signed session cookie; missing/invalid → 302 to `/dashboard/login`
 - `session (401)` — same protection but JSON routes return 401 instead of redirecting
 
@@ -91,10 +93,9 @@ argus/
 │       │   ├── __init__.py
 │       │   ├── router.py         # /dashboard/* routes
 │       │   ├── queries.py        # time series queries
-│       │   └── templates/
-│       │       ├── _base.html    # shared layout
-│       │       ├── index.html    # event list
-│       │       └── event.html    # per-event chart
+│       │   └── frontend/         # built Next.js static export, copied in at
+│       │                         # build time (gitignored); served by main.py's
+│       │                         # StaticFiles mount at /dashboard
 │       │
 │       │   # ── shared infrastructure ──
 │       ├── auth.py               # OAuth client + require_login dependency (reusable)
@@ -113,6 +114,8 @@ argus/
 │   ├── conftest.py
 │   ├── test_*.py                 # automated tests
 │   └── test_discord_format_manual.py  # opt-in test that sends real Discord webhooks
+├── frontend/                     # Next.js dashboard UI (source); builds into
+│                                  # src/argus/dashboard/frontend/ (see above)
 ├── .env.example
 ├── pyproject.toml
 ├── railway.json
@@ -391,19 +394,19 @@ A web UI that visualizes registration trends per event over time. Implemented as
 
 ### Routes
 
-See [API Reference](#api-reference) for the canonical list. All routes under `/dashboard/*` (except `login` and `oauth/callback`) require an authenticated session. HTML routes redirect to `/dashboard/login` on failure; JSON API routes return `401`.
+See [API Reference](#api-reference) for the canonical list. The dashboard UI itself is a statically-exported Next.js app served same-origin under `/dashboard`, `/dashboard/events`, and `/dashboard/webhook-logs` — these three pages are public shells with no server-side session check; each gates its own content client-side by calling `/dashboard/api/me` (and other `/dashboard/api/*` routes) and redirecting to `/dashboard/login` in the browser if that call 401s. Every `/dashboard/api/*` route requires the session cookie and returns `401` if it's missing or invalid.
 
 ### Authentication
 
 Server-side OAuth 2.0 with Google as the identity provider. After successful OAuth, the user's email is checked against `ALLOWED_EMAILS`. If allowed, a signed session cookie is set.
 
 **Flow:**
 
-1. Visit `/dashboard` (or any protected route) without session → 302 to `/dashboard/login`
+1. Visit `/dashboard` without a session → the static shell loads, its client-side `/dashboard/api/me` call 401s, and the browser is redirected to `/dashboard/login`
 2. `/dashboard/login` → 302 to Google consent screen
 3. Google → `/dashboard/oauth/callback?code=...`
 4. Backend exchanges code for `id_token`, verifies email is in `ALLOWED_EMAILS`
-5. On success: session cookie written, 302 to original destination (or `/dashboard`)
+5. On success: session cookie written, 302 to `/dashboard`
 6. On rejection: 403 page
 
 Session is signed using `SESSION_SECRET` via Starlette's `SessionMiddleware`.