Admin UI¶

Status: 🚧 Partial — Admin-UI page/component inventory, live-status dashboard, universe editor, and the honest-disabled regional governance tabs are real and accurate … · ⚠︎ contains code↔spec divergence (impl audit 2026-06-16)

The administrative web app at services/admin-ui/. Used by operators to manage the universe, players, economy, security, multi-regional deployment, and the AI dialogue subsystem.

1. Tech stack¶

From services/admin-ui/package.json:

Layer	Choice
Framework	React 18.2 + TypeScript 5.2
Build	Vite 4.4
Routing	react-router-dom 6.15
HTTP	axios 1.5
WebSockets	socket.io-client 4.8
Charting	chart.js 4.4 + react-chartjs-2; d3 7.8 for custom viz
i18n	i18next 23.16 + react-i18next 13.5 + browser-languagedetector + http-backend
Tests	Playwright 1.52 (E2E)
Lint	ESLint 8 + @typescript-eslint 8

State management: React Context (no external store).

Auth: JWT, integrated via contexts/AuthContext.tsx and utils/auth.ts.

Default ports: admin-ui on 3001, gameserver on 8080.

2. Project layout¶

services/admin-ui/src/
├── App.tsx, main.tsx, i18n.ts
├── components/
│   ├── admin/        Player asset / detail editors, intervention panels, bulk ops
│   ├── ai/           Market prediction, route optimization, behavior analytics
│   ├── analytics/    Custom report builder, performance metrics, predictive
│   ├── auth/         LoginForm, MFASetup, MFAVerification, ProtectedRoute, UserProfile
│   ├── charts/       Combat activity, fleet health, market health, price, team strength
│   ├── colonization/ Colony overview, genesis tracking, planetary mgmt, production
│   ├── combat/       CombatFeed, DisputePanel
│   ├── common/       LanguageSwitcher, PageLoader
│   ├── first-login/  ConversationDetailModal, ConversationFilters, ConversationTable
│   ├── layouts/      AppLayout, Sidebar
│   ├── pages/        28 top-level page components (see Section 3)
│   ├── permissions/  PermissionMatrix, RoleManagement
│   ├── security/     AuditLogViewer
│   ├── teams/        AllianceNetwork, TeamAdminPanel
│   ├── ui/           PageHeader, SystemHealthStatus
│   ├── universe/     SectorEditModal, PlanetDetail(Modal), StationDetail, ColonyDetailModal, UniverseEditor
│   └── users/        (CSS only — page lives in components/pages/UsersManager.tsx)
├── contexts/         AdminContext, AuthContext, WebSocketContext
├── services/         websocket.ts (single shared client)
├── styles/, types/, utils/

utils/ only holds auth.ts — the rest is in components. services/ has just one file (websocket.ts); REST calls happen via per-component axios usage rather than a centralized API client (contrast with the player-client, which has a dedicated services/api.ts).

3. Pages¶

components/pages/ contains 26 .tsx files, each routed in App.tsx. The list:

Page	Domain
`LoginPage.tsx`	Auth
`Dashboard.tsx`	Landing / overview
`UniverseManager.tsx`, `BangGalaxyPage.tsx`	Universe editor + Bang-engine generation
`SectorsManager.tsx`, `StationsManager.tsx`, `PlanetsManager.tsx`, `WarpTunnelsManager.tsx`	Universe drill-downs
`UsersManager.tsx`, `PlayerAnalytics.tsx`	Users / players
`AdvancedAnalytics.tsx`	Analytics
`EconomyDashboard.tsx`	Economy
`CombatOverview.tsx`, `FleetManagement.tsx`	Combat / fleets
`ColonizationManagement.tsx`	Planetary
`TeamManagement.tsx`	Teams
`EventManagement.tsx`	Game events
`FactionManagement.tsx`	Factions
`MessageModeration.tsx`	Messaging / moderation
`CentralNexusManager.tsx`, `RegionalGovernorDashboard.tsx`	Multi-regional
`AITradingDashboard.tsx`, `FirstLoginConversations.tsx`	AI ops
`SecurityDashboard.tsx`, `PermissionsDashboard.tsx`	Security / RBAC
`TranslationManagement.tsx`	Internationalization

4. Key features¶

Universe editor¶

