Skip to content

UI Flows

Prescriptive end-to-end flows for both the player-client (services/player-client/) and the admin-ui (services/admin-ui/). Names every page/component the user touches and the action that drives them to the next screen.

This is the target experience. For implementation tech stacks see player-client.md and admin-ui.md. For the realtime layer see realtime.md.

Source files referenced throughout: - services/player-client/src/components/pages/ — top-level player pages. - services/player-client/src/components/first-login/, galaxy/, trading/, combat/, planetary/, spacedock/, ai/. - services/admin-ui/src/components/pages/ — top-level admin pages.

1. Player-client journey

1.1 High-level flow

flowchart TD
    A[LoginPage.tsx] -->|JWT auth| B{First login?}
    B -->|yes| C[FirstLoginContainer.tsx]
    B -->|no| D[GameDashboard.tsx]
    C -->|dialogue + ship pick| D
    D -->|click Galaxy| E[GalaxyMap.tsx]
    D -->|click Dock| F[SpaceDockInterface.tsx]
    D -->|click Trade| G[TradingInterface.tsx]
    D -->|click Planet| H[Planetary components]
    D -->|click Combat| I[Combat components]
    D -->|click ARIA| J[AI chat panel]
    E -->|select sector| K[SectorView]
    K -->|warp/move| E
    K -->|enter port| F
    F -->|buy/sell| G
    G -->|exit| D
    H -->|manage colony| D
    I -->|combat resolved| D
    J -->|return| D

1.2 Step-by-step

Login → Dashboard

  1. Player lands on LoginPage.tsx (components/pages/LoginPage.tsx).
  2. Submits credentials via AuthContext → gameserver issues JWT + refresh token.
  3. On success, the router checks Player.first_login.completed. If false → first-login flow. If true → GameDashboard.tsx.

First-login flow (one-time per character)

  1. FirstLoginContainer.tsx (components/first-login/) orchestrates a four-step ARIA-driven sequence:
  2. DialogueExchange.tsx — multi-turn AI conversation. Trust is shown by TrustMeter.tsx.
  3. ShipSelection.tsx — picks the starter ship type.
  4. OutcomeDisplay.tsx — confirms the outcome (ship, credits, starting sector).
  5. On completion → Player.first_login = { completed: true } server-side, redirect to GameDashboard.tsx.

Main dashboard

  1. GameDashboard.tsx (components/pages/GameDashboard.tsx) is the central hub. It shows:
  2. Current ship status (hull, shields, cargo, turns, credits).
  3. Current sector and dock state.
  4. Quick actions: Galaxy Map, Dock/Undock, Trade (if docked), Planet (if landed), Combat status, ARIA.
  5. Live activity feed via WebSocketContext.
  6. From here the player branches into one of five sub-flows.

Galaxy map flow

  1. Click "Galaxy Map" → GalaxyMap.tsx (components/pages/GalaxyMap.tsx).
  2. Renders a 3D star field via Galaxy3DRenderer.tsx + SectorNode3D.tsx + ConnectionPath3D.tsx + PlayerMarker3D.tsx (components/galaxy/).
  3. Click a sector node → sector detail panel shows distance, contents (stations, planets, hostile presence), and a "Move here" button.
  4. Move → server validates turn_cost, updates Player.current_sector_id, returns updated state via WebSocket. Map redraws with new player position.

Dock and trade flow

  1. From dashboard or sector view, click "Dock" at a station → SpaceDockInterface.tsx (components/spacedock/).
  2. SpaceDock screen shows: Trade, Repair, Upgrade, Equipment, Insurance buttons.
  3. Click Trade → TradingInterface.tsx (components/trading/). Shows commodity buy/sell prices for this station, with current cargo and credit balance.
  4. Submit buy or sell → server runs trading_service.calculate_dynamic_price (economy/trading.md), commits transaction, returns updated cargo/credits.
  5. (Optional) Click Upgrade → ship-upgrade panel listing available UpgradeType levels with costs (driven by ship_upgrade_service.get_upgrade_info).
  6. Click Undock → return to GameDashboard.tsx.

