Player Client¶

Status: 🚧 Partial — Core player-client inventory (first-login, galaxy 3D, trading-interface, subscriptions, services/contexts) is accurate … · ⚠︎ contains code↔spec divergence (impl audit 2026-06-16)

The player-facing web app at services/player-client/.

1. Tech stack¶

From services/player-client/package.json:

Layer	Choice
Framework	React 18.2 + TypeScript 5.2
Build	Vite 8.0
Routing	react-router-dom 7.13
HTTP	axios 1.13
3D	three 0.158, @react-three/fiber 8.18, @react-three/drei 9.122
Animation	framer-motion 10.16, @react-spring 9.7
Icons	lucide-react 0.292
Sanitization	isomorphic-dompurify 3.4 (XSS prevention for AI chat)
Utility	lodash.debounce, lodash.throttle
i18n	i18next 23.16 + react-i18next 13.5 + browser-languagedetector + http-backend
Tests	Playwright 1.52

State management: React Context (AuthContext, GameContext, FirstLoginContext, WebSocketContext).

Default ports: player-client on 3000, gameserver on 8080.

2. Project layout¶

services/player-client/src/
├── App.tsx, main.tsx, i18n.ts
├── components/
│   ├── ai/              AIAssistant, AIAssistantButton, EnhancedAIAssistant (ARIA chat)
│   ├── analytics/       AchievementTracker, GoalManager, Leaderboards, PlayerAnalytics, ProgressVisualizer
│   ├── auth/
│   ├── combat/          CombatInterface, CombatLog, CombatAnalytics, DroneManager,
│   │                    FleetBattlePanel, FormationControl, SiegeInterface, TacticalPlanner
│   ├── common/          shared UI (LanguageSwitcher, etc.)
│   ├── first-login/     FirstLoginContainer, DialogueExchange, ShipSelection,
│   │                    OutcomeDisplay, TrustMeter
│   ├── galaxy/          Galaxy3DRenderer, SectorNode3D, PlayerMarker3D,
│   │                    ConnectionPath3D, StarField
│   ├── layouts/
│   ├── market-intelligence/  MarketAnalyzer, PricePredictor, RouteOptimizer, CompetitionMonitor
│   ├── pages/           7 top-level pages (see Section 3)
│   ├── paypal/          PayPalSubscription
│   ├── planetary/       PlanetManager, BuildingManager, ColonistAllocator,
│   │                    ColonySpecialization, DefenseConfiguration, GenesisDeployment,
│   │                    ProductionDashboard, SiegeStatusMonitor, CitadelManager
│   ├── ranking/         RankDisplay, RankProgress, Leaderboard, MedalShowcase
│   ├── ships/           CargoManager, FleetCoordination, InsuranceManager,
│   │                    MaintenanceManager, ShipDetails, ShipSelector, UpgradeInterface
│   ├── spacedock/       SpaceDockInterface
│   ├── tactical/        SectorViewport, NavigationMap, PlanetCard, PlanetPortPair,
│   │                    StationCard, TacticalCard
│   ├── teams/           TeamManager, TeamChat, TeamAnalytics, AllianceManager,
│   │                    DiplomacyInterface, ResourceSharing
│   └── trading/         TradingInterface, MarketIntelligenceDashboard, SmartTradingAutomation
├── contexts/            AuthContext, GameContext, FirstLoginContext, WebSocketContext
├── services/            api.ts, apiClient.ts, websocket.ts, realtimeWebSocket.ts, aiTradingService.ts
├── styles/, themes/, types/, utils/
└── utils/security/      XSS / sanitization helpers (separate from common utils)

A shared API layer lives in services/api.ts (~14.6 KB) plus services/apiClient.ts. Real-time traffic flows through services/realtimeWebSocket.ts (the multiplayer protocol client).

3. Pages¶

components/pages/ has 7 top-level pages:

