Admin UI¶

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 28 .tsx files. The list:

Page	Domain
`LoginPage.tsx`	Auth
`Dashboard.tsx`, `AdminDashboard.tsx`, `TranslatedDashboard.tsx`	Landing / overview
`Universe.tsx`, `UniverseEditorPage.tsx`, `UniverseManager.tsx`	Universe editor
`SectorsManager.tsx`, `StationsManager.tsx`, `PlanetsManager.tsx`, `WarpTunnelsManager.tsx`	Universe drill-downs
`UsersManager.tsx`, `PlayerAnalytics.tsx`	Users / players
`AdvancedAnalytics.tsx`, `AnalyticsReports.tsx`	Analytics
`EconomyDashboard.tsx`	Economy
`CombatOverview.tsx`, `FleetManagement.tsx`	Combat / fleets
`ColonizationManagement.tsx`, `ColonizationOverview.tsx`	Planetary
`TeamManagement.tsx`	Teams
`EventManagement.tsx`	Game events
`CentralNexusManager.tsx`, `RegionalGovernorDashboard.tsx`	Multi-regional
`AITradingDashboard.tsx`, `FirstLoginConversations.tsx`	AI ops
`SecurityDashboard.tsx`, `PermissionsDashboard.tsx`	Security / RBAC

4. Key features¶

Universe editor¶

Universe.tsx / UniverseEditorPage.tsx / UniverseManager.tsx plus the universe/ modal components offer 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), AdvancedAnalytics.tsx, AnalyticsReports.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).

Security & RBAC¶

SecurityDashboard.tsx for monitoring; PermissionsDashboard.tsx plus permissions/ (PermissionMatrix, RoleManagement) for role assignment. security/AuditLogViewer.tsx for the audit trail. MFA setup and verification components live in auth/.

i18n¶

common/LanguageSwitcher.tsx with full i18next integration. Backed by 5-language translation files (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.