# lordbusiness011124/carolina-data-challenge-2026 architecture

> Architecture diagram of the GitHub repository lordbusiness011124/carolina-data-challenge-2026, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lordbusiness011124/carolina-data-challenge-2026
- Repository: https://github.com/lordbusiness011124/carolina-data-challenge-2026

## Overview

Humanity’s Next Move is a turn-based development strategy game that lets players govern a country against real World Bank history. The documented workflow runs from country and year selection, through a live national briefing and ten simulated turns with regional rivals, policies, events and story chapters, to a final comparison of simulated outcomes with real history. A separate data explorer and landing-page progress panel make the source data inspectable. The sampled routes and services establish the server-side data flow; component-to-component wiring and most game-engine calls are not shown, so those links are omitted.

Main entry points: [`src/lib/worldbank/service.ts`](https://github.com/lordbusiness011124/carolina-data-challenge-2026/blob/main/src/lib/worldbank/service.ts) (Data service), [`src/lib/worldbank/client.ts`](https://github.com/lordbusiness011124/carolina-data-challenge-2026/blob/main/src/lib/worldbank/client.ts) (API client), [`src/components/Setup.tsx`](https://github.com/lordbusiness011124/carolina-data-challenge-2026/blob/main/src/components/Setup.tsx) (Game setup), [`src/components/Play.tsx`](https://github.com/lordbusiness011124/carolina-data-challenge-2026/blob/main/src/components/Play.tsx) (Turn play)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_play["Game experience"]
  node_home["Landing page<br/>[page.tsx]"]
  node_setup["Game setup<br/>[Setup.tsx]"]
  node_playgame["Turn play<br/>[Play.tsx]"]
  node_gameui["Game screen<br/>[Game.tsx]"]
  node_board["Regional board<br/>[Board.tsx]"]
  node_story["Turn chronicle<br/>[Story.tsx]"]
  node_revealui["Final reveal<br/>[Reveal.tsx]"]
  node_explorer["Data explorer<br/>[DataExplorer.tsx]"]
end

subgraph group_engine["Simulation engine"]
  node_simulation["Turn simulation<br/>[simulation.ts]"]
  node_rules["Policy rules<br/>[rules.ts]"]
  node_politics["Political events<br/>[politics.ts]"]
  node_impact["Impact ledger<br/>[impact.ts]"]
  node_scoring["Mission scoring<br/>[scoring.ts]"]
end

subgraph group_data["World Bank data"]
  node_service["Data service<br/>[service.ts]"]
  node_package["Data packages<br/>[package.ts]"]
  node_client["API client<br/>[client.ts]"]
  node_normalize["Data normalization<br/>[normalize.ts]"]
end

subgraph group_api["API routes"]
  node_countries["Countries route<br/>[route.ts]"]
  node_setuproute["Setup route<br/>[route.ts]"]
  node_startroute["Start route<br/>[route.ts]"]
  node_rivalsroute["Rivals route<br/>[route.ts]"]
  node_historyroute["History route<br/>[route.ts]"]
  node_revealroute["Reveal route<br/>[route.ts]"]
  node_progressroute["Progress route<br/>[route.ts]"]
  node_verifyroute["Verify route<br/>[route.ts]"]
end

node_player(("Player"))
node_wb(("World Bank API"))

node_player -->|"chooses country"| node_setup
node_player -->|"makes decisions"| node_playgame
node_setup -->|"loads countries"| node_countries
node_setup -->|"checks start years"| node_setuproute
node_setup -->|"loads briefing"| node_startroute
node_playgame -->|"loads rivals"| node_rivalsroute
node_playgame -->|"loads played history"| node_historyroute
node_playgame -->|"requests final history"| node_revealroute
node_home -->|"loads world progress"| node_progressroute
node_explorer -->|"checks indicator data"| node_verifyroute
node_setuproute -->|"calls"| node_service
node_countries -->|"calls"| node_service
node_startroute -->|"calls"| node_service
node_rivalsroute -->|"calls"| node_service
node_historyroute -->|"calls"| node_service
node_revealroute -->|"calls"| node_service
node_progressroute -->|"fetches indicators"| node_client
node_verifyroute -->|"fetches indicator"| node_client
node_service -->|"fetches data"| node_client
node_service -->|"builds packages"| node_package
node_service -->|"converts observations"| node_normalize
node_client -->|"parses pages"| node_normalize
node_client -->|"requests data"| node_wb

click node_home "https://github.com/lordbusiness011124/carolina-data-challenge-2026/blob/main/src/app/page.tsx"
click node_setup "https://github.com/lordbusiness011124/carolina-data-challenge-2026/blob/main/src/components/Setup.tsx"
click node_playgame "https://github.com/lordbusiness011124/carolina-data-challenge-2026/blob/main/src/components/Play.tsx"
click node_gameui "https://github.com/lordbusiness011124/carolina-data-challenge-2026/blob/main/src/components/Game.tsx"
click node_board "https://github.com/lordbusiness011124/carolina-data-challenge-2026/blob/main/src/components/Board.tsx"
click node_story "https://github.com/lordbusiness011124/carolina-data-challenge-2026/blob/main/src/components/Story.tsx"
click node_revealui "https://github.com/lordbusiness011124/carolina-data-challenge-2026/blob/main/src/components/Reveal.tsx"
click node_explorer "https://github.com/lordbusiness011124/carolina-data-challenge-2026/blob/main/src/components/DataExplorer.tsx"
click node_simulation "https://github.com/lordbusiness011124/carolina-data-challenge-2026/blob/main/src/lib/game/simulation.ts"
click node_rules "https://github.com/lordbusiness011124/carolina-data-challenge-2026/blob/main/src/lib/game/rules.ts"
click node_politics "https://github.com/lordbusiness011124/carolina-data-challenge-2026/blob/main/src/lib/game/politics.ts"
click node_impact "https://github.com/lordbusiness011124/carolina-data-challenge-2026/blob/main/src/lib/game/impact.ts"
click node_scoring "https://github.com/lordbusiness011124/carolina-data-challenge-2026/blob/main/src/lib/game/scoring.ts"
click node_service "https://github.com/lordbusiness011124/carolina-data-challenge-2026/blob/main/src/lib/worldbank/service.ts"
click node_package "https://github.com/lordbusiness011124/carolina-data-challenge-2026/blob/main/src/lib/worldbank/package.ts"
click node_client "https://github.com/lordbusiness011124/carolina-data-challenge-2026/blob/main/src/lib/worldbank/client.ts"
click node_normalize "https://github.com/lordbusiness011124/carolina-data-challenge-2026/blob/main/src/lib/worldbank/normalize.ts"
click node_countries "https://github.com/lordbusiness011124/carolina-data-challenge-2026/blob/main/src/app/api/countries/route.ts"
click node_setuproute "https://github.com/lordbusiness011124/carolina-data-challenge-2026/blob/main/src/app/api/setup/route.ts"
click node_startroute "https://github.com/lordbusiness011124/carolina-data-challenge-2026/blob/main/src/app/api/start/route.ts"
click node_rivalsroute "https://github.com/lordbusiness011124/carolina-data-challenge-2026/blob/main/src/app/api/rivals/route.ts"
click node_historyroute "https://github.com/lordbusiness011124/carolina-data-challenge-2026/blob/main/src/app/api/history/route.ts"
click node_revealroute "https://github.com/lordbusiness011124/carolina-data-challenge-2026/blob/main/src/app/api/reveal/route.ts"
click node_progressroute "https://github.com/lordbusiness011124/carolina-data-challenge-2026/blob/main/src/app/api/progress/route.ts"
click node_verifyroute "https://github.com/lordbusiness011124/carolina-data-challenge-2026/blob/main/src/app/api/verify/route.ts"

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_home,node_setup,node_playgame,node_gameui,node_board,node_story,node_revealui,node_explorer toneBlue
class node_simulation,node_rules,node_politics,node_impact,node_scoring toneAmber
class node_service,node_package,node_client,node_normalize,node_wb toneMint
class node_countries,node_setuproute,node_startroute,node_rivalsroute,node_historyroute,node_revealroute,node_progressroute,node_verifyroute toneRose
class node_player toneIndigo
```

## Components

### Game experience

- [Landing page](https://github.com/lordbusiness011124/carolina-data-challenge-2026/blob/main/src/app/page.tsx): `src/app/page.tsx`
- [Game setup](https://github.com/lordbusiness011124/carolina-data-challenge-2026/blob/main/src/components/Setup.tsx): `src/components/Setup.tsx`
- [Turn play](https://github.com/lordbusiness011124/carolina-data-challenge-2026/blob/main/src/components/Play.tsx): `src/components/Play.tsx`
- [Game screen](https://github.com/lordbusiness011124/carolina-data-challenge-2026/blob/main/src/components/Game.tsx): `src/components/Game.tsx`
- [Regional board](https://github.com/lordbusiness011124/carolina-data-challenge-2026/blob/main/src/components/Board.tsx): `src/components/Board.tsx`
- [Turn chronicle](https://github.com/lordbusiness011124/carolina-data-challenge-2026/blob/main/src/components/Story.tsx): `src/components/Story.tsx`
- [Final reveal](https://github.com/lordbusiness011124/carolina-data-challenge-2026/blob/main/src/components/Reveal.tsx): `src/components/Reveal.tsx`
- [Data explorer](https://github.com/lordbusiness011124/carolina-data-challenge-2026/blob/main/src/components/DataExplorer.tsx): `src/components/DataExplorer.tsx`

### Simulation engine

- [Turn simulation](https://github.com/lordbusiness011124/carolina-data-challenge-2026/blob/main/src/lib/game/simulation.ts): `src/lib/game/simulation.ts`
- [Policy rules](https://github.com/lordbusiness011124/carolina-data-challenge-2026/blob/main/src/lib/game/rules.ts): `src/lib/game/rules.ts`
- [Political events](https://github.com/lordbusiness011124/carolina-data-challenge-2026/blob/main/src/lib/game/politics.ts): `src/lib/game/politics.ts`
- [Impact ledger](https://github.com/lordbusiness011124/carolina-data-challenge-2026/blob/main/src/lib/game/impact.ts): `src/lib/game/impact.ts`
- [Mission scoring](https://github.com/lordbusiness011124/carolina-data-challenge-2026/blob/main/src/lib/game/scoring.ts): `src/lib/game/scoring.ts`

### World Bank data

- [Data service](https://github.com/lordbusiness011124/carolina-data-challenge-2026/blob/main/src/lib/worldbank/service.ts): `src/lib/worldbank/service.ts`
- [Data packages](https://github.com/lordbusiness011124/carolina-data-challenge-2026/blob/main/src/lib/worldbank/package.ts): `src/lib/worldbank/package.ts`
- [API client](https://github.com/lordbusiness011124/carolina-data-challenge-2026/blob/main/src/lib/worldbank/client.ts): `src/lib/worldbank/client.ts`
- [Data normalization](https://github.com/lordbusiness011124/carolina-data-challenge-2026/blob/main/src/lib/worldbank/normalize.ts): `src/lib/worldbank/normalize.ts`

### API routes

- [Countries route](https://github.com/lordbusiness011124/carolina-data-challenge-2026/blob/main/src/app/api/countries/route.ts): `src/app/api/countries/route.ts`
- [Setup route](https://github.com/lordbusiness011124/carolina-data-challenge-2026/blob/main/src/app/api/setup/route.ts): `src/app/api/setup/route.ts`
- [Start route](https://github.com/lordbusiness011124/carolina-data-challenge-2026/blob/main/src/app/api/start/route.ts): `src/app/api/start/route.ts`
- [Rivals route](https://github.com/lordbusiness011124/carolina-data-challenge-2026/blob/main/src/app/api/rivals/route.ts): `src/app/api/rivals/route.ts`
- [History route](https://github.com/lordbusiness011124/carolina-data-challenge-2026/blob/main/src/app/api/history/route.ts): `src/app/api/history/route.ts`
- [Reveal route](https://github.com/lordbusiness011124/carolina-data-challenge-2026/blob/main/src/app/api/reveal/route.ts): `src/app/api/reveal/route.ts`
- [Progress route](https://github.com/lordbusiness011124/carolina-data-challenge-2026/blob/main/src/app/api/progress/route.ts): `src/app/api/progress/route.ts`
- [Verify route](https://github.com/lordbusiness011124/carolina-data-challenge-2026/blob/main/src/app/api/verify/route.ts): `src/app/api/verify/route.ts`

### Other components

- **Player**
- **World Bank API**

## Connections

- Player → Game setup: chooses country
- Player → Turn play: makes decisions
- Game setup → Countries route: loads countries
- Game setup → Setup route: checks start years
- Game setup → Start route: loads briefing
- Turn play → Rivals route: loads rivals
- Turn play → History route: loads played history
- Turn play → Reveal route: requests final history
- Landing page → Progress route: loads world progress
- Data explorer → Verify route: checks indicator data
- Setup route → Data service: calls
- Countries route → Data service: calls
- Start route → Data service: calls
- Rivals route → Data service: calls
- History route → Data service: calls
- Reveal route → Data service: calls
- Progress route → API client: fetches indicators
- Verify route → API client: fetches indicator
- Data service → API client: fetches data
- Data service → Data packages: builds packages
- Data service → Data normalization: converts observations
- API client → Data normalization: parses pages
- API client → World Bank API: requests data