Planet management flow

  1. When the player's ship is at a sector with an owned planet, the dashboard exposes a "Land" action.
  2. Click → planetary management view (components/planetary/). Shows population, production, defences, build queue, terraforming state.
  3. Player can: queue colonist transport from station, install planetary defences, initiate terraforming, build citadels.
  4. "Take off" → return to GameDashboard.tsx with ship in sector orbit.

Combat flow

  1. When the player enters a sector with a hostile, the dashboard surfaces a combat alert banner.
  2. Click → combat interface (components/combat/, components/tactical/). Shows attacker/defender ship cards with hull, shields, drone counts.
  3. Each combat round uses attack_turn_cost from Ship.attack_turn_cost (see combat.md). Round-by-round results stream over WebSocket.
  4. On resolution: winner returns to dashboard with loot; loser returns in escape pod (ship_service._ensure_escape_pod).

Fleet operations

  1. From dashboard, click "Fleet" (📐 Design-only top-level button) → fleet management view.
  2. Lists all owned ships, their current sector, status, assigned route. Player can:
  3. Reassign a ship to a different sector.
  4. Set up an automated trade route between two stations.
  5. Designate a flagship (Ship.is_flagship).
  6. Status: 📐 Design-only — Fleet model exists (models/fleet.py) and fleet_service.py is shipped, but the management UI is unbuilt.

ARIA chat

  1. From any screen, an ARIA panel toggle is available (components/ai/).
  2. Click → conversational panel showing recent ARIA messages, market intelligence summaries, and a free-text input.
  3. ARIA's responses incorporate Player.aria_consciousness_level, aria_relationship_score, and the player's recent activity (see aria.md).

Subscription / settings

  1. Profile menu → subscription management → SubscriptionResult.tsx for post-PayPal-redirect handling.
  2. Subscription create button kicks off the PayPal flow described in monetization.md. On return, SubscriptionResult.tsx displays activation confirmation.
  3. PayPal-related UI lives in components/paypal/.

2. Admin-ui journey

2.1 High-level flow

flowchart TD
    A[LoginPage.tsx] -->|JWT + MFA| B[AdminDashboard.tsx]
    B -->|Universe| C[UniverseEditorPage.tsx]
    B -->|Users| D[UsersManager.tsx]
    B -->|Economy| E[EconomyDashboard.tsx]
    B -->|Security| F[SecurityDashboard.tsx]
    B -->|Multi-regional| G[RegionalGovernorDashboard.tsx]
    B -->|Combat| H[CombatOverview.tsx]
    B -->|Colonization| I[ColonizationManagement.tsx]
    B -->|First-login| J[FirstLoginConversations.tsx]
    B -->|Permissions| K[PermissionsDashboard.tsx]
    B -->|Teams| L[TeamManagement.tsx]
    B -->|Analytics| M[AdvancedAnalytics.tsx]
    C -->|edit sector| N[SectorEditModal]
    C -->|edit planet| O[PlanetDetail]
    C -->|edit station| P[StationDetail]
    D -->|edit player| Q[player editor]
    G -->|select region| R[CentralNexusManager.tsx]

2.2 Step-by-step

Login + MFA

  1. Operator visits the admin URL → LoginPage.tsx (admin-ui components/pages/).
  2. Submits credentials. If MFA is enabled (auth/MFAVerification.tsx), prompts for TOTP code.
  3. Server validates against models/admin_credentials.py and models/mfa.py. JWT issued.

Admin dashboard

  1. Lands on AdminDashboard.tsx — the operator hub. Displays:
  2. System health, active player count, recent audit events.
  3. Sidebar navigation (components/layouts/Sidebar.tsx) with the 12+ top-level admin sections.

Universe editor

  1. Sidebar → "Universe" → UniverseEditorPage.tsx or Universe.tsx / UniverseManager.tsx.
  2. Renders the universe (regions → clusters → sectors → planets → stations) in a navigable tree.
  3. Click a sector → SectorEditModal (components/universe/).
  4. Click a planet → PlanetDetail modal. Adjust biome, population, owner, defences.
  5. Click a station → StationDetail modal. Adjust commodities, prices, base values, station class.
  6. Click a colony → ColonyDetailModal.
  7. All edits route through the gameserver admin API (services/admin/) and are audited.

