M13 — Frontend Admin Spec (v1)

Multi-tenant admin UI for broad-announce. React + Vite SPA, embedded in the admind Go binary via embed.FS. Companion to SPEC.md (the backend), M13_API_CONTRACT.md (the wire), and the per-milestone plans M13a_PLAN.md, M13b_PLAN.md, M13c_PLAN.md.

Status: planning (post-M11, parallel to M12) Target: ship a v1 admin UI that replaces dlq.html and adds the CRUD + live-tail + audit + auth surfaces for super-admin and tenant-admin personas.

0. Recap — what M13 must prove

Surface	Acceptance criteria
Auth	Super-admin and tenant-admin can log in (username + password, argon2id). Tenant-admins are invited via magic-link (or psql bootstrap if email infra is not yet ready).
Tenants / Companies CRUD	Super-admin can create, list, edit, suspend. Tenant-admin sees only their own company.
Sources CRUD	Both personas can CRUD sources within their scope. Super-admin sees all, tenant-admin sees only their company's.
Telegram bots	Per-company bots: token, invite code generation, chat_id mapping table view.
Live tail	SSE feed of incoming alerts on a single page. Filterable by company (super-admin) or scoped to tenant (tenant-admin).
DLQ surface	Replaces `cmd/admind/ui/dlq.html` with the same list/replay/discard flow, plus filters.
Audit log viewer	Read-only table of `audit_log` rows, filterable by actor / action / entity / time.
Single binary	`admind` Go binary embeds the SPA via `embed.FS`. One build, one deploy. No CORS, no separate frontend server.

What M13 is NOT:

Not a customer-facing end-user app (out of scope per survey 1.3).
Not a tenant-admin invite flow beyond email/PSQL bootstrap. SSO is post-v1 (survey 2.3).
Not a Grafana replacement. Dashboards stay in Grafana (M9). The frontend surfaces the control plane, not observability charts.

1. Personas

1.1 Super-admin (`role=super_admin`)

Scope: every company in the system.
Use cases: onboarding a new company, troubleshooting cross-tenant issues, audit review, killing misbehaving sources.
Login: username + password. Bootstrap account seeded by env vars at first deploy (BA_AUTH_BOOTSTRAP_ADMIN=...).
UI affordances: company switcher in the top bar; all data tables have a "company" column.

1.2 Tenant-admin (`role=tenant_admin`)

Scope: exactly one company (their own). Backend rejects any cross-company request with 403.
Use cases: managing their sources, viewing their alerts, configuring their telegram bot, seeing their DLQ.
Login: username + password. Invited by super-admin via magic-link.
UI affordances: no company switcher; all data tables filtered to their company automatically.

1.3 End-user — NOT v1

Deferred. The 1.3 survey response excluded mobile/PWA. End-user is the recipient of alerts, manages quiet hours. Out of scope.

2. Tenancy & auth

2.1 New service: `authd`

Decision: cmd/authd/, port 8804, dedicated HTTP service. NOT a module inside admind. Rationale:

Clean security boundary — auth holds the JWT secret, never touches business data.
Reusable from ingestd, routerd, deliverd-*, gRPC server in the future (M14+). Today only admind and the frontend use it.
Independent scaling and deployment.
Uses Postgres for users/memberships (same DB, separate schema — see M13_API_CONTRACT.md §1.10 for the schema sketch).

2.2 Auth flow

Login (POST /v1/auth/login): username + password → verify argon2id hash → issue access JWT (15min, HS256) + refresh JWT (7d, opaque, server-side store).
Refresh (POST /v1/auth/refresh): rotate refresh token, return new access + refresh. Old refresh invalidated.
Logout (POST /v1/auth/logout): invalidate refresh token server-side.
Invite (super-admin only, POST /v1/auth/invites): create user row with status=pending, generate magic-link token, return URL. Email send is best-effort: if SMTP env vars are unset, the API returns the URL directly so super-admin can paste it. (This is the "B with fallback to A" answer for survey 2.4.)
Magic-link accept (POST /v1/auth/invites/accept): user submits token + new password → password hashed → user status=active.
Me (GET /v1/auth/me): returns current user with role + scoped company_id. Frontend uses this for routing and nav.

