# spinjitsu12/scout architecture

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

- Interactive diagram: https://gitdiagram.com/spinjitsu12/scout
- Repository: https://github.com/spinjitsu12/scout

## Overview

SCOUT is an offline-first, first-person scout simulator. The player creates or selects a career, completes an opening story, explores and drives through a town, visits venues, meets people, and advances a career through scouting choices. The renderer coordinates gameplay and career state; the game domain models progression and field state, while world modules provide the 3D environment. Electron supplies native saves, display controls, and update checks. Some subsystem links rely on README descriptions or SOURCE INDEX references; unsampled implementation details are not inferred.

Main entry points: [`src/App.tsx`](https://github.com/spinjitsu12/scout/blob/main/src/App.tsx) (Game coordinator), [`src/lib/game.ts`](https://github.com/spinjitsu12/scout/blob/main/src/lib/game.ts) (Career rules), [`src/components/game/ImmersiveWorld.tsx`](https://github.com/spinjitsu12/scout/blob/main/src/components/game/ImmersiveWorld.tsx) (First-person world), [`src/lib/desktop.ts`](https://github.com/spinjitsu12/scout/blob/main/src/lib/desktop.ts) (Desktop bridge)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Game experience"]
  node_app["Game coordinator<br/>[App.tsx]"]
  node_career["Career setup<br/>[CareerSetup.tsx]"]
  node_prologue["Opening story<br/>[Prologue.tsx]"]
  node_road["Town exploration<br/>[RoadWorld.tsx]"]
  node_immersive["First-person world<br/>[ImmersiveWorld.tsx]"]
  node_panels["Gameplay panels<br/>[GameplayPanels.tsx]"]
  node_settings["Game settings"]
  node_updatesui["Update panel<br/>[UpdatePanel.tsx]"]
end

subgraph group_world["World simulation"]
  node_immworld["World layout<br/>[immersive-world.ts]"]
  node_assets["World assets"]
  node_driving["Driving model<br/>[driving.ts]"]
  node_drivecamera["Driving camera<br/>[driving-camera.ts]"]
end

subgraph group_domain["Career and sound"]
  node_game["Career rules<br/>[game.ts]"]
  node_expedition["Field state<br/>[expedition.ts]"]
  node_immruntime["Immersion state"]
  node_audio["Audio system<br/>[audio.ts]"]
end

subgraph group_desktop["Desktop services"]
  node_desktopbridge["Desktop bridge<br/>[desktop.ts]"]
  node_main["Electron main<br/>[main.cjs]"]
  node_saves["Save slots<br/>[save-store.cjs]"]
  node_savefiles[("Career files")]
  node_updatemgr["Update manager<br/>[update-manager.cjs]"]
end

node_player(("Player"))
node_release["Update service"]

node_player -->|"starts game"| node_app
node_app -->|"opens setup"| node_career
node_app -->|"shows story"| node_prologue
node_app -->|"opens town"| node_road
node_app -->|"opens world"| node_immersive
node_app -->|"shows panels"| node_panels
node_app -->|"opens settings"| node_settings
node_app -->|"shows updates"| node_updatesui
node_app -->|"validates career"| node_game
node_career -->|"uses desktop"| node_desktopbridge
node_prologue -.->|"advances story"| node_game
node_road -->|"uses driving model"| node_driving
node_road -->|"renders driving view"| node_drivecamera
node_immersive -->|"updates snapshots"| node_immruntime
node_immersive -->|"dispatches actions"| node_game
node_immersive -->|"gets locations"| node_immworld
node_immworld -->|"uses assets"| node_assets
node_game -->|"uses field rules"| node_expedition
node_game -->|"creates immersion"| node_immruntime
node_panels -->|"reads career state"| node_game
node_settings -->|"configures sound"| node_audio
node_settings -->|"configures display"| node_desktopbridge
node_immersive -->|"plays world audio"| node_audio
node_app -->|"lists and saves"| node_desktopbridge
node_desktopbridge -.->|"calls native bridge"| node_main
node_main -->|"handles career saves"| node_saves
node_saves -->|"reads and writes"| node_savefiles
node_main -->|"initializes updates"| node_updatemgr
node_updatemgr -.->|"checks and downloads"| node_release
node_updatesui -.->|"requests update status"| node_desktopbridge

click node_app "https://github.com/spinjitsu12/scout/blob/main/src/App.tsx"
click node_career "https://github.com/spinjitsu12/scout/blob/main/src/components/game/CareerSetup.tsx"
click node_prologue "https://github.com/spinjitsu12/scout/blob/main/src/components/game/Prologue.tsx"
click node_road "https://github.com/spinjitsu12/scout/blob/main/src/components/game/RoadWorld.tsx"
click node_immersive "https://github.com/spinjitsu12/scout/blob/main/src/components/game/ImmersiveWorld.tsx"
click node_panels "https://github.com/spinjitsu12/scout/blob/main/src/components/game/GameplayPanels.tsx"
click node_settings "https://github.com/spinjitsu12/scout/blob/main/src/components/game/ImmersiveSettings.tsx"
click node_updatesui "https://github.com/spinjitsu12/scout/blob/main/src/components/game/UpdatePanel.tsx"
click node_game "https://github.com/spinjitsu12/scout/blob/main/src/lib/game.ts"
click node_expedition "https://github.com/spinjitsu12/scout/blob/main/src/lib/expedition.ts"
click node_immruntime "https://github.com/spinjitsu12/scout/blob/main/src/lib/immersive-runtime.ts"
click node_immworld "https://github.com/spinjitsu12/scout/blob/main/src/lib/immersive-world.ts"
click node_assets "https://github.com/spinjitsu12/scout/blob/main/src/lib/immersive-assets.ts"
click node_driving "https://github.com/spinjitsu12/scout/blob/main/src/lib/driving.ts"
click node_drivecamera "https://github.com/spinjitsu12/scout/blob/main/src/components/game/driving-camera.ts"
click node_audio "https://github.com/spinjitsu12/scout/blob/main/src/lib/audio.ts"
click node_desktopbridge "https://github.com/spinjitsu12/scout/blob/main/src/lib/desktop.ts"
click node_main "https://github.com/spinjitsu12/scout/blob/main/electron/main.cjs"
click node_saves "https://github.com/spinjitsu12/scout/blob/main/electron/save-store.cjs"
click node_updatemgr "https://github.com/spinjitsu12/scout/blob/main/electron/update-manager.cjs"

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_career,node_prologue,node_road,node_immersive,node_panels,node_settings,node_updatesui toneBlue
class node_immworld,node_assets,node_driving,node_drivecamera toneAmber
class node_game,node_expedition,node_immruntime,node_audio toneMint
class node_desktopbridge,node_main,node_saves,node_savefiles,node_updatemgr toneRose
class node_player,node_release toneIndigo
```

## Components

### Game experience

- [Game coordinator](https://github.com/spinjitsu12/scout/blob/main/src/App.tsx): `src/App.tsx`
- [Career setup](https://github.com/spinjitsu12/scout/blob/main/src/components/game/CareerSetup.tsx): `src/components/game/CareerSetup.tsx`
- [Opening story](https://github.com/spinjitsu12/scout/blob/main/src/components/game/Prologue.tsx): `src/components/game/Prologue.tsx`
- [Town exploration](https://github.com/spinjitsu12/scout/blob/main/src/components/game/RoadWorld.tsx): `src/components/game/RoadWorld.tsx`
- [First-person world](https://github.com/spinjitsu12/scout/blob/main/src/components/game/ImmersiveWorld.tsx): `src/components/game/ImmersiveWorld.tsx`
- [Gameplay panels](https://github.com/spinjitsu12/scout/blob/main/src/components/game/GameplayPanels.tsx): `src/components/game/GameplayPanels.tsx`
- [Game settings](https://github.com/spinjitsu12/scout/blob/main/src/components/game/ImmersiveSettings.tsx): `src/components/game/ImmersiveSettings.tsx`
- [Update panel](https://github.com/spinjitsu12/scout/blob/main/src/components/game/UpdatePanel.tsx): `src/components/game/UpdatePanel.tsx`

### World simulation

- [World layout](https://github.com/spinjitsu12/scout/blob/main/src/lib/immersive-world.ts): `src/lib/immersive-world.ts`
- [World assets](https://github.com/spinjitsu12/scout/blob/main/src/lib/immersive-assets.ts): `src/lib/immersive-assets.ts`
- [Driving model](https://github.com/spinjitsu12/scout/blob/main/src/lib/driving.ts): `src/lib/driving.ts`
- [Driving camera](https://github.com/spinjitsu12/scout/blob/main/src/components/game/driving-camera.ts): `src/components/game/driving-camera.ts`

### Career and sound

- [Career rules](https://github.com/spinjitsu12/scout/blob/main/src/lib/game.ts): `src/lib/game.ts`
- [Field state](https://github.com/spinjitsu12/scout/blob/main/src/lib/expedition.ts): `src/lib/expedition.ts`
- [Immersion state](https://github.com/spinjitsu12/scout/blob/main/src/lib/immersive-runtime.ts): `src/lib/immersive-runtime.ts`
- [Audio system](https://github.com/spinjitsu12/scout/blob/main/src/lib/audio.ts): `src/lib/audio.ts`

### Desktop services

- [Desktop bridge](https://github.com/spinjitsu12/scout/blob/main/src/lib/desktop.ts): `src/lib/desktop.ts`
- [Electron main](https://github.com/spinjitsu12/scout/blob/main/electron/main.cjs): `electron/main.cjs`
- [Save slots](https://github.com/spinjitsu12/scout/blob/main/electron/save-store.cjs): `electron/save-store.cjs`
- **Career files**
- [Update manager](https://github.com/spinjitsu12/scout/blob/main/electron/update-manager.cjs): `electron/update-manager.cjs`

### Other components

- **Player**
- **Update service**

## Connections

- Player → Game coordinator: starts game (evidence: `README.md`)
- Game coordinator → Career setup: opens setup (evidence: `src/App.tsx`)
- Game coordinator → Opening story: shows story (evidence: `src/App.tsx`)
- Game coordinator → Town exploration: opens town (evidence: `src/App.tsx`)
- Game coordinator → First-person world: opens world (evidence: `src/App.tsx`)
- Game coordinator → Gameplay panels: shows panels (evidence: `src/App.tsx`)
- Game coordinator → Game settings: opens settings (evidence: `src/App.tsx`)
- Game coordinator → Update panel: shows updates (evidence: `src/App.tsx`)
- Game coordinator → Career rules: validates career (evidence: `src/App.tsx`)
- Career setup → Desktop bridge: uses desktop (evidence: `src/components/game/CareerSetup.tsx`)
- Opening story → Career rules: advances story
- Town exploration → Driving model: uses driving model (evidence: `src/components/game/RoadWorld.tsx`)
- Town exploration → Driving camera: renders driving view (evidence: `src/components/game/RoadWorld.tsx`)
- First-person world → Immersion state: updates snapshots (evidence: `src/components/game/ImmersiveWorld.tsx`)
- First-person world → Career rules: dispatches actions (evidence: `src/components/game/ImmersiveWorld.tsx`)
- First-person world → World layout: gets locations (evidence: `src/components/game/ImmersiveWorld.tsx`)
- World layout → World assets: uses assets (evidence: `src/lib/immersive-world.ts`)
- Career rules → Field state: uses field rules (evidence: `src/lib/game.ts`)
- Career rules → Immersion state: creates immersion (evidence: `src/lib/game.ts`)
- Gameplay panels → Career rules: reads career state (evidence: `src/components/game/GameplayPanels.tsx`)
- Game settings → Audio system: configures sound (evidence: `src/components/game/ImmersiveSettings.tsx`)
- Game settings → Desktop bridge: configures display (evidence: `src/components/game/ImmersiveSettings.tsx`)
- First-person world → Audio system: plays world audio (evidence: `src/components/game/ImmersiveWorld.tsx`)
- Game coordinator → Desktop bridge: lists and saves (evidence: `src/App.tsx`)
- Desktop bridge → Electron main: calls native bridge
- Electron main → Save slots: handles career saves (evidence: `electron/main.cjs`)
- Save slots → Career files: reads and writes (evidence: `electron/save-store.cjs`)
- Electron main → Update manager: initializes updates (evidence: `electron/main.cjs`)
- Update manager → Update service: checks and downloads
- Update panel → Desktop bridge: requests update status (evidence: `src/components/game/UpdatePanel.tsx`)
