[jayleaton]

The template gets an optional admin dashboard (apps/admin): its own binary, Railway service, database and auth instance. Admins can list, search and inspect users (sessions, verified, created, role, ban state), ban (reason, expiry) and unban, revoke sessions, set roles, invite admins and read an audit log of every admin action. An analytics placeholder sits behind a port. The UI is in en and ja, and there is a matching JSON API under /api/admin/v1.

Summary

flowchart LR
  subgraph admin["apps/admin (own binary, ADMIN_* env)"]
    UI["ui (templ + Datastar)"] --> S["services (Policy + audit)"]
    API["api /api/admin/v1"] --> S
    S --> SRV["server adapters"]
  end
  SRV -->|"auth.UserAdmin (ban, role, sessions)"| APPDB[("app DB: DATABASE_URL")]
  SRV -->|"admin auth instance, cookie admin.*"| ADMDB[("admin DB: ADMIN_DATABASE_URL")]
  S -->|"adminrepo.AuditLog (append-only)"| ADMDB
  S -->|"adminrepo.Stats (read-only)"| APPDB
  WEB["apps/web"] -.x|"depguard + forbidigo"| admin
  WEB -.x ADMDB

Loading

• Same layers as the web app. Ports live in the services, the handlers are about five lines inside the route wrapper and envelope, validators are separate, and mockgen mocks are used only at the boundary tests. Every service method checks services.Policy first: any admin may act, provided they have 2FA when ADMIN_REQUIRE_2FA is on (the default in production). Every mutation writes admin_audit_log after it succeeds. A failed audit write is a 500 and is never swallowed.
• User administration goes through auth.UserAdmin, not a second sqlc copy. packages/auth owns those tables, the ban rules (including expired bans lifting themselves) and session revocation. packages/database/adminrepo (sqlc) holds what the admin app owns: the audit log, which a trigger keeps append-only, and read-only stats.
• Isolation in both directions, enforced and probed.
  • depguard: apps/web/** cannot import apps/admin or adminrepo, and apps/admin/** cannot import apps/web.
  • Admin transports cannot import packages/auth; they declare UI-owned ports and server adapts auth to them.
  • forbidigo: auth.NewUserAdmin and (*auth.Auth).Users are only allowed in apps/admin and in auth itself.
  • make lint-layering plants a violation for every rule.
• Invite only.
  • admin migrate seeds ADMIN_BOOTSTRAP_EMAIL without a password, and admin invite <email> (or the Admins page) emails a set-password link. With ADMIN_REQUIRE_2FA, setting the password continues into TOTP enrolment with backup codes before the first session.
  • The admin auth instance has DisableSignUp, and the server mounts only the auth endpoints it needs: sign-in, the 2FA steps, the set-password link, session and sign-out. Self-service account changes would bypass the audit log, so they are not reachable.
• Local dev and deploy.
  • make db-up creates an admin database on the same per-checkout Postgres: no extra container, and worktree isolation is unchanged.
  • Commands: make admin-dev, admin-migrate, admin-invite EMAIL=, admin-build, admin-docker.
  • Deploy files: apps/admin/Dockerfile and apps/admin/railway.json (pre-deploy /admin migrate, plus /healthz, which pings both databases). Hosted, the admin database is its own small Postgres.
• Fixes the browser pass found:
  • Web sign-in of a banned user showed "Something went wrong". It now maps auth.ErrBannedUser to a translated "account suspended" message.
  • In the admin UI, the GET search and filter forms were swallowed by Datastar's submit preventDefault.
• Fixes a blocking security review found:
  • The emailed set-password and reset token was written to request logs, in both apps. Logs now record /api/auth/reset-password/{token}.
  • Every admin response is now no-store.
  • The locale redirect now rejects control characters.
  • The auth endpoints are an allowlist (see above).

Evidence

Before: there was no admin app (apps/admin did not exist).

After:

• Real servers (web on :3200, admin on :3201, the per-checkout dev Postgres with app and admin databases, ADMIN_REQUIRE_2FA=true), driven by headless Chromium. Script output on the final commit:

  [e2e] admin signed in after 2FA enrolment
  [e2e] web: banned session redirected to http://localhost:3200/login
  [e2e] web: banned sign-in refused with: "Your account has been suspended. Contact support if you think this is a mistake."
  [e2e] web: sign-in works after unban
  [e2e] admin sign-in with TOTP works
  [e2e] ALL OK
  

  The flow: a user signs up in web; admin migrate creates the bootstrap admin; admin invite admin@example.com logs the link; the admin opens it, sets a password and enrols TOTP; they search for the user, open the detail page and ban them for 1 day. The user's web session dies and their sign-in is refused. After the unban, sign-in works again. Then the audit log, analytics, admins and the Japanese pages are checked, and finally a fresh browser signs in with the TOTP step. A replayed TOTP code is refused, as expected.

  There are 15 screenshots: users search, user detail, banned and unbanned states, the web refusal, the audit log, analytics, admins, the ja pages, and 2FA enrolment and sign-in. They are on the dev box at ~/Documents/spark-work/zig-dsv41-scratch/admin-shots/ and are not uploaded to GitHub.

• make ci, run through heavy.sh with -j1 -p=1, passes:

  • Build, generated-code diff (sqlc, mocks, templ), and gofmt + golangci-lint with 0 issues.
  • Test-location check, go test -race, and coverage floors.
  • 40/40 layering probes (22 new: 20 admin depguard probes in both directions and 2 forbidigo) and the test-boundary and coverage probes, including the admin services coverage probe.

• Per boundary (passing tests including subtests, then coverage against the floor):

  Boundary	Passing tests	Coverage (floor)
  apps/admin/internal/services	28	100% (90)
  apps/admin/internal/api	91	100% (85); validate 100%
  apps/admin/ui/**	106	89.9% (80, new floor)
  packages/database/adminrepo	4	82.9% (80)

  The allowlisted wiring tests are apps/admin/internal/server (6, incl. TestBanFlow and TestAdminIsolation over real packages/auth on two Postgres databases) and apps/admin/internal/config (4).

Merge Danger

Door: two-way.

Everything is additive and opt-in. The admin app runs only if you deploy it, and its migrations touch only its own database (goose_auth and goose_admin there). The app database gets no new migrations from this PR.

The shared-code changes are small:

• dbtest.Fingerprint is now exported.
• The web UI gains one error mapping and two message keys.
• Web request logs redact reset tokens.

Reverting the PR removes them.

Blast Radius: platform.

• Lint, CI and tooling: new depguard and forbidigo rules, extended test boundaries and floors, CI templ/paths, and Makefile targets. make db-up now also creates the admin dev database.
• Shared code: the web-side changes listed above.
• Deploy order: deploy the web service before the admin service. Web's pre-deploy migrates the app database the admin app reads.

Follow-ups, not in this PR:

• Removing or disabling an admin.
• Admin RESEND_API_KEY through packages/secrets.
• A QR code for TOTP (manual key plus otpauth:// link today).
• Auditing admin sign-ins.

🤖 Generated with Claude Code