# tommi-k/pax-historia architecture

> Architecture diagram of the GitHub repository tommi-k/pax-historia, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tommi-k/pax-historia
- Repository: https://github.com/tommi-k/pax-historia

## Overview

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: [`src/Game/Map/World.jsx`](https://github.com/tommi-k/pax-historia/blob/main/src/Game/Map/World.jsx) (World), [`src/Game/GameUI/main.jsx`](https://github.com/tommi-k/pax-historia/blob/main/src/Game/GameUI/main.jsx) (HUD), [`public/saves/save0/storage`](https://github.com/tommi-k/pax-historia/tree/main/public/saves/save0/storage) (Storage), [`src/App.jsx`](https://github.com/tommi-k/pax-historia/blob/main/src/App.jsx) (App Shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_main(("Entry<br/>Vite bootstrap<br/>[main.jsx]"))
  node_app["App Shell<br/>React root<br/>[App.jsx]"]
  node_startup["Startup<br/>loading screen<br/>[StartupScreen.jsx]"]
  node_preload["Preload<br/>asset loader<br/>[preload.js]"]
  node_assets["Assets<br/>runtime data<br/>[assets.js]"]
  node_labels["Labels<br/>metadata<br/>[countryLabels.js]"]
end

subgraph group_game["Game Client"]
  node_world["World<br/>map layer<br/>[World.jsx]"]
  node_nations["Nations<br/>map layer<br/>[Nations.jsx]"]
  node_cities["Cities<br/>map layer<br/>[Cities.jsx]"]
  node_regions["Regions<br/>selection<br/>[Regions.jsx]"]
  node_ui["HUD<br/>game ui<br/>[main.jsx]"]
  node_actions["Actions<br/>ui panel<br/>[actions.jsx]"]
  node_advisor["Advisor<br/>ui panel<br/>[advisor.jsx]"]
  node_chat["Chat<br/>ui panel<br/>[chat.jsx]"]
  node_search["Search<br/>ui panel<br/>[search.jsx]"]
  node_settings["Settings<br/>ui panel<br/>[settings.jsx]"]
  node_time["Time<br/>ui panel<br/>[time.jsx]"]
  node_other["Other<br/>ui panel<br/>[other.jsx]"]
  node_ai["AI Core<br/>model adapter<br/>[main.jsx]"]
  node_providers["Providers<br/>ai config<br/>[providerConfig.js]"]
end

subgraph group_data["Data & Saves"]
  node_save[("Save Slot<br/>persistent state")]
  node_gamejson["Game State<br/>save json<br/>[game.json]"]
  node_prompts["Prompts<br/>ai state<br/>[prompts.json]"]
  node_storage[("Storage<br/>feature history")]
  node_actionslog["Action Log<br/>persisted log<br/>[actions.json]"]
  node_advisorlog["Advisor Log<br/>persisted log<br/>[advisor.json]"]
  node_chatlog["Chat Log<br/>persisted log<br/>[chat.json]"]
  node_events["Events<br/>persisted log<br/>[events.json]"]
  node_tiles[("PMTiles<br/>map data<br/>[countries.pmtiles]")]
  node_regiontiles[("Regions Tiles<br/>map data<br/>[regions.pmtiles]")]
  node_countrytiles[("Countries Tiles<br/>map data<br/>[countries.pmtiles]")]
  node_citytiles[("Cities Tiles<br/>map data<br/>[cities.pmtiles]")]
  node_colors["Colors<br/>palette data<br/>[colors.json]"]
end

subgraph group_server["Server"]
  node_serverjs["Server<br/>Node host<br/>[server.js]"]
end

node_main -->|"boots"| node_app
node_app -->|"shows"| node_startup
node_startup -->|"waits on"| node_preload
node_preload -->|"loads"| node_assets
node_preload -->|"loads"| node_labels
node_app -->|"renders"| node_world
node_world -->|"layers"| node_nations
node_world -->|"layers"| node_cities
node_world -->|"selects"| node_regions
node_regions -->|"updates"| node_ui
node_ui -->|"contains"| node_actions
node_ui -->|"contains"| node_advisor
node_ui -->|"contains"| node_chat
node_ui -->|"contains"| node_search
node_ui -->|"contains"| node_settings
node_ui -->|"contains"| node_time
node_ui -->|"contains"| node_other
node_advisor -->|"uses"| node_ai
node_chat -->|"uses"| node_ai
node_ai -->|"configures"| node_providers
node_world -->|"reads"| node_tiles
node_world -->|"reads"| node_regiontiles
node_world -->|"reads"| node_countrytiles
node_world -->|"reads"| node_citytiles
node_app -->|"styles"| node_colors
node_save -->|"contains"| node_gamejson
node_save -->|"contains"| node_prompts
node_save -->|"contains"| node_storage
node_storage -->|"stores"| node_actionslog
node_storage -->|"stores"| node_advisorlog
node_storage -->|"stores"| node_chatlog
node_storage -->|"stores"| node_events
node_serverjs -->|"hosts"| node_app

click node_main "https://github.com/tommi-k/pax-historia/blob/main/src/main.jsx"
click node_app "https://github.com/tommi-k/pax-historia/blob/main/src/App.jsx"
click node_startup "https://github.com/tommi-k/pax-historia/blob/main/src/runtime/StartupScreen.jsx"
click node_preload "https://github.com/tommi-k/pax-historia/blob/main/src/runtime/preload.js"
click node_assets "https://github.com/tommi-k/pax-historia/blob/main/src/runtime/assets.js"
click node_labels "https://github.com/tommi-k/pax-historia/blob/main/src/runtime/countryLabels.js"
click node_world "https://github.com/tommi-k/pax-historia/blob/main/src/Game/Map/World.jsx"
click node_nations "https://github.com/tommi-k/pax-historia/blob/main/src/Game/Map/Nations.jsx"
click node_cities "https://github.com/tommi-k/pax-historia/blob/main/src/Game/Map/Cities.jsx"
click node_regions "https://github.com/tommi-k/pax-historia/blob/main/src/Game/Selection/Regions.jsx"
click node_ui "https://github.com/tommi-k/pax-historia/blob/main/src/Game/GameUI/main.jsx"
click node_actions "https://github.com/tommi-k/pax-historia/blob/main/src/Game/GameUI/actions.jsx"
click node_advisor "https://github.com/tommi-k/pax-historia/blob/main/src/Game/GameUI/advisor.jsx"
click node_chat "https://github.com/tommi-k/pax-historia/blob/main/src/Game/GameUI/chat.jsx"
click node_search "https://github.com/tommi-k/pax-historia/blob/main/src/Game/GameUI/search.jsx"
click node_settings "https://github.com/tommi-k/pax-historia/blob/main/src/Game/GameUI/settings.jsx"
click node_time "https://github.com/tommi-k/pax-historia/blob/main/src/Game/GameUI/time.jsx"
click node_other "https://github.com/tommi-k/pax-historia/blob/main/src/Game/GameUI/other.jsx"
click node_ai "https://github.com/tommi-k/pax-historia/blob/main/src/Game/AI/main.jsx"
click node_providers "https://github.com/tommi-k/pax-historia/blob/main/src/Game/AI/providerConfig.js"
click node_save "https://github.com/tommi-k/pax-historia/tree/main/public/saves/save0"
click node_gamejson "https://github.com/tommi-k/pax-historia/blob/main/public/saves/save0/game.json"
click node_prompts "https://github.com/tommi-k/pax-historia/blob/main/public/saves/save0/prompts.json"
click node_storage "https://github.com/tommi-k/pax-historia/tree/main/public/saves/save0/storage"
click node_actionslog "https://github.com/tommi-k/pax-historia/blob/main/public/saves/save0/storage/actions.json"
click node_advisorlog "https://github.com/tommi-k/pax-historia/blob/main/public/saves/save0/storage/advisor.json"
click node_chatlog "https://github.com/tommi-k/pax-historia/blob/main/public/saves/save0/storage/chat.json"
click node_events "https://github.com/tommi-k/pax-historia/blob/main/public/saves/save0/storage/events.json"
click node_tiles "https://github.com/tommi-k/pax-historia/blob/main/countries.pmtiles"
click node_regiontiles "https://github.com/tommi-k/pax-historia/blob/main/public/saves/save0/regions.pmtiles"
click node_countrytiles "https://github.com/tommi-k/pax-historia/blob/main/public/saves/save0/countries.pmtiles"
click node_citytiles "https://github.com/tommi-k/pax-historia/blob/main/public/saves/save0/cities.pmtiles"
click node_colors "https://github.com/tommi-k/pax-historia/blob/main/public/assets/colors.json"
click node_serverjs "https://github.com/tommi-k/pax-historia/blob/main/server/server.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_app,node_startup,node_preload,node_assets,node_labels toneBlue
class node_world,node_nations,node_cities,node_regions,node_ui,node_actions,node_advisor,node_chat,node_search,node_settings,node_time,node_other,node_ai,node_providers toneAmber
class node_save,node_gamejson,node_prompts,node_storage,node_actionslog,node_advisorlog,node_chatlog,node_events,node_tiles,node_regiontiles,node_countrytiles,node_citytiles,node_colors toneMint
class node_serverjs toneRose
```

## Components

### Runtime

Startup and preload layer before the main app mounts.

- [Entry](https://github.com/tommi-k/pax-historia/blob/main/src/main.jsx): Vite bootstrap · Client entrypoint that mounts the app. · `src/main.jsx`
- [App Shell](https://github.com/tommi-k/pax-historia/blob/main/src/App.jsx): React root · Top-level application component. · `src/App.jsx`
- [Startup](https://github.com/tommi-k/pax-historia/blob/main/src/runtime/StartupScreen.jsx): loading screen · Initial loading and startup experience. · `src/runtime/StartupScreen.jsx`
- [Preload](https://github.com/tommi-k/pax-historia/blob/main/src/runtime/preload.js): asset loader · Prepares runtime assets before gameplay. · `src/runtime/preload.js`
- [Assets](https://github.com/tommi-k/pax-historia/blob/main/src/runtime/assets.js): runtime data · Runtime asset wiring and manifest helpers. · `src/runtime/assets.js`
- [Labels](https://github.com/tommi-k/pax-historia/blob/main/src/runtime/countryLabels.js): metadata · Country label metadata for rendering and UI. · `src/runtime/countryLabels.js`

### Game Client

Main React game shell and feature subsystems.

- [World](https://github.com/tommi-k/pax-historia/blob/main/src/Game/Map/World.jsx): map layer · Main world map visualization. · `src/Game/Map/World.jsx`
- [Nations](https://github.com/tommi-k/pax-historia/blob/main/src/Game/Map/Nations.jsx): map layer · Nation overlay and boundary rendering. · `src/Game/Map/Nations.jsx`
- [Cities](https://github.com/tommi-k/pax-historia/blob/main/src/Game/Map/Cities.jsx): map layer · City overlay and settlement rendering. · `src/Game/Map/Cities.jsx`
- [Regions](https://github.com/tommi-k/pax-historia/blob/main/src/Game/Selection/Regions.jsx): selection · Region selection and interaction boundary. · `src/Game/Selection/Regions.jsx`
- [HUD](https://github.com/tommi-k/pax-historia/blob/main/src/Game/GameUI/main.jsx): game ui · Composite gameplay interface and panels. · `src/Game/GameUI/main.jsx`
- [Actions](https://github.com/tommi-k/pax-historia/blob/main/src/Game/GameUI/actions.jsx): ui panel · Gameplay action controls and commands. · `src/Game/GameUI/actions.jsx`
- [Advisor](https://github.com/tommi-k/pax-historia/blob/main/src/Game/GameUI/advisor.jsx): ui panel · AI-guided advice and status panel. · `src/Game/GameUI/advisor.jsx`
- [Chat](https://github.com/tommi-k/pax-historia/blob/main/src/Game/GameUI/chat.jsx): ui panel · Conversation and message interface. · `src/Game/GameUI/chat.jsx`
- [Search](https://github.com/tommi-k/pax-historia/blob/main/src/Game/GameUI/search.jsx): ui panel · Lookup and discovery tools. · `src/Game/GameUI/search.jsx`
- [Settings](https://github.com/tommi-k/pax-historia/blob/main/src/Game/GameUI/settings.jsx): ui panel · Configuration and preferences. · `src/Game/GameUI/settings.jsx`
- [Time](https://github.com/tommi-k/pax-historia/blob/main/src/Game/GameUI/time.jsx): ui panel · Time progression and timeline controls. · `src/Game/GameUI/time.jsx`
- [Other](https://github.com/tommi-k/pax-historia/blob/main/src/Game/GameUI/other.jsx): ui panel · Auxiliary gameplay controls and extras. · `src/Game/GameUI/other.jsx`
- [AI Core](https://github.com/tommi-k/pax-historia/blob/main/src/Game/AI/main.jsx): model adapter · Provider abstraction for advisor/chat behavior. · `src/Game/AI/main.jsx`
- [Providers](https://github.com/tommi-k/pax-historia/blob/main/src/Game/AI/providerConfig.js): ai config · External model and provider configuration. · `src/Game/AI/providerConfig.js`

### Data & Saves

Bundled assets and save-slot data used by the client.

- [Save Slot](https://github.com/tommi-k/pax-historia/tree/main/public/saves/save0): persistent state · Bundled save-slot state and world data. · `public/saves/save0`
- [Game State](https://github.com/tommi-k/pax-historia/blob/main/public/saves/save0/game.json): save json · Core game state for the save slot. · `public/saves/save0/game.json`
- [Prompts](https://github.com/tommi-k/pax-historia/blob/main/public/saves/save0/prompts.json): ai state · Saved prompt data for AI features. · `public/saves/save0/prompts.json`
- [Storage](https://github.com/tommi-k/pax-historia/tree/main/public/saves/save0/storage): feature history · Per-feature persisted event and conversation state. · `public/saves/save0/storage`
- [Action Log](https://github.com/tommi-k/pax-historia/blob/main/public/saves/save0/storage/actions.json): persisted log · Stored gameplay actions history. · `public/saves/save0/storage/actions.json`
- [Advisor Log](https://github.com/tommi-k/pax-historia/blob/main/public/saves/save0/storage/advisor.json): persisted log · Stored advisor state and history. · `public/saves/save0/storage/advisor.json`
- [Chat Log](https://github.com/tommi-k/pax-historia/blob/main/public/saves/save0/storage/chat.json): persisted log · Stored chat messages and context. · `public/saves/save0/storage/chat.json`
- [Events](https://github.com/tommi-k/pax-historia/blob/main/public/saves/save0/storage/events.json): persisted log · Stored game event history. · `public/saves/save0/storage/events.json`
- [PMTiles](https://github.com/tommi-k/pax-historia/blob/main/countries.pmtiles): map data · Tile-based geospatial datasets used by the map. · `countries.pmtiles`
- [Regions Tiles](https://github.com/tommi-k/pax-historia/blob/main/public/saves/save0/regions.pmtiles): map data · Saved-region tile dataset for the active slot. · `public/saves/save0/regions.pmtiles`
- [Countries Tiles](https://github.com/tommi-k/pax-historia/blob/main/public/saves/save0/countries.pmtiles): map data · Saved-country tile dataset for the active slot. · `public/saves/save0/countries.pmtiles`
- [Cities Tiles](https://github.com/tommi-k/pax-historia/blob/main/public/saves/save0/cities.pmtiles): map data · Saved-city tile dataset for the active slot. · `public/saves/save0/cities.pmtiles`
- [Colors](https://github.com/tommi-k/pax-historia/blob/main/public/assets/colors.json): palette data · Color palette metadata for presentation. · `public/assets/colors.json`

### Server

Thin Node host for the built frontend.

- [Server](https://github.com/tommi-k/pax-historia/blob/main/server/server.js): Node host · Thin Node server for serving the built app. · `server/server.js`

## Connections

- 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.