2.3 Session storage

Access token (15min): stored in memory by the SPA. Never in localStorage (XSS exposure).
Refresh token (7d): stored in httpOnly, Secure, SameSite=Lax cookie. Sent automatically on refresh.
Logout: clears the cookie + calls POST /v1/auth/logout to invalidate the server-side row.

2.4 JWT shape

{
  "sub": "user_<uuid>",
  "role": "super_admin" | "tenant_admin",
  "company_id": "acme-001" | null,
  "iat": 1749819000,
  "exp": 1749822600
}

HS256, secret from env BA_AUTH_JWT_SECRET (32+ bytes, rotated by supporting both old and new during rotation).
company_id is null for super-admin (cross-tenant access).

2.5 Backend enforcement

Every admind endpoint checks Authorization: Bearer <jwt>.
For tenant-admin: server appends WHERE company_id = $1 from the JWT to every query. No way to bypass from the frontend.
Audit log row written for every state-changing call, signed with the actor's user_id.

2.6 SSO — explicitly post-v1

A cmd/authd/sso/ directory will be created (empty in v1) and the /v1/auth/sso/<provider>/login and /v1/auth/sso/<provider>/callback routes will return 501. SSO is added when the first enterprise customer asks for it.

3. v1 modules

3.1 Tenants / Companies CRUD

List: table of companies, columns: name, slug, status, created_at, fcm_shared, rate_limit_per_sec, alert_count_24h.
Detail: edit form (name, slug, fcm_shared toggle, rate_limit_per_sec, telegram_bot_token_enc, status).
Create: form (name, slug auto-derived; auto-checks uniqueness).
Suspend/activate: button on detail; sets status=suspended or active. Suspended companies cannot ingest.
Tenant-admin view: read-only "Your company" page (no edit, no create).
Backend endpoints: GET/POST/PATCH /v1/companies, GET /v1/companies/:id.

3.2 Sources CRUD

List: per-company table, columns: name, type, hmac_secret (masked), api_key_hash (masked), rate_limit_per_sec, allowed_ips, status, alerts_24h.
Detail: edit form (name, type, hmac_secret, api_key, rate_limit_per_sec, allowed_ips[], topic_prefix, status). The secret field is masked with "show" toggle.
Create: same form, generates a fresh hmac_secret and api_key on save and shows them ONCE in a "save these now" modal (same pattern as GitHub PAT).
Status: active / quarantined (per layer-7 from M9). Show quarantine reason if quarantined.
Backend endpoints: GET/POST/PATCH /v1/sources, GET /v1/sources/:id.

3.3 Telegram bots

Per-company bot config: set the bot token (encrypted at rest by admind using a master key from env), view invite codes, list of bound chat_id → individual_id mappings.
Generate invite code: button → POST → returns code + t.me/<bot>?start=<code> URL. Status (active / expired / used).
List individuals bound: table of individual_id, telegram_user_id, telegram_chat_id, status, last_seen_at.
Backend endpoints: GET/PUT /v1/companies/:id/telegram, GET/POST /v1/companies/:id/telegram/invites, GET /v1/companies/:id/telegram/bindings.

3.4 Live tail (SSE)

