# mad1izjod/business-simulator architecture

> Architecture diagram of the GitHub repository mad1izjod/business-simulator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mad1izjod/business-simulator
- Repository: https://github.com/mad1izjod/business-simulator

## Overview

Business Simulator is a browser-based, single-player company simulation: the player creates a company, issues validated decisions, advances time, and explores the resulting business and financial outcomes. The React UI is backed by a pure TypeScript engine; a controller owns the live state, clock, and saves. Daily and month-end simulation stages update interconnected domains, with financial statements derived from ledger postings. README documentation establishes several domain capabilities whose detailed source wiring was not sampled, so those branches are shown without speculative internal call chains.

Main entry points: [`src/engine/step.ts`](https://github.com/mad1izjod/business-simulator/blob/main/src/engine/step.ts) (Daily and monthly loop), [`src/ui/game/controller.ts`](https://github.com/mad1izjod/business-simulator/blob/main/src/ui/game/controller.ts) (Game controller), [`src/engine/systems/ledger.ts`](https://github.com/mad1izjod/business-simulator/blob/main/src/engine/systems/ledger.ts) (Accounting ledger), [`src/engine/create.ts`](https://github.com/mad1izjod/business-simulator/blob/main/src/engine/create.ts) (Company initialization)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Player interface"]
  node_onboarding["Company setup<br/>[CreateCompany.tsx]"]
  node_app["App shell<br/>[App.tsx]"]
  node_pages["Simulation pages"]
end

subgraph group_runtime["Simulation runtime"]
  node_controller["Game controller<br/>[controller.ts]"]
  node_engine["Daily and monthly loop<br/>[step.ts]"]
  node_commands["Validated commands<br/>[commands.ts]"]
  node_company["Company initialization<br/>[create.ts]"]
end

subgraph group_business["Business operations"]
  node_market["Demand and sales<br/>[market.ts]"]
  node_products["Products and R&amp;D<br/>[products.ts]"]
  node_operations["Supply and production"]
  node_people["Employees and hiring"]
  node_growth["Growth and corporate actions"]
  node_definitions["Industry and market data<br/>[industries.ts]"]
end

subgraph group_finance["Finance and world"]
  node_ledger["Accounting ledger<br/>[ledger.ts]"]
  node_finance["Debt and capital"]
  node_world["Markets and events"]
end

subgraph group_insight["Analysis and persistence"]
  node_reports["Reports and insights<br/>[insights.ts]"]
  node_explain["Metric explanations<br/>[explain.ts]"]
  node_projection["Forecasts and scenarios<br/>[projection.ts]"]
  node_worker["Forecast worker"]
  node_storage[("Browser saves<br/>[storage.ts]")]
  node_serialization["Save serialization<br/>[serialize.ts]"]
end

node_player(("Player"))

node_player -->|"sets up"| node_onboarding
node_onboarding -->|"creates company"| node_company
node_app -->|"shows before game"| node_onboarding
node_app -->|"subscribes to"| node_controller
node_app -->|"selects page"| node_pages
node_player -->|"reviews and decides"| node_pages
node_pages -->|"dispatches actions"| node_controller
node_controller -->|"dispatches"| node_commands
node_controller -->|"advances time"| node_engine
node_controller -->|"starts game"| node_company
node_company -->|"uses configuration"| node_definitions
node_company -->|"initializes accounts"| node_ledger
node_engine -.->|"runs simulation"| node_market
node_engine -.->|"runs simulation"| node_products
node_engine -.->|"runs simulation"| node_operations
node_engine -.->|"runs simulation"| node_people
node_engine -.->|"runs simulation"| node_finance
node_engine -.->|"runs simulation"| node_world
node_market -->|"reads product data"| node_products
node_market -->|"posts activity"| node_ledger
node_products -->|"posts expenses"| node_ledger
node_products -->|"reads industry data"| node_definitions
node_operations -.->|"records transactions"| node_ledger
node_people -.->|"records transactions"| node_ledger
node_finance -.->|"records transactions"| node_ledger
node_growth -.->|"records transactions"| node_ledger
node_engine -.->|"closes reporting"| node_reports
node_controller -->|"requests forecasts"| node_projection
node_projection -->|"simulates copy"| node_engine
node_controller -->|"creates worker"| node_worker
node_worker -->|"runs forecast"| node_projection
node_app -->|"opens explanations"| node_explain
node_controller -->|"saves game"| node_storage
node_storage -->|"serializes saves"| node_serialization
node_serialization -->|"recreates save"| node_company

click node_onboarding "https://github.com/mad1izjod/business-simulator/blob/main/src/ui/onboarding/CreateCompany.tsx"
click node_app "https://github.com/mad1izjod/business-simulator/blob/main/src/ui/App.tsx"
click node_pages "https://github.com/mad1izjod/business-simulator/tree/main/src/ui/pages"
click node_controller "https://github.com/mad1izjod/business-simulator/blob/main/src/ui/game/controller.ts"
click node_engine "https://github.com/mad1izjod/business-simulator/blob/main/src/engine/step.ts"
click node_commands "https://github.com/mad1izjod/business-simulator/blob/main/src/engine/commands.ts"
click node_company "https://github.com/mad1izjod/business-simulator/blob/main/src/engine/create.ts"
click node_market "https://github.com/mad1izjod/business-simulator/blob/main/src/engine/systems/market.ts"
click node_products "https://github.com/mad1izjod/business-simulator/blob/main/src/engine/systems/products.ts"
click node_operations "https://github.com/mad1izjod/business-simulator/tree/main/src/engine/systems"
click node_people "https://github.com/mad1izjod/business-simulator/tree/main/src/engine/systems"
click node_growth "https://github.com/mad1izjod/business-simulator/tree/main/src/engine/systems"
click node_ledger "https://github.com/mad1izjod/business-simulator/blob/main/src/engine/systems/ledger.ts"
click node_finance "https://github.com/mad1izjod/business-simulator/tree/main/src/engine/systems"
click node_world "https://github.com/mad1izjod/business-simulator/tree/main/src/engine/systems"
click node_definitions "https://github.com/mad1izjod/business-simulator/blob/main/src/engine/data/industries.ts"
click node_reports "https://github.com/mad1izjod/business-simulator/blob/main/src/engine/systems/insights.ts"
click node_explain "https://github.com/mad1izjod/business-simulator/blob/main/src/engine/explain.ts"
click node_projection "https://github.com/mad1izjod/business-simulator/blob/main/src/engine/projection.ts"
click node_worker "https://github.com/mad1izjod/business-simulator/blob/main/src/ui/game/projection.worker.ts"
click node_storage "https://github.com/mad1izjod/business-simulator/blob/main/src/persistence/storage.ts"
click node_serialization "https://github.com/mad1izjod/business-simulator/blob/main/src/persistence/serialize.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_onboarding,node_app,node_pages toneBlue
class node_controller,node_engine,node_commands,node_company toneAmber
class node_market,node_products,node_operations,node_people,node_growth,node_definitions toneMint
class node_ledger,node_finance,node_world toneRose
class node_reports,node_explain,node_projection,node_worker,node_storage,node_serialization,node_player toneIndigo
```

## Components

### Player interface

- [Company setup](https://github.com/mad1izjod/business-simulator/blob/main/src/ui/onboarding/CreateCompany.tsx): `src/ui/onboarding/CreateCompany.tsx`
- [App shell](https://github.com/mad1izjod/business-simulator/blob/main/src/ui/App.tsx): `src/ui/App.tsx`
- [Simulation pages](https://github.com/mad1izjod/business-simulator/tree/main/src/ui/pages): `src/ui/pages`

### Simulation runtime

- [Game controller](https://github.com/mad1izjod/business-simulator/blob/main/src/ui/game/controller.ts): `src/ui/game/controller.ts`
- [Daily and monthly loop](https://github.com/mad1izjod/business-simulator/blob/main/src/engine/step.ts): `src/engine/step.ts`
- [Validated commands](https://github.com/mad1izjod/business-simulator/blob/main/src/engine/commands.ts): `src/engine/commands.ts`
- [Company initialization](https://github.com/mad1izjod/business-simulator/blob/main/src/engine/create.ts): `src/engine/create.ts`

### Business operations

- [Demand and sales](https://github.com/mad1izjod/business-simulator/blob/main/src/engine/systems/market.ts): `src/engine/systems/market.ts`
- [Products and R&D](https://github.com/mad1izjod/business-simulator/blob/main/src/engine/systems/products.ts): `src/engine/systems/products.ts`
- [Supply and production](https://github.com/mad1izjod/business-simulator/tree/main/src/engine/systems): `src/engine/systems`
- [Employees and hiring](https://github.com/mad1izjod/business-simulator/tree/main/src/engine/systems): `src/engine/systems`
- [Growth and corporate actions](https://github.com/mad1izjod/business-simulator/tree/main/src/engine/systems): `src/engine/systems`
- [Industry and market data](https://github.com/mad1izjod/business-simulator/blob/main/src/engine/data/industries.ts): `src/engine/data/industries.ts`

### Finance and world

- [Accounting ledger](https://github.com/mad1izjod/business-simulator/blob/main/src/engine/systems/ledger.ts): `src/engine/systems/ledger.ts`
- [Debt and capital](https://github.com/mad1izjod/business-simulator/tree/main/src/engine/systems): `src/engine/systems`
- [Markets and events](https://github.com/mad1izjod/business-simulator/tree/main/src/engine/systems): `src/engine/systems`

### Analysis and persistence

- [Reports and insights](https://github.com/mad1izjod/business-simulator/blob/main/src/engine/systems/insights.ts): `src/engine/systems/insights.ts`
- [Metric explanations](https://github.com/mad1izjod/business-simulator/blob/main/src/engine/explain.ts): `src/engine/explain.ts`
- [Forecasts and scenarios](https://github.com/mad1izjod/business-simulator/blob/main/src/engine/projection.ts): `src/engine/projection.ts`
- [Forecast worker](https://github.com/mad1izjod/business-simulator/blob/main/src/ui/game/projection.worker.ts): `src/ui/game/projection.worker.ts`
- [Browser saves](https://github.com/mad1izjod/business-simulator/blob/main/src/persistence/storage.ts): `src/persistence/storage.ts`
- [Save serialization](https://github.com/mad1izjod/business-simulator/blob/main/src/persistence/serialize.ts): `src/persistence/serialize.ts`

### Other components

- **Player**

## Connections

- Player → Company setup: sets up (evidence: `README.md`)
- Company setup → Company initialization: creates company (evidence: `src/ui/onboarding/CreateCompany.tsx`)
- App shell → Company setup: shows before game (evidence: `src/ui/App.tsx`)
- App shell → Game controller: subscribes to (evidence: `src/ui/App.tsx`)
- App shell → Simulation pages: selects page (evidence: `src/ui/App.tsx`)
- Player → Simulation pages: reviews and decides (evidence: `README.md`)
- Simulation pages → Game controller: dispatches actions (evidence: `src/ui/pages/Research.tsx`)
- Game controller → Validated commands: dispatches (evidence: `src/ui/game/controller.ts`)
- Game controller → Daily and monthly loop: advances time (evidence: `src/ui/game/controller.ts`)
- Game controller → Company initialization: starts game (evidence: `src/ui/game/controller.ts`)
- Company initialization → Industry and market data: uses configuration (evidence: `src/engine/create.ts`)
- Company initialization → Accounting ledger: initializes accounts (evidence: `src/engine/create.ts`)
- Daily and monthly loop → Demand and sales: runs simulation
- Daily and monthly loop → Products and R&D: runs simulation
- Daily and monthly loop → Supply and production: runs simulation
- Daily and monthly loop → Employees and hiring: runs simulation
- Daily and monthly loop → Debt and capital: runs simulation
- Daily and monthly loop → Markets and events: runs simulation
- Demand and sales → Products and R&D: reads product data (evidence: `src/engine/systems/market.ts`)
- Demand and sales → Accounting ledger: posts activity (evidence: `src/engine/systems/market.ts`)
- Products and R&D → Accounting ledger: posts expenses (evidence: `src/engine/systems/products.ts`)
- Products and R&D → Industry and market data: reads industry data (evidence: `src/engine/systems/products.ts`)
- Supply and production → Accounting ledger: records transactions (evidence: `src/engine/systems/market.ts`)
- Employees and hiring → Accounting ledger: records transactions (evidence: `src/engine/systems/market.ts`)
- Debt and capital → Accounting ledger: records transactions (evidence: `src/engine/systems/market.ts`)
- Growth and corporate actions → Accounting ledger: records transactions (evidence: `src/engine/systems/market.ts`)
- Daily and monthly loop → Reports and insights: closes reporting
- Game controller → Forecasts and scenarios: requests forecasts (evidence: `src/ui/game/controller.ts`)
- Forecasts and scenarios → Daily and monthly loop: simulates copy (evidence: `src/engine/projection.ts`)
- Game controller → Forecast worker: creates worker (evidence: `src/ui/game/controller.ts`)
- Forecast worker → Forecasts and scenarios: runs forecast (evidence: `src/ui/game/projection.worker.ts`)
- App shell → Metric explanations: opens explanations (evidence: `src/ui/App.tsx`)
- Game controller → Browser saves: saves game (evidence: `src/ui/game/controller.ts`)
- Browser saves → Save serialization: serializes saves (evidence: `src/persistence/storage.ts`)
- Save serialization → Company initialization: recreates save (evidence: `src/persistence/serialize.ts`)