UniverseManager.tsx (plus BangGalaxyPage.tsx for Bang-engine generation and the universe/ modal components) offers galaxy generation (configurable parameters, region distribution sliders, sector-by-sector edits) and clickable drill-downs to planets, ports, and warp tunnels. Backed by /api/v1/admin/galaxy/* and /api/v1/admin/sectors/* endpoints.

Dashboard with live status¶

SystemHealthStatus.tsx (in components/ui/) renders three live cards — Database, AI providers (OpenAI / Anthropic), Game Server — pulling from /api/v1/status/database, /api/v1/status/ai/providers, /api/v1/status/. Auto-refreshes; shows pool metrics, response times, configuration vs reachability state.

AI ops¶

AITradingDashboard.tsx — monitors AI trading interactions.
FirstLoginConversations.tsx + first-login/ modals/filters/table — review the AI-driven first-login dialogues, useful for tuning the guard personality and ship-outcome thresholds (recent migrations ec92f8afd44a, c5e32c313020, 6b1d95a38c98, 2e78250f47bc, 6acc65ee7a72 all touched this area).
ai/ components (MarketPredictionInterface, RouteOptimizationDisplay, PlayerBehaviorAnalytics) surface backend ML output.

Analytics¶

PlayerAnalytics.tsx (large) and AdvancedAnalytics.tsx, plus analytics/ (CustomReportBuilder, PerformanceMetrics, PredictiveAnalytics) and the charts/ widgets.

Multi-regional¶

CentralNexusManager.tsx and RegionalGovernorDashboard.tsx expose the Central Nexus generation + regional governance APIs (/api/v1/nexus/*, /api/v1/regions/*). The latter is one of the larger pages in the app — 7-tab interface (Overview, Governance, Economy, Policies, Elections, Diplomacy, Culture).

Governance write scope and honest-disabled tabs (canon, blessed by Max 2026-06-14). Governance writes are keyed by region id — an operator acts on a named region's governance state, not a global one — gated by admin.regions.* scopes. The Culture and Diplomacy tabs are honestly disabled (visibly inert, not faked) until their backing endpoints exist; each must be re-enabled only once its real endpoint ships, never wired to mock data in the interim. Diplomacy in particular is intended to graduate into a real gameplay feature (inter-region relations), not a permanent admin-only panel — so its tab stays disabled rather than stubbed until that feature lands.

Security & audit¶

SecurityDashboard.tsx for monitoring (live metrics over the audit-log feed); security/AuditLogViewer.tsx for the audit trail. MFA setup and verification components live in auth/.

Authorization model (per ADR-0058 A-F2; supersedes ADR-0027): admin capabilities live as a 19-entry scope set, each scope assignable per-admin via AdminScopeGrant (user_id, scope, granted_by, granted_at). The legacy User.is_admin boolean is retained as a derived view (is_admin = EXISTS scope grant) for backwards compatibility — no longer the authorization gate.

Scope families: admin.players.* (view, suspend, adjust_rep, transfer_assets), admin.subscriptions.* (view, modify, refund), admin.webhooks.* (view, replay), admin.regions.* (view, create, terminate, transfer_ownership), admin.aria.audit, admin.multi_account.review, admin.bang.regenerate, admin.scopes.* (grant, revoke), admin.audit.view. Full list in ADR-0058.

UI surfaces:

/admin/scopes — scope-grant management. Gated by admin.scopes.grant / admin.scopes.revoke. Targets PermissionsDashboard.tsx + permissions/ components, which previously rendered mock data — now wired against AdminScopeGrant.
/admin/audit — admin-action audit log. Gated by admin.audit.view.
/admin/review-queue — daily queue of high-impact actions (anything in admin.subscriptions.*, admin.webhooks.replay, admin.regions.terminate, admin.scopes.*) for retrospective acknowledgement by another admin. Acknowledgements logged. No pre-action two-person gate — accountability through scope-precision + audit + review.

A sweep-test alarm fires if the review queue's 30-day-old unacknowledged count crosses a threshold (target: review acknowledged within 7 days).

Scope-gated routes return 403 with the missing scope name in the response body — clients render "you need scope X" rather than a generic permission error.

Admin REST rate limits¶

📐 Design-only — admin endpoints are rate-limited per authenticated admin user (separate from the player-facing limits enforced on the realtime bus):

Endpoint class	Limit
Read (`GET /api/v1/admin/*`)	100 / minute
Write (`POST` / `PATCH` / `DELETE`)	30 / minute
Bulk operations (`POST /api/v1/admin/*/bulk`)	10 / minute
Reports / exports	5 / hour

Bulk operations include market interventions (price cap / floor / supply injection), combat resolution overrides, mass message moderation, and asset transfers — actions that touch many rows in one call. The 5-per-hour reports cap covers expensive analytics queries that scan denormalized aggregates.

i18n¶

common/LanguageSwitcher.tsx with full i18next integration. Backed by six-language translation files (English / Spanish / French / Portuguese / Chinese launch-complete; German Partial — see ./i18n.md).

5. Build / test¶

# from services/admin-ui/
npm run dev          # vite dev
npm run dev:watch    # with live-reload watcher
npm run build        # tsc + vite build
npm run lint         # eslint
npm run test:e2e     # playwright via scripts/run-tests.js

E2E specs live in e2e_tests/admin/ui/: login, dashboard, universe-generation, sector-editing, sector-editing-authenticated, user-management.