Page: full-width feed of incoming alerts, newest at top. Auto-scrolls; pause-on-scroll-up.
Filter bar: company (super-admin only), severity (>= X), category, source, text search on title_key.
Row columns: timestamp, severity, company, source, title_key, dedupe_count, actions (drill-in).
Click row: modal with full alert payload (data JSON, dedupe history).
Backpressure: server keeps last 200 events in memory; new connection catches up. No persistence — this is live, not history.
Transport: EventSource('/v1/tail/stream') with Authorization header workaround (EventSource doesn't support headers natively — token passed as query param ?access_token=***, validated once, upgraded to a short-lived SSE token by authd).
Backend endpoints: GET /v1/tail/stream (SSE), GET /v1/tail/recent?since=<ts> (HTTP fallback).

3.5 DLQ surface

List: table of DLQ rows, columns: id, alert_id, channel, target, attempts, last_error, next_attempt_at, created_at, status (pending / replayed / discarded).
Detail: full alert payload + delivery history (each attempt's error, response code, latency).
Replay: button → POST → re-publishes to deliverd NATS subject. Confirmation modal showing "this will redeliver to N recipients".
Discard: button → POST → marks status=discarded (hidden from default list). Audit row written.
Bulk actions (v1.1 — not v1): multi-select replay/discard. v1 is single-row only.
Backend endpoints: GET /v1/dlq, GET /v1/dlq/:id, POST /v1/dlq/:id/replay, POST /v1/dlq/:id/discard. Migrates the M8 endpoints that already exist.

3.6 Audit log viewer

List: table of audit_log rows, columns: ts, actor (user_id or "system"), action, entity_type, entity_id, ip, user_agent, metadata (collapsed JSON).
Filter: actor, action, entity_type, time range.
Read-only. No actions from this page (audit is immutable).
Backend endpoints: GET /v1/audit?actor=&action=&since=&until=. New endpoint — M8 didn't have it.

3.7 Auth pages

Login: username + password → access + refresh.
Magic-link accept: token + new password form.
Forbidden / 403 page: clean message, link to login.
Logout: button in top bar.

3.8 Out of scope for v1 (deferred, recorded so we don't forget)

Survey responses were explicit. Recorded here so a future reader doesn't re-litigate:

Module	Why deferred	Trigger to revisit
Groups + group members	Excluded from survey 1.2	When 2nd customer asks for self-service user mgmt
Individuals CRUD	Excluded from survey 1.2	Same as groups
Subscriptions UI	Excluded from survey 1.2	When end-user (D from 1.1) becomes a real persona
Routing rules editor	Excluded from survey 1.2	When power users complain about SQL-only
SSO / OIDC per customer	2.3 chose in-house first	First enterprise customer with own IdP
Mobile app / PWA	Excluded from 1.3	After end-user (D) is a real persona
Real-time collab editing	Excluded from 1.3	When >5 operators use it concurrently
Billing / quota UI	Excluded from 1.3	When pricing model exists
Theme/branding per company	Implicit deferral	When 2nd customer with brand requirements signs
Visual rule editor (drag/drop)	Implicit deferral	When customers request low-code routing
Density toggle in UI	3.1 chose shadcn default	When ops users complain about density
SLO dashboards in UI	They live in Grafana (M9)	When operators ask to leave Grafana

4. Milestones — the implementation grouping

M13 is split into 3 milestones (M13a, M13b, M13c) plus the spec & API contract already written. Each milestone has its own PLAN.md with workstreams, estimates, and exit criteria.

Milestone	Goal	Plan	Blocked by	Estimate
M13.0	Spec + API contract (this file + `M13_API_CONTRACT.md`)	inline	M11	✅ done (this PR)
M13a	authd service + web skeleton (login works end-to-end)	`M13a_PLAN.md`	M13.0	~5-6 days
M13b	Companies + Sources + Telegram CRUD	`M13b_PLAN.md`	M13a	~7-8 days
M13c	Live tail + DLQ + Audit + K8s + Playwright E2E	`M13c_PLAN.md`	M13a, M13b	~7-9 days

Each milestone ships independently and flips one row of SPEC.md. You can stop after any milestone and have something useful:

After M13a: nothing visible to the end-user yet, but auth is in place and the SPA shell loads. Useful for "is the design right?" review before committing to the rest.
After M13b: super-admin can do real work — create companies, onboard a source, set up telegram. ~80% of operator value.
After M13c: full v1 done. Replaces dlq.html, adds live tail and audit, has K8s manifests and a Playwright gate.

4.1 What ships in M13a

cmd/authd/ — JWT IdP service, all 7 endpoints.
web/ skeleton — Vite + React 19 + shadcn/ui + TanStack Query.
Login page → /me → logout, all working against real authd.
Top bar + sidebar with empty pages (companies/sources/telegram/etc.) rendered with "coming soon" placeholders.
admind modified to require JWT on every endpoint (except /health, /metrics, the auth passthroughs).
SPEC.md M13a row flipped to ✅.

4.2 What ships in M13b

Companies CRUD (super-admin full, tenant-admin read-only).
Sources CRUD with one-time secrets modal.
Telegram bot config + invite codes + bindings list.
All forms validate, audit log writes, error toasts.
SPEC.md M13b row flipped to ✅.

4.3 What ships in M13c

Live tail page (SSE) with filter bar + drill-in modal.
DLQ list/detail/replay/discard, replaces dlq.html.
Audit log viewer.
K8s manifests for admind and authd (carry from M12 W1).
Playwright E2E happy path green in CI.
M13_VERIFICATION.md with screenshots + run logs.
SPEC.md M13c row flipped to ✅.

5. Stack

Layer	Choice	Why
Build	Vite 5	Fast HMR, the SPEC literally says "React + Vite"
UI framework	React 19	Current, shadcn-compatible
Components	shadcn/ui (Radix + Tailwind)	Accessible, copy-paste, no version lock-in
Server state	TanStack Query v5	Cache, retries, devtools. Standard for v1 SPA
Client state	React useState/useReducer. No Redux.	Not needed
Forms	React Hook Form + Zod	Standard, type-safe
Tables	TanStack Table (headless) + shadcn Data Table wrapper	Powerful, accessible
Routing	React Router v6 (data routers)	Stable, type-safe loaders
Live tail	Server-Sent Events via native EventSource	Simpler than WS, one-direction
HTTP client	openapi-fetch + openapi-typescript generated client	Type-safe from Go OpenAPI spec
Testing	Vitest (units) + Playwright (1 E2E happy path)	Fast + high-signal
i18n	None in v1. All copy in `src/i18n/en.ts`	Future i18next migration is mechanical
Package manager	pnpm with workspace	Fast, saves disk
Lint	ESLint + Prettier	Standard
Node version	22 LTS	Current LTS

Not in v1:

Redux / Zustand / MobX (overkill for this scope)
next-intl / i18next (English only v1)
Storybook (defer until we have 10+ components in flux)
Sentry / OpenTelemetry browser (defer to v2)
Workbox / PWA manifest (defer — not in scope per 1.3)

6. Repo layout

broad-announce/
├── cmd/
│   ├── admind/                  # existing — gets embed.FS for the SPA
│   │   ├── main.go
│   │   └── web/dist/            # generated by `pnpm --filter web build`
│   └── authd/                   # new in M13a — JWT IdP service, port 8804
│       ├── main.go
│       └── ...
├── internal/                    # existing backend code
├── web/                         # new in M13a — Vite + React 19 SPA
│   ├── package.json
│   ├── pnpm-workspace.yaml
│   ├── vite.config.ts
│   ├── index.html
│   ├── src/
│   │   ├── main.tsx
│   │   ├── App.tsx
│   │   ├── routes/              # React Router routes
│   │   ├── components/          # shadcn/ui + custom
│   │   ├── features/            # companies/, sources/, telegram/, tail/, dlq/, audit/
│   │   ├── lib/                 # api client, auth, hooks
│   │   ├── i18n/en.ts
│   │   └── types/               # generated openapi types
│   ├── public/
│   └── tests/                   # vitest + playwright
├── M13_FRONTEND_SPEC.md (this file)
├── M13_API_CONTRACT.md
├── M13a_PLAN.md
├── M13b_PLAN.md
├── M13c_PLAN.md
└── ...

7. Embedding & deployment

7.1 Build pipeline

cd web && pnpm install (first time or on dep change).
pnpm --filter web run build → outputs web/dist/.
cp -r web/dist/* cmd/admind/web/dist/ (or use a Makefile target).
go build ./cmd/admind/... → Go's //go:embed web/dist directive packages the static files into the binary.
go build ./cmd/authd/... → authd binary.
Docker image: existing Dockerfile copies both binaries.

7.2 Serving the SPA from `admind`

admind registers mux.Handle("/", http.FileServer(http.FS(staticFS))) with the embed.FS rooted at web/dist.
SPA fallback: any path that doesn't match an API route serves index.html (so React Router can handle the route).
API routes are prefixed /v1/, /health, /metrics. Everything else → SPA.
Cache-Control: long for /assets/* (hashed), no-cache for /.

7.3 Auth and CORS

No CORS needed — same-origin, the SPA is served by admind itself.
authd is on port 8804; the SPA talks to it via the authd Service in K8s / via localhost:8804 in dev. The admind API forwards Authorization: Bearer *** from the SPA's cookie to upstream checks by calling authd POST /v1/auth/verify (or by sharing the JWT secret — see M13_API_CONTRACT.md §3 for the design call).

8. Testing strategy (per-milestone detail in each PLAN)

Unit (Vitest): forms, auth helpers, data transformers, one happy-path per feature.
E2E (Playwright, 1 happy path in M13c): super-admin logs in → creates a company → creates a source → triggers an alert via curl to ingestd → sees the alert in Live Tail within 2s.
What we are NOT testing in v1: visual regression, cross-browser matrix, SPA load testing, axe-core audit (shadcn/Radix gets us 90% for free).

9. Open questions (flagged for the W1 walk-through)

Default is documented; if a reviewer disagrees, they edit the spec before M13a W1 starts.

Users table location — same Postgres DB as everything else, or a separate authd DB? Default: same DB, separate schema (auth). Pro: one backup story. Con: blast radius.
JWT verification — admind calls authd on every request, or shares the secret? Default: shared secret (HS256) for v1; flip to authd JWKS endpoint when K8s multi-cluster lands.
Refresh token storage — server-side Postgres row, or stateless JWT? Default: server-side row, 7d TTL, rotated on use. Revocable.
Audit log writes — every service writes its own rows, or admind is the proxy? Default: every service writes its own (M9 already has the schema). Simpler, more accurate, no proxy needed.
authd HTTP port — 8804 (next slot after admind 8803). Flag for review if there's a convention I'm missing.

10. Risks (carried forward to each milestone's PLAN)

Risk	Likelihood	Impact	Mitigation
Bundle size grows with features	Medium	Medium (slow first paint)	Code-split per route, lazy-load heavy tables
`embed.FS` blows the Go binary to 100+ MB	Low	Low	Use `//go:embed` with gzip; check size in CI
JWT secret rotation breaks live sessions	Medium	Medium	Support 2 secrets during rotation; rotation playbook in `authd/README.md`
Magic-link emails go to spam	High	Low (we have psql fallback)	Document SPF/DKIM; v1 returns URL in API response if SMTP unconfigured
Tenant-admin bypass via direct API call	Low	High	Backend enforcement of `WHERE company_id = $1`, tested in Playwright
SSE drops through corporate proxies	Medium	Medium	Long-poll fallback (`/v1/tail/recent?since=`) is already in the API
React 19 + shadcn interop bugs	Low	Low	shadcn already supports React 19; pin in pnpm-lock
Two builds per release (web + Go)	Certain	Low	Makefile target, single `make build` in CI
OpenAPI drift between Go and TS types	Medium	High	Generate client in CI on every Go API change; PR that drifts fails

Next step: review this spec + M13_API_CONTRACT.md, mark up the Open Questions in §9, then start M13a W1 (authd).

M13_FRONTEND_SPEC.md 20 KB Historia Raaka