User management

  1. Sidebar → "Users" → UsersManager.tsx.
  2. Search / filter users. Click a user → player editor (components/admin/).
  3. Editor lets operator: grant credits, modify rank, reset turns, suspend account, view audit history, force logout.

Economy dashboard

  1. Sidebar → "Economy" → EconomyDashboard.tsx (components/pages/, CSS in economy-dashboard.css).
  2. Shows: total credits in circulation, inflation indicators, top trading ports, wealth distribution, market liquidity, health score.
  3. Drill-down into per-region or per-commodity views.
  4. Levers exposed (📐 Design-only): adjust commodity base prices, production rates, regional tax rates without DB shell access. See FEATURES/economy/lifecycle.md §5.

Security / audit

  1. Sidebar → "Security" → SecurityDashboard.tsx.
  2. Sub-views: AuditLogViewer (components/security/), permission matrix, recent suspicious events.
  3. Sidebar → "Permissions" → PermissionsDashboard.tsx with PermissionMatrix + RoleManagement (components/permissions/).

Multi-regional governor

  1. Sidebar → "Multi-Regional" → RegionalGovernorDashboard.tsx (components/pages/).
  2. Lists all regions with: type (central_nexus / terran_space / player_owned), owner, citizen count, tax rate, status, governance type.
  3. Click a region → drill into governance tools: edit tax_rate (within 5–25%), adjust governance_type, force-suspend, view treasury balance.
  4. Sidebar → "Central Nexus" → CentralNexusManager.tsx for managing the 5,000-sector central hub specifically.

Combat overview

  1. Sidebar → "Combat" → CombatOverview.tsx with CombatFeed + DisputePanel (components/combat/).
  2. Real-time feed of all active combat events. Operator can review disputes (suspected exploits) and reverse outcomes if justified.

Colonization

  1. Sidebar → "Colonization" → ColonizationOverview.tsx / ColonizationManagement.tsx.
  2. Per-planet view of colony health, terraforming progress, genesis device deployment status.

First-login conversations

  1. Sidebar → "First-Login" → FirstLoginConversations.tsx.
  2. Lists every player's first-login dialogue with filters and detail modal (components/first-login/). Used for QA, content tuning, and identifying ARIA misbehaviour.

Teams

  1. Sidebar → "Teams" → TeamManagement.tsx with AllianceNetwork + TeamAdminPanel (components/teams/).
  2. View team membership, alliance graph, intervene in team disputes.

Analytics

  1. Sidebar → "Analytics" → AdvancedAnalytics.tsx, PlayerAnalytics.tsx, AnalyticsReports.tsx.
  2. Build custom reports, view performance metrics, surface predictive analytics.

AI trading dashboard

  1. Sidebar → "AI Trading" → AITradingDashboard.tsx.
  2. Monitors AI provider health (ai_provider_service.py), recent ARIA conversations, market prediction accuracy.

Event management

  1. Sidebar → "Events" → EventManagement.tsx.
  2. Schedule and trigger universe-wide events (sales, faction wars, anomalies).

3. Key cross-cutting UX rules

3.1 Auth gating

Every authenticated page in both apps wraps in AuthContext (player-client) or ProtectedRoute (admin-ui components/auth/). Unauthenticated requests redirect to LoginPage.tsx.

3.2 Real-time updates

Both apps maintain a single WebSocket connection (WebSocketContext). Server pushes: - Sector arrivals (other players entering / leaving). - Combat events. - Market price changes. - Admin audit events. - ARIA messages.

See realtime.md.

3.3 i18n

All visible strings flow through i18next (services/admin-ui/src/i18n.ts, services/player-client/src/i18n.ts). Language switcher available on LoginPage.tsx and the user profile menu. See i18n.md.

3.4 Error states

  • Network failure: toast banner, retry-with-backoff. No silent failures.
  • Auth expiry: redirect to login.
  • Server-side validation failure: inline form error.

3.5 Mobile responsiveness

The player-client targets a desktop-first 3D experience but degrades for tablet (the galaxy map switches from 3D to 2D minimap, dashboards stack to single-column). The admin-ui is desktop-only.

4. Cross-references