# charlesokeke1/economic-simulation architecture

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

- Interactive diagram: https://gitdiagram.com/charlesokeke1/economic-simulation
- Repository: https://github.com/charlesokeke1/economic-simulation

## Overview

This is a JavaFX Nigerian economy simulation game. The player selects a state and policy, then the monthly simulation applies federal accounting and state policies, triggers events, updates rankings, and periodically runs elections; the interface presents the resulting economy through dashboards and reports. The graph emphasizes that orchestration and the major economic, event, AI, and election branches. Several links are based on the sampled SimulationEngine and UI excerpts; unsampled subsystems are included only where their role is clear from the tree.

Main entry points: [`src/main/java/backend/engine/SimulationEngine.java`](https://github.com/charlesokeke1/economic-simulation/blob/main/src/main/java/backend/engine/SimulationEngine.java) (Monthly simulation), [`src/main/java/backend/economies/StateEconomy.java`](https://github.com/charlesokeke1/economic-simulation/blob/main/src/main/java/backend/economies/StateEconomy.java) (State economy), [`src/main/java/frontend/gui/HomeScreen.java`](https://github.com/charlesokeke1/economic-simulation/blob/main/src/main/java/frontend/gui/HomeScreen.java) (Game dashboard), [`src/main/java/backend/engine/FederalAccountingEngine.java`](https://github.com/charlesokeke1/economic-simulation/blob/main/src/main/java/backend/engine/FederalAccountingEngine.java) (Federal accounting)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Player interface"]
  node_app["Application<br/>[AppMain.java]"]
  node_home["Game dashboard<br/>[HomeScreen.java]"]
  node_reports["Economic reports<br/>[PrintReports.java]"]
end

subgraph group_simulation["Simulation workflow"]
  node_initializer["Game initializer<br/>[Initializer.java]"]
  node_simulation_engine["Monthly simulation"]
end

subgraph group_economy["Economic model"]
  node_state_model["State economy<br/>[StateEconomy.java]"]
  node_federal_model["Federal economy"]
  node_economy_seed["Starting economies"]
  node_accounting["Federal accounting"]
  node_policy["Policy application<br/>[PolicyEngine.java]"]
end

subgraph group_events_ai["Events and AI"]
  node_event_trigger["Event triggers<br/>[EventTrigger.java]"]
  node_ai_policy["AI policy choice<br/>[AiPolicyMaker.java]"]
  node_policy_checks["Policy checks<br/>[PolicyChecks.java]"]
end

subgraph group_results["Results"]
  node_ranking["State rankings<br/>[RankingEngine.java]"]
  node_elections["Elections"]
  node_telemetry["Month telemetry<br/>[Telemetry.java]"]
end

node_player(("Player"))

node_player -->|"chooses policy"| node_home
node_app -->|"opens interface"| node_home
node_initializer -->|"creates economies"| node_economy_seed
node_simulation_engine -->|"runs accounting"| node_accounting
node_simulation_engine -->|"applies policies"| node_policy
node_simulation_engine -->|"triggers events"| node_event_trigger
node_simulation_engine -->|"calculates ranks"| node_ranking
node_simulation_engine -->|"runs periodically"| node_elections
node_simulation_engine -->|"logs month"| node_telemetry
node_simulation_engine -->|"chooses AI policy"| node_ai_policy
node_simulation_engine -->|"checks AI policy"| node_policy_checks
node_home -->|"advances simulation"| node_simulation_engine
node_home -->|"reads state"| node_state_model
node_reports -->|"reads state"| node_state_model
node_reports -->|"reads federation"| node_federal_model
node_accounting -->|"updates allocations"| node_state_model
node_accounting -->|"updates totals"| node_federal_model
node_policy -->|"updates state"| node_state_model
node_ranking -->|"updates positions"| node_state_model
node_elections -->|"updates governments"| node_state_model

click node_app "https://github.com/charlesokeke1/economic-simulation/blob/main/src/main/java/frontend/gui/AppMain.java"
click node_home "https://github.com/charlesokeke1/economic-simulation/blob/main/src/main/java/frontend/gui/HomeScreen.java"
click node_reports "https://github.com/charlesokeke1/economic-simulation/blob/main/src/main/java/frontend/ui/PrintReports.java"
click node_initializer "https://github.com/charlesokeke1/economic-simulation/blob/main/src/main/java/frontend/ui/Initializer.java"
click node_simulation_engine "https://github.com/charlesokeke1/economic-simulation/blob/main/src/main/java/backend/engine/SimulationEngine.java"
click node_state_model "https://github.com/charlesokeke1/economic-simulation/blob/main/src/main/java/backend/economies/StateEconomy.java"
click node_federal_model "https://github.com/charlesokeke1/economic-simulation/blob/main/src/main/java/backend/economies/FederalEconomy.java"
click node_economy_seed "https://github.com/charlesokeke1/economic-simulation/blob/main/src/main/java/backend/data/EconomyInitializer.java"
click node_accounting "https://github.com/charlesokeke1/economic-simulation/blob/main/src/main/java/backend/engine/FederalAccountingEngine.java"
click node_policy "https://github.com/charlesokeke1/economic-simulation/blob/main/src/main/java/backend/engine/PolicyEngine.java"
click node_ranking "https://github.com/charlesokeke1/economic-simulation/blob/main/src/main/java/backend/engine/RankingEngine.java"
click node_elections "https://github.com/charlesokeke1/economic-simulation/blob/main/src/main/java/backend/election/ElectionEngine.java"
click node_event_trigger "https://github.com/charlesokeke1/economic-simulation/blob/main/src/main/java/backend/events/EventTrigger.java"
click node_ai_policy "https://github.com/charlesokeke1/economic-simulation/blob/main/src/main/java/backend/engine/AiPolicyMaker.java"
click node_policy_checks "https://github.com/charlesokeke1/economic-simulation/blob/main/src/main/java/backend/AI/PolicyChecks.java"
click node_telemetry "https://github.com/charlesokeke1/economic-simulation/blob/main/src/main/java/backend/analytics/Telemetry.java"

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_app,node_home,node_reports toneBlue
class node_initializer,node_simulation_engine toneAmber
class node_state_model,node_federal_model,node_economy_seed,node_accounting,node_policy toneMint
class node_event_trigger,node_ai_policy,node_policy_checks toneRose
class node_ranking,node_elections,node_telemetry,node_player toneIndigo
```

## Components

### Player interface

- [Application](https://github.com/charlesokeke1/economic-simulation/blob/main/src/main/java/frontend/gui/AppMain.java): `src/main/java/frontend/gui/AppMain.java`
- [Game dashboard](https://github.com/charlesokeke1/economic-simulation/blob/main/src/main/java/frontend/gui/HomeScreen.java): `src/main/java/frontend/gui/HomeScreen.java`
- [Economic reports](https://github.com/charlesokeke1/economic-simulation/blob/main/src/main/java/frontend/ui/PrintReports.java): `src/main/java/frontend/ui/PrintReports.java`

### Simulation workflow

- [Game initializer](https://github.com/charlesokeke1/economic-simulation/blob/main/src/main/java/frontend/ui/Initializer.java): `src/main/java/frontend/ui/Initializer.java`
- [Monthly simulation](https://github.com/charlesokeke1/economic-simulation/blob/main/src/main/java/backend/engine/SimulationEngine.java): `src/main/java/backend/engine/SimulationEngine.java`

### Economic model

- [State economy](https://github.com/charlesokeke1/economic-simulation/blob/main/src/main/java/backend/economies/StateEconomy.java): `src/main/java/backend/economies/StateEconomy.java`
- [Federal economy](https://github.com/charlesokeke1/economic-simulation/blob/main/src/main/java/backend/economies/FederalEconomy.java): `src/main/java/backend/economies/FederalEconomy.java`
- [Starting economies](https://github.com/charlesokeke1/economic-simulation/blob/main/src/main/java/backend/data/EconomyInitializer.java): `src/main/java/backend/data/EconomyInitializer.java`
- [Federal accounting](https://github.com/charlesokeke1/economic-simulation/blob/main/src/main/java/backend/engine/FederalAccountingEngine.java): `src/main/java/backend/engine/FederalAccountingEngine.java`
- [Policy application](https://github.com/charlesokeke1/economic-simulation/blob/main/src/main/java/backend/engine/PolicyEngine.java): `src/main/java/backend/engine/PolicyEngine.java`

### Events and AI

- [Event triggers](https://github.com/charlesokeke1/economic-simulation/blob/main/src/main/java/backend/events/EventTrigger.java): `src/main/java/backend/events/EventTrigger.java`
- [AI policy choice](https://github.com/charlesokeke1/economic-simulation/blob/main/src/main/java/backend/engine/AiPolicyMaker.java): `src/main/java/backend/engine/AiPolicyMaker.java`
- [Policy checks](https://github.com/charlesokeke1/economic-simulation/blob/main/src/main/java/backend/AI/PolicyChecks.java): `src/main/java/backend/AI/PolicyChecks.java`

### Results

- [State rankings](https://github.com/charlesokeke1/economic-simulation/blob/main/src/main/java/backend/engine/RankingEngine.java): `src/main/java/backend/engine/RankingEngine.java`
- [Elections](https://github.com/charlesokeke1/economic-simulation/blob/main/src/main/java/backend/election/ElectionEngine.java): `src/main/java/backend/election/ElectionEngine.java`
- [Month telemetry](https://github.com/charlesokeke1/economic-simulation/blob/main/src/main/java/backend/analytics/Telemetry.java): `src/main/java/backend/analytics/Telemetry.java`

### Other components

- **Player**

## Connections

- Player → Game dashboard: chooses policy
- Application → Game dashboard: opens interface
- Game initializer → Starting economies: creates economies
- Monthly simulation → Federal accounting: runs accounting
- Monthly simulation → Policy application: applies policies
- Monthly simulation → Event triggers: triggers events
- Monthly simulation → State rankings: calculates ranks
- Monthly simulation → Elections: runs periodically
- Monthly simulation → Month telemetry: logs month
- Monthly simulation → AI policy choice: chooses AI policy
- Monthly simulation → Policy checks: checks AI policy
- Game dashboard → Monthly simulation: advances simulation
- Game dashboard → State economy: reads state
- Economic reports → State economy: reads state
- Economic reports → Federal economy: reads federation
- Federal accounting → State economy: updates allocations
- Federal accounting → Federal economy: updates totals
- Policy application → State economy: updates state
- State rankings → State economy: updates positions
- Elections → State economy: updates governments