feat(m0): bootstrap repo, design system, compose stack

- Repo scaffolding: .gitignore, .env.example, Makefile, docker-compose.yml, README.md, CHANGELOG.md, pre-commit config. - Three-service stack: api (Flask 3), db (postgres:16-alpine), front (nginx serving the Vite bundle). Named volumes metamorph_db + metamorph_evidence. - Backend skeleton: Flask app factory, JSON structured logging on stdout, GET /api/v1/health, multi-stage Dockerfile, pyproject.toml driven by uv, Pydantic Settings with secret guard rails (refuses to boot in non-dev with placeholders), APP_ENV gating. - Frontend skeleton: Vite + React 18 + TypeScript strict + TailwindCSS, RTOps design tokens from tasks/design.md, self-hosted JetBrains Mono / IBM Plex Sans via @fontsource, base UI primitives (Card/Tag/SectionHeader/FlowNode/ Button), home page wired to /api/v1/health. - Engine-agnostic Makefile: auto-detects docker or podman, picks the matching compose driver. Targets: up/down/build/rebuild/dev/lint/fmt/test/migrate/ seed-mitre/print-install-token/e2e/inspect-health. - Playwright suite: e2e/tests/m0-smoke.spec.ts (8 tests) + HTML + JUnit reports + traces on retry. - Docs: tasks/spec.md (finalized after Q&A), tasks/design.md, tasks/todo.md (14 milestones), tasks/testing-m0.md, tasks/lessons.md. DoD: make up + make health + make e2e all pass on podman 5.x (Fedora) and docker. TLS terminated by external reverse proxy (spec §6 NF-network). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-11 06:16:00 +02:00
commit f1fdf27012
58 changed files with 5365 additions and 0 deletions
--- a/frontend/.dockerignore
+++ b/frontend/.dockerignore
@@ -0,0 +1,7 @@
+node_modules
+dist
+.vite
+*.log
+.env
+.env.*
+!.env.example
--- a/frontend/.eslintrc.cjs
+++ b/frontend/.eslintrc.cjs
@@ -0,0 +1,18 @@
+/* eslint-env node */
+module.exports = {
+  root: true,
+  env: { browser: true, es2022: true },
+  extends: [
+    'eslint:recommended',
+    'plugin:@typescript-eslint/recommended',
+    'plugin:react-hooks/recommended',
+  ],
+  ignorePatterns: ['dist', '.eslintrc.cjs', 'node_modules'],
+  parser: '@typescript-eslint/parser',
+  parserOptions: { ecmaVersion: 'latest', sourceType: 'module' },
+  plugins: ['react-refresh'],
+  rules: {
+    'react-refresh/only-export-components': ['warn', { allowConstantExport: true }],
+    '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
+  },
+};
--- a/frontend/.prettierrc
+++ b/frontend/.prettierrc
@@ -0,0 +1,8 @@
+{
+  "singleQuote": true,
+  "semi": true,
+  "trailingComma": "all",
+  "printWidth": 100,
+  "tabWidth": 2,
+  "arrowParens": "always"
+}
--- a/frontend/Dockerfile
+++ b/frontend/Dockerfile
@@ -0,0 +1,31 @@
+# syntax=docker/dockerfile:1.7
+
+# === Stage 1: build the SPA bundle ===
+FROM docker.io/library/node:20-alpine AS builder
+
+ARG VITE_API_BASE_URL=/api/v1
+ENV VITE_API_BASE_URL=${VITE_API_BASE_URL}
+
+WORKDIR /app
+COPY package.json ./
+# When a lockfile is committed (npm/pnpm/yarn), prefer `npm ci` for reproducibility.
+RUN if [ -f package-lock.json ]; then npm ci; else npm install --no-audit --no-fund; fi
+
+COPY tsconfig*.json vite.config.ts tailwind.config.ts postcss.config.js index.html ./
+COPY src ./src
+
+RUN npm run build
+
+# === Stage 2: serve via nginx ===
+FROM docker.io/library/nginx:1.27-alpine AS runtime
+
+# Drop the default config and use ours.
+RUN rm -f /etc/nginx/conf.d/default.conf
+COPY nginx.conf /etc/nginx/conf.d/metamorph.conf
+
+COPY --from=builder /app/dist /usr/share/nginx/html
+
+EXPOSE 80
+
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
+    CMD wget -qO- http://127.0.0.1/healthz || exit 1
--- a/frontend/README.md
+++ b/frontend/README.md
@@ -0,0 +1,39 @@
+# Metamorph frontend
+
+Vite + React 18 + TypeScript + TailwindCSS. Design tokens from `../tasks/design.md` are in `tailwind.config.ts`.
+
+## Local dev
+
+```bash
+npm install
+npm run dev          # http://localhost:5173 (proxies /api/* to http://localhost:8000)
+```
+
+## Build
+
+```bash
+npm run build        # outputs to dist/
+npm run preview      # serves dist/ on http://localhost:8080
+```
+
+## Quality
+
+```bash
+npm run typecheck
+npm run lint
+npm run format
+```
+
+## Layout
+
+```
+src/
+├── App.tsx                  # M0 home page (health check + design tokens demo)
+├── main.tsx
+├── index.css                # Tailwind base + tinted-accent utilities
+├── components/ui/           # RTOps design primitives: Card, Tag, SectionHeader, FlowNode, Button
+├── lib/
+│   ├── api.ts               # fetch wrapper (M2 will replace with auth-aware client)
+│   └── cn.ts                # classnames + ACCENTS palette
+└── vite-env.d.ts
+```
--- a/frontend/index.html
+++ b/frontend/index.html
@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta name="color-scheme" content="dark" />
+    <title>Metamorph</title>
+  </head>
+  <body class="bg-bg text-text font-sans">
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>
--- a/frontend/nginx.conf
+++ b/frontend/nginx.conf
@@ -0,0 +1,45 @@
+server {
+    listen 80;
+    listen [::]:80;
+    server_name _;
+
+    root /usr/share/nginx/html;
+    index index.html;
+
+    # Reasonable hardening — TLS is terminated by an external reverse proxy
+    # so we don't add HSTS here (let the edge own that header).
+    add_header X-Content-Type-Options "nosniff" always;
+    add_header X-Frame-Options "DENY" always;
+    add_header Referrer-Policy "same-origin" always;
+
+    # Internal liveness for the docker healthcheck.
+    location = /healthz {
+        access_log off;
+        return 200 "ok\n";
+        add_header Content-Type text/plain;
+    }
+
+    # Proxy API calls to the Flask service on the compose network.
+    location /api/ {
+        proxy_pass         http://api:8000;
+        proxy_http_version 1.1;
+        proxy_set_header   Host              $host;
+        proxy_set_header   X-Real-IP         $remote_addr;
+        proxy_set_header   X-Forwarded-For   $proxy_add_x_forwarded_for;
+        proxy_set_header   X-Forwarded-Proto $scheme;
+        proxy_read_timeout 60s;
+        client_max_body_size 64m;
+    }
+
+    # SPA fallback — every unknown route returns index.html.
+    location / {
+        try_files $uri $uri/ /index.html;
+    }
+
+    # Long cache for hashed assets.
+    location ~* \.(?:js|css|woff2?|svg|png|jpg|jpeg|webp|ico)$ {
+        expires 30d;
+        add_header Cache-Control "public, immutable";
+        try_files $uri =404;
+    }
+}
--- a/frontend/package.json
+++ b/frontend/package.json
@@ -0,0 +1,43 @@
+{
+  "name": "metamorph-front",
+  "private": true,
+  "version": "0.1.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc -b && vite build",
+    "preview": "vite preview --port 8080",
+    "lint": "eslint .",
+    "typecheck": "tsc -b --pretty",
+    "format": "prettier --write \"src/**/*.{ts,tsx,css,json,html}\"",
+    "format:check": "prettier --check \"src/**/*.{ts,tsx,css,json,html}\""
+  },
+  "dependencies": {
+    "@fontsource/ibm-plex-sans": "^5.0.20",
+    "@fontsource/jetbrains-mono": "^5.0.20",
+    "@tanstack/react-query": "^5.51.0",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "react-router-dom": "^6.26.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "devDependencies": {
+    "@types/node": "^20.12.7",
+    "@types/react": "^18.3.3",
+    "@types/react-dom": "^18.3.0",
+    "@typescript-eslint/eslint-plugin": "^7.13.0",
+    "@typescript-eslint/parser": "^7.13.0",
+    "@vitejs/plugin-react": "^4.3.1",
+    "autoprefixer": "^10.4.19",
+    "eslint": "^8.57.0",
+    "eslint-plugin-react-hooks": "^4.6.2",
+    "eslint-plugin-react-refresh": "^0.4.7",
+    "postcss": "^8.4.38",
+    "prettier": "^3.3.0",
+    "tailwindcss": "^3.4.4",
+    "typescript": "^5.4.5",
+    "vite": "^5.3.1"
+  }
+}
--- a/frontend/postcss.config.js
+++ b/frontend/postcss.config.js
@@ -0,0 +1,6 @@
+export default {
+  plugins: {
+    tailwindcss: {},
+    autoprefixer: {},
+  },
+};
--- a/frontend/src/App.tsx
+++ b/frontend/src/App.tsx
@@ -0,0 +1,85 @@
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { BrowserRouter, Navigate, Route, Routes } from 'react-router-dom';
+
+import { Layout } from '@/components/Layout';
+import { RequireAdmin } from '@/components/RequireAdmin';
+import { RequireAuth } from '@/components/RequireAuth';
+import { AdminGroupsPage } from '@/pages/AdminGroupsPage';
+import { AdminInvitationsPage } from '@/pages/AdminInvitationsPage';
+import { AdminUsersPage } from '@/pages/AdminUsersPage';
+import { HomePage } from '@/pages/HomePage';
+import { LoginPage } from '@/pages/LoginPage';
+import { ProfilePage } from '@/pages/ProfilePage';
+import { RegisterPage } from '@/pages/RegisterPage';
+import { SetupPage } from '@/pages/SetupPage';
+import { AuthContext, useProvideAuth } from '@/lib/auth';
+
+const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      retry: false,
+      refetchOnWindowFocus: false,
+      staleTime: 30_000,
+    },
+  },
+});
+
+function AuthProvider({ children }: { children: React.ReactNode }) {
+  const auth = useProvideAuth();
+  return <AuthContext.Provider value={auth}>{children}</AuthContext.Provider>;
+}
+
+function App() {
+  return (
+    <QueryClientProvider client={queryClient}>
+      <BrowserRouter>
+        <AuthProvider>
+          <Routes>
+            <Route element={<Layout />}>
+              <Route path="/login" element={<LoginPage />} />
+              <Route path="/setup" element={<SetupPage />} />
+              <Route path="/register" element={<RegisterPage />} />
+              {/* Home page stays public — it's an ops dashboard, not sensitive. */}
+              <Route path="/" element={<HomePage />} />
+              <Route
+                path="/profile"
+                element={
+                  <RequireAuth>
+                    <ProfilePage />
+                  </RequireAuth>
+                }
+              />
+              <Route
+                path="/admin/users"
+                element={
+                  <RequireAdmin>
+                    <AdminUsersPage />
+                  </RequireAdmin>
+                }
+              />
+              <Route
+                path="/admin/groups"
+                element={
+                  <RequireAdmin>
+                    <AdminGroupsPage />
+                  </RequireAdmin>
+                }
+              />
+              <Route
+                path="/admin/invitations"
+                element={
+                  <RequireAdmin>
+                    <AdminInvitationsPage />
+                  </RequireAdmin>
+                }
+              />
+              <Route path="*" element={<Navigate to="/" replace />} />
+            </Route>
+          </Routes>
+        </AuthProvider>
+      </BrowserRouter>
+    </QueryClientProvider>
+  );
+}
+
+export default App;
--- a/frontend/src/components/ui/Button.tsx
+++ b/frontend/src/components/ui/Button.tsx
@@ -0,0 +1,45 @@
+import type { ButtonHTMLAttributes, ReactNode } from 'react';
+
+import { cn, type Accent } from '@/lib/cn';
+
+interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+  accent?: Accent;
+  variant?: 'solid' | 'outline' | 'ghost';
+  children: ReactNode;
+}
+
+const ACCENT_OUTLINE: Record<Accent, string> = {
+  red: 'border-red text-red hover:bg-red/10',
+  orange: 'border-orange text-orange hover:bg-orange/10',
+  yellow: 'border-yellow text-yellow hover:bg-yellow/10',
+  green: 'border-green text-green hover:bg-green/10',
+  cyan: 'border-cyan text-cyan hover:bg-cyan/10',
+  blue: 'border-blue text-blue hover:bg-blue/10',
+  purple: 'border-purple text-purple hover:bg-purple/10',
+  pink: 'border-pink text-pink hover:bg-pink/10',
+  rose: 'border-rose text-rose hover:bg-rose/10',
+  teal: 'border-teal text-teal hover:bg-teal/10',
+};
+
+/** Minimal button matching the briefing aesthetic — no shadows, thin borders. */
+export function Button({
+  accent = 'cyan',
+  variant = 'outline',
+  className,
+  children,
+  ...rest
+}: ButtonProps) {
+  const base =
+    'inline-flex items-center justify-center rounded-md border px-3 py-2 font-mono text-xs font-medium uppercase tracking-wider2 disabled:opacity-50 disabled:pointer-events-none';
+  const variantCls =
+    variant === 'outline'
+      ? ACCENT_OUTLINE[accent]
+      : variant === 'ghost'
+        ? 'border-transparent text-text hover:bg-bg-card'
+        : 'border-transparent bg-bg-card text-text-bright';
+  return (
+    <button className={cn(base, variantCls, className)} {...rest}>
+      {children}
+    </button>
+  );
+}
--- a/frontend/src/components/ui/Card.tsx
+++ b/frontend/src/components/ui/Card.tsx
@@ -0,0 +1,50 @@
+import type { HTMLAttributes, ReactNode } from 'react';
+
+import { cn, type Accent } from '@/lib/cn';
+
+interface CardProps extends Omit<HTMLAttributes<HTMLDivElement>, 'title'> {
+  /** Accent border color — distinguishes the card's category. */
+  accent?: Accent;
+  /** Card heading. Renamed from the native HTMLAttributes.title (string-only). */
+  title?: ReactNode;
+  /** Subtitle / metadata line below the title. */
+  sub?: ReactNode;
+  children?: ReactNode;
+}
+
+const ACCENT_BORDER: Record<Accent, string> = {
+  red: 'border-red',
+  orange: 'border-orange',
+  yellow: 'border-yellow',
+  green: 'border-green',
+  cyan: 'border-cyan',
+  blue: 'border-blue',
+  purple: 'border-purple',
+  pink: 'border-pink',
+  rose: 'border-rose',
+  teal: 'border-teal',
+};
+
+/** Card from design.md §5.3 — shared chrome, accent-only differentiation. */
+export function Card({ accent, title, sub, children, className, ...rest }: CardProps) {
+  return (
+    <div
+      className={cn(
+        'bg-bg-card rounded-lg border p-5',
+        accent ? ACCENT_BORDER[accent] : 'border-border',
+        className,
+      )}
+      {...rest}
+    >
+      {title && (
+        <h3 className="font-mono text-sm font-semibold text-text-bright mb-1">{title}</h3>
+      )}
+      {sub && (
+        <div className="font-mono text-4xs uppercase tracking-wider2 text-text-dim mb-3">
+          {sub}
+        </div>
+      )}
+      {children && <div className="text-xs leading-[1.7]">{children}</div>}
+    </div>
+  );
+}
--- a/frontend/src/components/ui/FlowNode.tsx
+++ b/frontend/src/components/ui/FlowNode.tsx
@@ -0,0 +1,37 @@
+import type { ReactNode } from 'react';
+
+import { cn, type Accent } from '@/lib/cn';
+
+interface FlowNodeProps {
+  accent?: Accent;
+  children: ReactNode;
+  className?: string;
+}
+
+const ACCENT_BORDER_TEXT: Record<Accent, string> = {
+  red: 'border-red text-red',
+  orange: 'border-orange text-orange',
+  yellow: 'border-yellow text-yellow',
+  green: 'border-green text-green',
+  cyan: 'border-cyan text-cyan',
+  blue: 'border-blue text-blue',
+  purple: 'border-purple text-purple',
+  pink: 'border-pink text-pink',
+  rose: 'border-rose text-rose',
+  teal: 'border-teal text-teal',
+};
+
+/** Flow node from design.md §5.5 — chained horizontally with arrows in flex rows. */
+export function FlowNode({ accent, children, className }: FlowNodeProps) {
+  return (
+    <span
+      className={cn(
+        'inline-block bg-bg-card rounded-md border px-3 py-2 font-mono text-4xs whitespace-nowrap shrink-0',
+        accent ? ACCENT_BORDER_TEXT[accent] : 'border-border text-text',
+        className,
+      )}
+    >
+      {children}
+    </span>
+  );
+}
--- a/frontend/src/components/ui/SectionHeader.tsx
+++ b/frontend/src/components/ui/SectionHeader.tsx
@@ -0,0 +1,51 @@
+import type { ReactNode } from 'react';
+
+import { cn, type Accent } from '@/lib/cn';
+
+interface SectionHeaderProps {
+  /** Plain text leading the colored word. */
+  prefix?: string;
+  /** The single colored word in the title. */
+  highlight: string;
+  accent?: Accent;
+  description?: ReactNode;
+  className?: string;
+}
+
+const ACCENT_TEXT: Record<Accent, string> = {
+  red: 'text-red',
+  orange: 'text-orange',
+  yellow: 'text-yellow',
+  green: 'text-green',
+  cyan: 'text-cyan',
+  blue: 'text-blue',
+  purple: 'text-purple',
+  pink: 'text-pink',
+  rose: 'text-rose',
+  teal: 'text-teal',
+};
+
+/**
+ * Section header from design.md §5.2 — every h2 starts with a cyan `//`,
+ * a plain word, and exactly one colored word.
+ */
+export function SectionHeader({
+  prefix,
+  highlight,
+  accent = 'red',
+  description,
+  className,
+}: SectionHeaderProps) {
+  return (
+    <div className={cn('mt-[60px] mb-[30px]', className)}>
+      <h2 className="font-mono text-lg font-semibold text-text-bright pb-3 border-b border-border">
+        <span className="text-cyan">{'// '}</span>
+        {prefix && <span>{prefix} </span>}
+        <span className={ACCENT_TEXT[accent]}>{highlight}</span>
+      </h2>
+      {description && (
+        <p className="font-mono text-xs text-text-dim mt-2">{description}</p>
+      )}
+    </div>
+  );
+}
--- a/frontend/src/components/ui/Tag.tsx
+++ b/frontend/src/components/ui/Tag.tsx
@@ -0,0 +1,37 @@
+import type { ReactNode } from 'react';
+
+import { cn, type Accent } from '@/lib/cn';
+
+interface TagProps {
+  accent: Accent;
+  children: ReactNode;
+  className?: string;
+}
+
+const ACCENT_FILL: Record<Accent, string> = {
+  red: 'accent-fill-red',
+  orange: 'accent-fill-orange',
+  yellow: 'accent-fill-yellow',
+  green: 'accent-fill-green',
+  cyan: 'accent-fill-cyan',
+  blue: 'accent-fill-blue',
+  purple: 'accent-fill-purple',
+  pink: 'accent-fill-pink',
+  rose: 'accent-fill-rose',
+  teal: 'accent-fill-teal',
+};
+
+/** Tag/pill from design.md §5.4 — 9px uppercase mono, tinted fill. */
+export function Tag({ accent, children, className }: TagProps) {
+  return (
+    <span
+      className={cn(
+        'inline-block rounded font-mono text-3xs font-semibold uppercase tracking-wider2 px-2 py-[3px] mr-1 mb-2',
+        ACCENT_FILL[accent],
+        className,
+      )}
+    >
+      {children}
+    </span>
+  );
+}
--- a/frontend/src/index.css
+++ b/frontend/src/index.css
@@ -0,0 +1,49 @@
+/* Self-hosted webfonts — no runtime CDN (cf. spec §7). */
+@import '@fontsource/jetbrains-mono/300.css';
+@import '@fontsource/jetbrains-mono/400.css';
+@import '@fontsource/jetbrains-mono/500.css';
+@import '@fontsource/jetbrains-mono/600.css';
+@import '@fontsource/jetbrains-mono/700.css';
+@import '@fontsource/ibm-plex-sans/300.css';
+@import '@fontsource/ibm-plex-sans/400.css';
+@import '@fontsource/ibm-plex-sans/500.css';
+@import '@fontsource/ibm-plex-sans/600.css';
+
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+@layer base {
+  html,
+  body,
+  #root {
+    @apply min-h-screen;
+  }
+  body {
+    @apply bg-bg text-text font-sans;
+    line-height: 1.6;
+  }
+  /* No transitions / hovers / animations baseline (cf. design.md §7). */
+  *:focus-visible {
+    outline: 1px solid theme('colors.cyan');
+    outline-offset: 2px;
+  }
+  ::selection {
+    background: rgb(6 182 212 / 0.25);
+    color: theme('colors.text-bright');
+  }
+}
+
+@layer utilities {
+  /* Tinted accent fill — see design.md §2 "tinted fills". */
+  .accent-fill-red    { background: rgb(239 68 68 / 0.15);   color: theme('colors.red'); }
+  .accent-fill-orange { background: rgb(245 158 11 / 0.15);  color: theme('colors.orange'); }
+  .accent-fill-yellow { background: rgb(234 179 8 / 0.15);   color: theme('colors.yellow'); }
+  .accent-fill-green  { background: rgb(16 185 129 / 0.15);  color: theme('colors.green'); }
+  .accent-fill-cyan   { background: rgb(6 182 212 / 0.15);   color: theme('colors.cyan'); }
+  .accent-fill-blue   { background: rgb(59 130 246 / 0.15);  color: theme('colors.blue'); }
+  .accent-fill-purple { background: rgb(139 92 246 / 0.15);  color: theme('colors.purple'); }
+  .accent-fill-pink   { background: rgb(236 72 153 / 0.15);  color: theme('colors.pink'); }
+  .accent-fill-rose   { background: rgb(244 63 94 / 0.15);   color: theme('colors.rose'); }
+  .accent-fill-teal   { background: rgb(20 184 166 / 0.15);  color: theme('colors.teal'); }
+}
--- a/frontend/src/lib/cn.ts
+++ b/frontend/src/lib/cn.ts
@@ -0,0 +1,19 @@
+/** Tiny classnames helper — keeps deps minimal. */
+export function cn(...parts: Array<string | false | null | undefined>): string {
+  return parts.filter(Boolean).join(' ');
+}
+
+export const ACCENTS = [
+  'red',
+  'orange',
+  'yellow',
+  'green',
+  'cyan',
+  'blue',
+  'purple',
+  'pink',
+  'rose',
+  'teal',
+] as const;
+
+export type Accent = (typeof ACCENTS)[number];
--- a/frontend/src/main.tsx
+++ b/frontend/src/main.tsx
@@ -0,0 +1,14 @@
+import { StrictMode } from 'react';
+import { createRoot } from 'react-dom/client';
+
+import App from '@/App';
+import '@/index.css';
+
+const root = document.getElementById('root');
+if (!root) throw new Error('#root not found in index.html');
+
+createRoot(root).render(
+  <StrictMode>
+    <App />
+  </StrictMode>,
+);
--- a/frontend/src/pages/HomePage.tsx
+++ b/frontend/src/pages/HomePage.tsx
@@ -0,0 +1,185 @@
+import { useEffect, useState } from 'react';
+
+import { Button } from '@/components/ui/Button';
+import { Card } from '@/components/ui/Card';
+import { FlowNode } from '@/components/ui/FlowNode';
+import { SectionHeader } from '@/components/ui/SectionHeader';
+import { Tag } from '@/components/ui/Tag';
+import { apiGet } from '@/lib/api';
+
+interface HealthResponse {
+  status: string;
+  version: string;
+}
+
+interface DbDiagResponse {
+  reachable: boolean;
+  alembic_revision?: string | null;
+  table_count?: number;
+  error?: string;
+}
+
+type HealthState =
+  | { kind: 'loading' }
+  | { kind: 'ok'; data: HealthResponse }
+  | { kind: 'error'; error: string };
+
+type DbState =
+  | { kind: 'loading' }
+  | { kind: 'ok'; data: DbDiagResponse }
+  | { kind: 'error'; error: string };
+
+export function HomePage() {
+  const [health, setHealth] = useState<HealthState>({ kind: 'loading' });
+  const [db, setDb] = useState<DbState>({ kind: 'loading' });
+
+  useEffect(() => {
+    let cancelled = false;
+    apiGet<HealthResponse>('/health', { anonymous: true })
+      .then((data) => !cancelled && setHealth({ kind: 'ok', data }))
+      .catch((err: unknown) =>
+        !cancelled &&
+        setHealth({ kind: 'error', error: err instanceof Error ? err.message : String(err) }),
+      );
+    apiGet<DbDiagResponse>('/diag/db', { anonymous: true })
+      .then((data) => !cancelled && setDb({ kind: 'ok', data }))
+      .catch((err: unknown) =>
+        !cancelled &&
+        setDb({ kind: 'error', error: err instanceof Error ? err.message : String(err) }),
+      );
+    return () => {
+      cancelled = true;
+    };
+  }, []);
+
+  return (
+    <>
+      <header className="text-center mb-12">
+        <h1 className="font-mono text-[28px] font-bold tracking-tight text-text-bright">
+          <span className="text-red">Meta</span>
+          <span>morph</span>{' '}
+          <span className="text-purple">Purple Team Platform</span>
+        </h1>
+        <p className="font-mono text-sm font-light text-text-dim mt-2">
+          Collaborative red &amp; blue test orchestration — M3 milestone (RBAC)
+        </p>
+      </header>
+      <SectionHeader
+        prefix="System"
+        highlight="Health"
+        accent="cyan"
+        description="Live status pulled from /api/v1/health and /api/v1/diag/db."
+      />
+      <div className="grid gap-4 [grid-template-columns:repeat(auto-fill,minmax(420px,1fr))]">
+        <Card
+          accent={health.kind === 'ok' ? 'green' : health.kind === 'error' ? 'red' : 'cyan'}
+          title="API"
+          sub={
+            health.kind === 'loading'
+              ? 'probing…'
+              : health.kind === 'error'
+                ? 'unreachable'
+                : `version ${health.data.version}`
+          }
+        >
+          {health.kind === 'loading' && <p>Waiting for the backend…</p>}
+          {health.kind === 'ok' && (
+            <p>
+              Status:{' '}
+              <code className="accent-fill-green px-2 py-[2px] rounded-sm font-mono text-4xs">
+                {health.data.status}
+              </code>
+            </p>
+          )}
+          {health.kind === 'error' && (
+            <p>
+              Error:{' '}
+              <code className="accent-fill-red px-2 py-[2px] rounded-sm font-mono text-4xs">
+                {health.error}
+              </code>
+            </p>
+          )}
+        </Card>
+
+        <Card
+          accent={db.kind === 'ok' && db.data.reachable ? 'blue' : db.kind === 'error' ? 'red' : 'cyan'}
+          title="Database"
+          sub={
+            db.kind === 'loading'
+              ? 'probing…'
+              : db.kind === 'error'
+                ? 'unreachable'
+                : db.data.reachable
+                  ? `revision ${db.data.alembic_revision?.slice(0, 8) ?? 'unknown'}`
+                  : 'unreachable'
+          }
+        >
+          {db.kind === 'ok' && db.data.reachable && (
+            <p>
+              Tables:{' '}
+              <code
+                className="accent-fill-blue px-2 py-[2px] rounded-sm font-mono text-4xs"
+                data-testid="db-table-count"
+              >
+                {db.data.table_count}
+              </code>{' '}
+              · Alembic head reached.
+            </p>
+          )}
+          {(db.kind === 'loading' || (db.kind === 'ok' && !db.data.reachable)) && (
+            <p>Querying schema metadata…</p>
+          )}
+          {db.kind === 'error' && (
+            <p>
+              Error:{' '}
+              <code className="accent-fill-red px-2 py-[2px] rounded-sm font-mono text-4xs">
+                {db.error}
+              </code>
+            </p>
+          )}
+        </Card>
+
+        <Card accent="purple" title="Roadmap" sub="14 milestones">
+          <p>
+            M0 + M1 + M2 + M3 done. Next:{' '}
+            <code className="accent-fill-cyan px-2 py-[2px] rounded-sm font-mono text-4xs">
+              M4 — MITRE ATT&amp;CK
+            </code>
+            .
+          </p>
+        </Card>
+      </div>
+
+      <SectionHeader
+        prefix="Design"
+        highlight="Tokens"
+        accent="orange"
+        description="Sanity check of the RTOps design system primitives (cf. tasks/design.md)."
+      />
+      <div className="mb-6">
+        <Tag accent="red">EVASION</Tag>
+        <Tag accent="purple">C2</Tag>
+        <Tag accent="cyan">LATERAL</Tag>
+        <Tag accent="orange">CRED</Tag>
+        <Tag accent="green">PHISH</Tag>
+        <Tag accent="teal">PERSIST</Tag>
+      </div>
+      <div className="flex items-center gap-1 flex-wrap py-3 mb-6">
+        <FlowNode accent="orange">recon</FlowNode>
+        <span className="text-text-dim font-mono text-2xs">→</span>
+        <FlowNode accent="green">phish</FlowNode>
+        <span className="text-text-dim font-mono text-2xs">→</span>
+        <FlowNode accent="purple">c2</FlowNode>
+        <span className="text-text-dim font-mono text-2xs">→</span>
+        <FlowNode accent="cyan">lateral</FlowNode>
+        <span className="text-text-dim font-mono text-2xs">→</span>
+        <FlowNode accent="red">impact</FlowNode>
+      </div>
+      <div className="flex gap-2">
+        <Button accent="cyan">Primary</Button>
+        <Button accent="red">Danger</Button>
+        <Button variant="ghost">Cancel</Button>
+      </div>
+    </>
+  );
+}
--- a/frontend/src/vite-env.d.ts
+++ b/frontend/src/vite-env.d.ts
@@ -0,0 +1,9 @@
+/// <reference types="vite/client" />
+
+interface ImportMetaEnv {
+  readonly VITE_API_BASE_URL?: string;
+}
+
+interface ImportMeta {
+  readonly env: ImportMetaEnv;
+}
--- a/frontend/tailwind.config.ts
+++ b/frontend/tailwind.config.ts
@@ -0,0 +1,66 @@
+import type { Config } from 'tailwindcss';
+
+/**
+ * Design tokens from `tasks/design.md` — Red Team Operations Map.
+ * Dark, flat, terminal-inspired. Color-as-taxonomy: each accent maps to a category.
+ */
+export default {
+  content: ['./index.html', './src/**/*.{ts,tsx}'],
+  theme: {
+    extend: {
+      colors: {
+        // Surfaces
+        bg: '#0a0e1a',
+        'bg-card': '#111827',
+        border: '#1e2d3d',
+        // Text
+        text: '#94a3b8',
+        'text-bright': '#f8fafc',
+        'text-dim': '#64748b',
+        'text-comment': '#475569',
+        // Accent palette (each one means a category — see tasks/design.md §2)
+        red: '#ef4444',
+        orange: '#f59e0b',
+        yellow: '#eab308',
+        green: '#10b981',
+        cyan: '#06b6d4',
+        blue: '#3b82f6',
+        purple: '#8b5cf6',
+        pink: '#ec4899',
+        rose: '#f43f5e',
+        teal: '#14b8a6',
+      },
+      fontFamily: {
+        mono: ['"JetBrains Mono"', 'ui-monospace', 'SFMono-Regular', 'monospace'],
+        sans: ['"IBM Plex Sans"', 'ui-sans-serif', 'system-ui', 'sans-serif'],
+      },
+      fontSize: {
+        // Custom scale matching design.md §3 — extends the default Tailwind ramp.
+        // 2xs = arrow labels (8px), 3xs = tag/pill (9px), 4xs = card sub-label, flow node, inline code (10px).
+        // 11px (pre/footer), 12px (body/section desc), 13/14px (card title), 18px (section h2),
+        // and 28px (page h1) all already exist in the default ramp.
+        '2xs': ['8px', '1.4'],
+        '3xs': ['9px', '1.4'],
+        '4xs': ['10px', '1.4'],
+      },
+      borderRadius: {
+        sm: '3px',
+        DEFAULT: '4px',
+        md: '6px',
+        lg: '10px',
+      },
+      maxWidth: {
+        page: '1400px',
+      },
+      letterSpacing: {
+        wider2: '1px',
+      },
+    },
+  },
+  // Safelist accent classes used dynamically (tag categories, flow nodes).
+  safelist: [
+    { pattern: /^(border|text|bg)-(red|orange|yellow|green|cyan|blue|purple|pink|rose|teal)$/ },
+    { pattern: /^(border|text|bg)-(red|orange|yellow|green|cyan|blue|purple|pink|rose|teal)\/(\d+)$/ },
+  ],
+  plugins: [],
+} satisfies Config;
--- a/frontend/tsconfig.app.json
+++ b/frontend/tsconfig.app.json
@@ -0,0 +1,29 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "useDefineForClassFields": true,
+    "module": "ESNext",
+    "skipLibCheck": true,
+
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "isolatedModules": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+    "jsx": "react-jsx",
+
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true,
+    "noImplicitOverride": true,
+    "exactOptionalPropertyTypes": false,
+
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["src/*"]
+    }
+  },
+  "include": ["src"]
+}
--- a/frontend/tsconfig.json
+++ b/frontend/tsconfig.json
@@ -0,0 +1,7 @@
+{
+  "files": [],
+  "references": [
+    { "path": "./tsconfig.app.json" },
+    { "path": "./tsconfig.node.json" }
+  ]
+}
--- a/frontend/tsconfig.node.json
+++ b/frontend/tsconfig.node.json
@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2023"],
+    "module": "ESNext",
+    "skipLibCheck": true,
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "isolatedModules": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true
+  },
+  "include": ["vite.config.ts"]
+}
--- a/frontend/vite.config.ts
+++ b/frontend/vite.config.ts
@@ -0,0 +1,29 @@
+import path from 'node:path';
+
+import react from '@vitejs/plugin-react';
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+  plugins: [react()],
+  resolve: {
+    alias: {
+      '@': path.resolve(__dirname, './src'),
+    },
+  },
+  server: {
+    host: '0.0.0.0',
+    port: 5173,
+    proxy: {
+      // In `npm run dev`, proxy /api/* to the local Flask backend.
+      '/api': {
+        target: 'http://localhost:8000',
+        changeOrigin: true,
+      },
+    },
+  },
+  build: {
+    outDir: 'dist',
+    sourcemap: false,
+    target: 'es2022',
+  },
+});