Page	Purpose
`LoginPage.tsx`	Auth
`Dashboard.tsx`, `GameDashboard.tsx`	Player landing pages
`GalaxyMap.tsx`	Galaxy / sector navigation (uses `galaxy/` 3D components)
`SubscriptionResult.tsx`	PayPal subscription confirmation
`DebugPage.tsx`, `TestAuthPage.tsx`	Dev / QA tools

Most actual gameplay UI happens inside the dashboards via the feature modules above rather than dedicated pages.

A markdown sketch (components/GameDashboardIntegration.md) sits alongside the code as in-tree design notes.

4. Key features¶

first-login/FirstLoginContainer.tsx orchestrates the AI guard interrogation. DialogueExchange.tsx renders the conversation, TrustMeter.tsx shows persuasion progress, ShipSelection.tsx is the ship picker, OutcomeDisplay.tsx shows the resolution. CSS is heavy (first-login.css). Backed by /api/v1/first-login/* and the multi-provider AI dialogue service (OpenAI primary, Anthropic secondary, deterministic fallback).

Trading + ARIA market intelligence¶

trading/TradingInterface.tsx is the core buy/sell UI. trading/MarketIntelligenceDashboard.tsx (~22 KB) and trading/SmartTradingAutomation.tsx (~29 KB) plus the market-intelligence/ quartet (MarketAnalyzer, PricePredictor, RouteOptimizer, CompetitionMonitor) surface ARIA's per-player observations and predictions. Service: services/aiTradingService.ts.

Combat¶

Eight components in combat/ covering combat interface, log, analytics, drone management, fleet battle panel, formation control, siege interface, and tactical planner. The combat/README.md indicates the directory has its own internal docs.

Planetary management¶

Nine components in planetary/ covering planet manager, building manager, colonist allocation, colony specialization, defense configuration, genesis deployment, production dashboard, siege monitoring, and citadel management.

Galaxy / 3D¶

galaxy/Galaxy3DRenderer.tsx plus SectorNode3D, PlayerMarker3D, ConnectionPath3D, StarField provide the Three.js view. tactical/SectorViewport.tsx is the in-sector 2D view.

Teams / alliances¶

Six components in teams/: TeamManager, TeamChat, TeamAnalytics, AllianceManager, DiplomacyInterface, ResourceSharing.

Ships & space dock¶

ships/ has 7 components (cargo, fleet coordination, insurance, maintenance, details, selector, upgrade UI). spacedock/SpaceDockInterface.tsx is the standalone dock view.

ARIA chat¶

See ./aria.md — ai/EnhancedAIAssistant.tsx is the main chat component with DOMPurify sanitization, client-side rate limiting, Web Speech API, and WebSocket integration.

Subscriptions¶

paypal/PayPalSubscription.tsx plus pages/SubscriptionResult.tsx handle the PayPal monetization flow used by multi-regional ($25/mo regional ownership, $5/mo galactic citizenship — see ./multi-regional.md).

Player progression UI¶

ranking/ (RankDisplay, RankProgress, Leaderboard, MedalShowcase) renders the military-rank progression. See FEATURES/gameplay/ranking.md.
analytics/AchievementTracker.tsx, GoalManager.tsx, and the rest of the analytics/ directory cover lifetime achievements and personal goals.

Real-time multiplayer¶

services/realtimeWebSocket.ts is the multiplayer-protocol client (presence, sector chat, combat events). See ./realtime.md.

i18n¶

common/LanguageSwitcher.tsx; full i18next setup. Six languages targeted (English / Spanish / French / Portuguese / Chinese launch-complete; German Partial — see ./i18n.md).

5. Build / test¶

# from services/player-client/
npm run dev         # vite dev (port 3000)
npm run build       # tsc + vite build
npm run lint        # eslint
npm run test:e2e    # playwright via scripts/run-tests.js
npm run test:e2e:ui # playwright UI mode

E2E specs: - e2e_tests/player/ui/player-ui.spec.ts — player-UI spec. - e2e_tests/foundation-sprint/security-validation.spec.ts, websocket-realtime.spec.ts — cross-cutting tests.