How tommi-k/pax-historia works
1. Overall shape
- Pax Historia is a React/Vite frontend with a small Node-based server in server/server.js.
- The repo is organized around a game client that loads map/data assets, renders a world map, and coordinates UI, selection, and AI-assisted gameplay systems.
- The README makes clear it is still early-stage and not yet a working product, so some modules are scaffolding rather than complete gameplay logic.
2. Application entry and runtime boundary
- The client entrypoint is src/main.jsx, which bootstraps src/App.jsx.
- src/runtime/StartupScreen.jsx and src/runtime/preload.js indicate a startup/loading phase before the game shell becomes usable.
- src/runtime/assets.js and src/runtime/countryLabels.js suggest a runtime layer responsible for preparing assets and label metadata before the main game UI renders.
3. Core game shell
- The game-specific code lives under src/Game/.
- This directory is split into three main concerns:
- Map/ for geographic rendering,
- Selection/ for user interaction with regions,
- GameUI/ for overlays, panels, and non-map controls,
- AI/ for model/provider integration.
- This structure implies a map-first game experience where user selections drive the UI and AI systems.
4. Map subsystem
- src/Game/Map/World.jsx, Nations.jsx, and Cities.jsx are the visual layers for the world state.
- The map is backed by PMTiles datasets in the repo root and in public/saves/save0/:
- countries.pmtiles
- public/saves/save0/regions.pmtiles
- public/saves/save0/countries.pmtiles
- public/saves/save0/cities.pmtiles
- This strongly suggests a tile-based geospatial data pipeline, where country/region/city geometry is rendered from local tiles rather than fetched from a remote map service.
5. Selection and interaction boundary
- src/Game/Selection/Regions.jsx appears to handle region selection logic.
- In architecture terms, this is the interaction layer between the map and the game state: the map presents geography, and selection determines what region/country/city is active for the rest of the app.
6. Game UI subsystem
- src/Game/GameUI/ is split into several feature panels:
- actions.jsx
- advisor.jsx
- chat.jsx
- search.jsx
- settings.jsx
- time.jsx
- other.jsx
- main.jsx
- This suggests a composite UI sidebar or HUD that aggregates gameplay controls, conversation/advisor tools, search, and time progression.
- The separation implies that the map is the main canvas, while this UI layer manages stateful gameplay actions and player feedback.
7. AI subsystem
- src/Game/AI/main.jsx and providerConfig.js indicate an abstraction for external AI providers or model settings.
- Because there is a dedicated advisor and chat UI, the AI layer likely powers in-game guidance and conversation, rather than being a generic background service.
- Architecturally, this is a clear boundary: the game UI requests AI behavior through the AI module, and the AI module likely mediates provider-specific configuration.
8. Persistence and save-state model
- The public/saves/save0/ directory is a major clue about how game state is organized.
- It contains:
- game.json for core game state,
- prompts.json for AI prompt data,
- storage/ with actions.json, advisor.json, chat.json, and events.json,
- plus the map PMTiles datasets.
- This suggests a save slot structure where a save directory bundles both world data and subsystem-specific state/history.
- The split into separate storage JSON files implies independent persistence for gameplay actions, AI/advisor context, chat history, and events.
9. Static assets and presentation data
- public/assets/colors.json likely feeds color styling for nations, regions, or map layers.
- The public/assets/ and runtime asset helpers show that a fair amount of presentation data is file-based and bundled with the app, not generated dynamically.
- public/loading_screen.jpg in the README screenshot reinforces the presence of a custom loading/startup experience.
10. Server role
- server/server.js is the only server file shown, which suggests a thin Node server rather than a large backend.
- Given the project setup instructions, it likely serves the built frontend and possibly exposes minimal runtime endpoints or file access for save data.
- The architecture is therefore primarily client-driven, with the server acting as an execution/hosting layer.
11. Build and tooling boundary
- The repo uses Vite for client bundling and ESLint for linting.
- TypeScript config files are present (tsconfig*.json), even though the visible source files are mostly .jsx, which suggests the project may be gradually migrating or using TypeScript-aware tooling without full TS adoption yet.
- npm run build followed by node server/server.js indicates a two-step delivery model: build frontend assets, then serve them from Node.
12. How data likely flows through the app
- On startup, runtime helpers preload assets and labels.
- The map layers consume PMTiles and color/label metadata.
- User interaction on the map feeds the selection subsystem.
- Selection and game events update the UI panels and may populate storage JSON.
- The AI layer reads prompt/config state and drives advisor/chat behavior.
- Save directories act as the durable boundary for world state and per-feature history.
13. Architecture summary for diagramming
- Think of the app as four main blocks:
- Runtime/bootstrap: loading, asset prep, startup screen.
- Map/game canvas: world, nations, cities, region selection.
- HUD/UI + AI: actions, chat, advisor, settings, search, time.
- Persistence/assets: PMTiles, JSON metadata, save-slot folders.
- The Node server sits behind the client as a simple host, while the substantive logic is concentrated in the React game modules and the file-based data assets.
Main entry points: World.jsx World · main.jsx HUD · storage Storage · App.jsx App Shell
Components 34
Runtime
Startup and preload layer before the main app mounts.
- Entry · Client entrypoint that mounts the app.
src/main.jsx - App Shell · Top-level application component.
src/App.jsx - Startup · Initial loading and startup experience.
src/runtime/StartupScreen.jsx - Preload · Prepares runtime assets before gameplay.
src/runtime/preload.js - Assets · Runtime asset wiring and manifest helpers.
src/runtime/assets.js - Labels · Country label metadata for rendering and UI.
src/runtime/countryLabels.js
Game Client
Main React game shell and feature subsystems.
- World · Main world map visualization.
src/Game/Map/World.jsx - Nations · Nation overlay and boundary rendering.
src/Game/Map/Nations.jsx - Cities · City overlay and settlement rendering.
src/Game/Map/Cities.jsx - Regions · Region selection and interaction boundary.
src/Game/Selection/Regions.jsx - HUD · Composite gameplay interface and panels.
src/Game/GameUI/main.jsx - Actions · Gameplay action controls and commands.
src/Game/GameUI/actions.jsx - Advisor · AI-guided advice and status panel.
src/Game/GameUI/advisor.jsx - Chat · Conversation and message interface.
src/Game/GameUI/chat.jsx - Search · Lookup and discovery tools.
src/Game/GameUI/search.jsx - Settings · Configuration and preferences.
src/Game/GameUI/settings.jsx - Time · Time progression and timeline controls.
src/Game/GameUI/time.jsx - Other · Auxiliary gameplay controls and extras.
src/Game/GameUI/other.jsx - AI Core · Provider abstraction for advisor/chat behavior.
src/Game/AI/main.jsx - Providers · External model and provider configuration.
src/Game/AI/providerConfig.js
Data & Saves
Bundled assets and save-slot data used by the client.
- Save Slot · Bundled save-slot state and world data.
public/saves/save0 - Game State · Core game state for the save slot.
public/saves/save0/game.json - Prompts · Saved prompt data for AI features.
public/saves/save0/prompts.json - Storage · Per-feature persisted event and conversation state.
public/saves/save0/storage - Action Log · Stored gameplay actions history.
public/saves/save0/storage/actions.json - Advisor Log · Stored advisor state and history.
public/saves/save0/storage/advisor.json - Chat Log · Stored chat messages and context.
public/saves/save0/storage/chat.json - Events · Stored game event history.
public/saves/save0/storage/events.json - PMTiles · Tile-based geospatial datasets used by the map.
countries.pmtiles - Regions Tiles · Saved-region tile dataset for the active slot.
public/saves/save0/regions.pmtiles - Countries Tiles · Saved-country tile dataset for the active slot.
public/saves/save0/countries.pmtiles - Cities Tiles · Saved-city tile dataset for the active slot.
public/saves/save0/cities.pmtiles - Colors · Color palette metadata for presentation.
public/assets/colors.json
Server
Thin Node host for the built frontend.
- Server · Thin Node server for serving the built app.
server/server.js
Connections 33
- Entry → App Shell: boots · Client entry mounts the application shell.
- App Shell → Startup: shows · App presents startup/loading UI while initializing.
- Startup → Preload: waits on · Startup depends on preload completion.
- Preload → Assets: loads · Runtime preload prepares asset metadata.
- Preload → Labels: loads · Runtime preload prepares label metadata.
- App Shell → World: renders · Main app renders the map canvas.
- World → Nations: layers · Nation boundaries are drawn as a world overlay.
- World → Cities: layers · Cities are drawn as a world overlay.
- World → Regions: selects · Map interaction feeds region selection.
- Regions → HUD: updates · Selection state drives the game HUD.
- HUD → Actions: contains · HUD includes gameplay actions.
- HUD → Advisor: contains · HUD includes advisor guidance.
- HUD → Chat: contains · HUD includes chat interface.
- HUD → Search: contains · HUD includes search tools.
- HUD → Settings: contains · HUD includes settings controls.
- HUD → Time: contains · HUD includes time controls.
- HUD → Other: contains · HUD includes auxiliary controls.
- Advisor → AI Core: uses · Advisor interactions are backed by the AI core.
- Chat → AI Core: uses · Chat interactions are backed by the AI core.
- AI Core → Providers: configures · AI core is parameterized by provider config.
- World → PMTiles: reads · Map rendering consumes PMTiles datasets.
- World → Regions Tiles: reads · Saved-region geometry is loaded by the map.
- World → Countries Tiles: reads · Saved-country geometry is loaded by the map.
- World → Cities Tiles: reads · Saved-city geometry is loaded by the map.
- App Shell → Colors: styles · Presentation palette informs rendering.
- Save Slot → Game State: contains · Save slot bundles core game state.
- Save Slot → Prompts: contains · Save slot bundles prompt state.
- Save Slot → Storage: contains · Save slot contains per-feature storage.
- Storage → Action Log: stores · Action history persists separately.
- Storage → Advisor Log: stores · Advisor history persists separately.
- Storage → Chat Log: stores · Chat history persists separately.
- Storage → Events: stores · Event history persists separately.
- Server → App Shell: hosts · Node server serves the built frontend.