# khalidabdi1/factory architecture

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

- Interactive diagram: https://gitdiagram.com/khalidabdi1/factory
- Repository: https://github.com/khalidabdi1/factory

## Overview

Factory Yard is a browser-based, live isometric town simulation. The user opens the map, watches goods and people move through the town and its surrounding regions, and can select objects to inspect live details or reveal vehicle routes. The runtime builds the scene, runs simulation systems, and presents them through a WebGL view inside a small React plate. The README documents additional domain systems whose source was not sampled; those are represented at their exact directories, while arrows reflect only shown imports or documented behavior.

Main entry points: [`yard/sim/core.ts`](https://github.com/khalidabdi1/factory/blob/main/yard/sim/core.ts) (Simulation core), [`yard/index.ts`](https://github.com/khalidabdi1/factory/blob/main/yard/index.ts) (Runtime bootstrap), [`yard/view.ts`](https://github.com/khalidabdi1/factory/blob/main/yard/view.ts) (Interactive view), [`yard/sim/cars.ts`](https://github.com/khalidabdi1/factory/blob/main/yard/sim/cars.ts) (Road traffic)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_presentation["Presentation"]
  node_page["App page<br/>[page.tsx]"]
  node_plate["Map plate<br/>[YardFigure.tsx]"]
  node_bootstrap["Runtime bootstrap<br/>[index.ts]"]
  node_view["Interactive view<br/>[view.ts]"]
end

subgraph group_simulation["Simulation"]
  node_simcore["Simulation core<br/>[core.ts]"]
  node_roadtraffic["Road traffic<br/>[cars.ts]"]
  node_roadrules["Road rules<br/>[roads.ts]"]
  node_pedestrians["People and walking<br/>[people.ts]"]
  node_person["Person movement<br/>[person.ts]"]
  node_logistics["Town logistics"]
  node_sahel["Sahel systems"]
  node_east["East and Millbrook"]
  node_special["Special operations"]
end

subgraph group_world["World and models"]
  node_layout["Town layout<br/>[layout.ts]"]
  node_land["Terrain<br/>[land.ts]"]
  node_townworld["Town environment<br/>[town.ts]"]
  node_ground["Ground and roads<br/>[ground.ts]"]
  node_regionalworld["Regional environments"]
  node_models["Vehicles and people models"]
  node_worksmodels["Factory models<br/>[works.ts]"]
end

subgraph group_kernel["Rendering kernel"]
  node_scene["Shared scene state<br/>[shared.ts]"]
  node_projection["Isometric projection<br/>[iso.ts]"]
  node_geometry["Part geometry<br/>[part.ts]"]
  node_paths["Paths and routes<br/>[path.ts]"]
  node_math["Math and randomness<br/>[math.ts]"]
  node_theme["Visual theme<br/>[theme.ts]"]
end

node_visitor(("Visitor"))

node_visitor -->|"opens"| node_page
node_page -->|"renders"| node_plate
node_plate -->|"loads engine"| node_bootstrap
node_bootstrap -->|"starts view"| node_view
node_bootstrap -->|"configures"| node_scene
node_bootstrap -->|"uses"| node_layout
node_bootstrap -->|"builds scene"| node_townworld
node_bootstrap -->|"builds regions"| node_regionalworld
node_bootstrap -->|"starts simulation"| node_simcore
node_bootstrap -->|"loads models"| node_models
node_bootstrap -->|"loads theme"| node_theme
node_view -->|"reads shared state"| node_scene
node_view -->|"reads simulation"| node_simcore
node_view -->|"reads vehicle state"| node_roadtraffic
node_view -->|"reads people state"| node_pedestrians
node_view -->|"reads entities"| node_person
node_view -->|"uses theme"| node_theme
node_simcore -->|"adds entities"| node_scene
node_simcore -->|"uses movement"| node_person
node_roadtraffic -->|"uses simulation state"| node_simcore
node_roadtraffic -->|"checks traffic"| node_roadrules
node_roadtraffic -->|"creates customers"| node_pedestrians
node_person -->|"uses entity state"| node_simcore
node_person -->|"checks crossings"| node_roadrules
node_pedestrians -->|"coordinates traffic"| node_roadtraffic
node_pedestrians -->|"uses walkers"| node_person
node_townworld -->|"uses terrain features"| node_ground
node_townworld -->|"uses vehicle models"| node_models
node_ground -->|"uses coordinates"| node_layout
node_layout -->|"reads elevation"| node_land
node_layout -->|"uses shared scene"| node_scene
node_land -->|"uses path geometry"| node_paths
node_geometry -->|"projects geometry"| node_projection
node_geometry -->|"uses materials"| node_theme
node_simcore -->|"uses routes"| node_paths
node_roadtraffic -->|"follows paths"| node_paths
node_roadtraffic -->|"reads terrain heights"| node_land
node_models -.->|"builds parts"| node_geometry
node_worksmodels -->|"builds factory parts"| node_geometry
node_logistics -.->|"uses shared simulation"| node_simcore
node_sahel -.->|"uses shared simulation"| node_simcore
node_east -.->|"uses shared simulation"| node_simcore
node_special -.->|"uses shared simulation"| node_simcore
node_visitor -->|"selects and inspects"| node_view

click node_page "https://github.com/khalidabdi1/factory/blob/main/app/page.tsx"
click node_plate "https://github.com/khalidabdi1/factory/blob/main/components/YardFigure.tsx"
click node_bootstrap "https://github.com/khalidabdi1/factory/blob/main/yard/index.ts"
click node_view "https://github.com/khalidabdi1/factory/blob/main/yard/view.ts"
click node_scene "https://github.com/khalidabdi1/factory/blob/main/yard/shared.ts"
click node_simcore "https://github.com/khalidabdi1/factory/blob/main/yard/sim/core.ts"
click node_roadtraffic "https://github.com/khalidabdi1/factory/blob/main/yard/sim/cars.ts"
click node_roadrules "https://github.com/khalidabdi1/factory/blob/main/yard/sim/roads.ts"
click node_pedestrians "https://github.com/khalidabdi1/factory/blob/main/yard/sim/people.ts"
click node_person "https://github.com/khalidabdi1/factory/blob/main/yard/sim/person.ts"
click node_logistics "https://github.com/khalidabdi1/factory/tree/main/yard/sim"
click node_sahel "https://github.com/khalidabdi1/factory/tree/main/yard/sim"
click node_east "https://github.com/khalidabdi1/factory/tree/main/yard/sim"
click node_special "https://github.com/khalidabdi1/factory/tree/main/yard/sim"
click node_layout "https://github.com/khalidabdi1/factory/blob/main/yard/layout.ts"
click node_land "https://github.com/khalidabdi1/factory/blob/main/yard/land.ts"
click node_townworld "https://github.com/khalidabdi1/factory/blob/main/yard/world/town.ts"
click node_ground "https://github.com/khalidabdi1/factory/blob/main/yard/world/ground.ts"
click node_regionalworld "https://github.com/khalidabdi1/factory/tree/main/yard/world"
click node_models "https://github.com/khalidabdi1/factory/tree/main/yard/models"
click node_worksmodels "https://github.com/khalidabdi1/factory/blob/main/yard/models/works.ts"
click node_projection "https://github.com/khalidabdi1/factory/blob/main/yard/kernel/iso.ts"
click node_geometry "https://github.com/khalidabdi1/factory/blob/main/yard/kernel/part.ts"
click node_paths "https://github.com/khalidabdi1/factory/blob/main/yard/kernel/path.ts"
click node_math "https://github.com/khalidabdi1/factory/blob/main/yard/kernel/math.ts"
click node_theme "https://github.com/khalidabdi1/factory/blob/main/yard/theme.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_page,node_plate,node_bootstrap,node_view toneBlue
class node_simcore,node_roadtraffic,node_roadrules,node_pedestrians,node_person,node_logistics,node_sahel,node_east,node_special toneAmber
class node_layout,node_land,node_townworld,node_ground,node_regionalworld,node_models,node_worksmodels toneMint
class node_scene,node_projection,node_geometry,node_paths,node_math,node_theme toneRose
class node_visitor toneIndigo
```

## Components

### Presentation

- [App page](https://github.com/khalidabdi1/factory/blob/main/app/page.tsx): `app/page.tsx`
- [Map plate](https://github.com/khalidabdi1/factory/blob/main/components/YardFigure.tsx): `components/YardFigure.tsx`
- [Runtime bootstrap](https://github.com/khalidabdi1/factory/blob/main/yard/index.ts): `yard/index.ts`
- [Interactive view](https://github.com/khalidabdi1/factory/blob/main/yard/view.ts): `yard/view.ts`

### Simulation

- [Simulation core](https://github.com/khalidabdi1/factory/blob/main/yard/sim/core.ts): `yard/sim/core.ts`
- [Road traffic](https://github.com/khalidabdi1/factory/blob/main/yard/sim/cars.ts): `yard/sim/cars.ts`
- [Road rules](https://github.com/khalidabdi1/factory/blob/main/yard/sim/roads.ts): `yard/sim/roads.ts`
- [People and walking](https://github.com/khalidabdi1/factory/blob/main/yard/sim/people.ts): `yard/sim/people.ts`
- [Person movement](https://github.com/khalidabdi1/factory/blob/main/yard/sim/person.ts): `yard/sim/person.ts`
- [Town logistics](https://github.com/khalidabdi1/factory/tree/main/yard/sim): `yard/sim`
- [Sahel systems](https://github.com/khalidabdi1/factory/tree/main/yard/sim): `yard/sim`
- [East and Millbrook](https://github.com/khalidabdi1/factory/tree/main/yard/sim): `yard/sim`
- [Special operations](https://github.com/khalidabdi1/factory/tree/main/yard/sim): `yard/sim`

### World and models

- [Town layout](https://github.com/khalidabdi1/factory/blob/main/yard/layout.ts): `yard/layout.ts`
- [Terrain](https://github.com/khalidabdi1/factory/blob/main/yard/land.ts): `yard/land.ts`
- [Town environment](https://github.com/khalidabdi1/factory/blob/main/yard/world/town.ts): `yard/world/town.ts`
- [Ground and roads](https://github.com/khalidabdi1/factory/blob/main/yard/world/ground.ts): `yard/world/ground.ts`
- [Regional environments](https://github.com/khalidabdi1/factory/tree/main/yard/world): `yard/world`
- [Vehicles and people models](https://github.com/khalidabdi1/factory/tree/main/yard/models): `yard/models`
- [Factory models](https://github.com/khalidabdi1/factory/blob/main/yard/models/works.ts): `yard/models/works.ts`

### Rendering kernel

- [Shared scene state](https://github.com/khalidabdi1/factory/blob/main/yard/shared.ts): `yard/shared.ts`
- [Isometric projection](https://github.com/khalidabdi1/factory/blob/main/yard/kernel/iso.ts): `yard/kernel/iso.ts`
- [Part geometry](https://github.com/khalidabdi1/factory/blob/main/yard/kernel/part.ts): `yard/kernel/part.ts`
- [Paths and routes](https://github.com/khalidabdi1/factory/blob/main/yard/kernel/path.ts): `yard/kernel/path.ts`
- [Math and randomness](https://github.com/khalidabdi1/factory/blob/main/yard/kernel/math.ts): `yard/kernel/math.ts`
- [Visual theme](https://github.com/khalidabdi1/factory/blob/main/yard/theme.ts): `yard/theme.ts`

### Other components

- **Visitor**

## Connections

- Visitor → App page: opens
- App page → Map plate: renders (evidence: `app/page.tsx`)
- Map plate → Runtime bootstrap: loads engine (evidence: `components/YardFigure.tsx`)
- Runtime bootstrap → Interactive view: starts view (evidence: `yard/index.ts`)
- Runtime bootstrap → Shared scene state: configures (evidence: `yard/index.ts`)
- Runtime bootstrap → Town layout: uses (evidence: `yard/index.ts`)
- Runtime bootstrap → Town environment: builds scene (evidence: `yard/index.ts`)
- Runtime bootstrap → Regional environments: builds regions (evidence: `yard/index.ts`)
- Runtime bootstrap → Simulation core: starts simulation (evidence: `yard/index.ts`)
- Runtime bootstrap → Vehicles and people models: loads models (evidence: `yard/index.ts`)
- Runtime bootstrap → Visual theme: loads theme (evidence: `yard/index.ts`)
- Interactive view → Shared scene state: reads shared state (evidence: `yard/view.ts`)
- Interactive view → Simulation core: reads simulation (evidence: `yard/view.ts`)
- Interactive view → Road traffic: reads vehicle state (evidence: `yard/view.ts`)
- Interactive view → People and walking: reads people state (evidence: `yard/view.ts`)
- Interactive view → Person movement: reads entities (evidence: `yard/view.ts`)
- Interactive view → Visual theme: uses theme (evidence: `yard/view.ts`)
- Simulation core → Shared scene state: adds entities (evidence: `yard/sim/core.ts`)
- Simulation core → Person movement: uses movement (evidence: `yard/sim/core.ts`)
- Road traffic → Simulation core: uses simulation state (evidence: `yard/sim/cars.ts`)
- Road traffic → Road rules: checks traffic (evidence: `yard/sim/cars.ts`)
- Road traffic → People and walking: creates customers (evidence: `yard/sim/cars.ts`)
- Person movement → Simulation core: uses entity state (evidence: `yard/sim/person.ts`)
- Person movement → Road rules: checks crossings (evidence: `yard/sim/person.ts`)
- People and walking → Road traffic: coordinates traffic (evidence: `yard/sim/people.ts`)
- People and walking → Person movement: uses walkers (evidence: `yard/sim/people.ts`)
- Town environment → Ground and roads: uses terrain features (evidence: `yard/world/town.ts`)
- Town environment → Vehicles and people models: uses vehicle models (evidence: `yard/world/town.ts`)
- Ground and roads → Town layout: uses coordinates (evidence: `yard/world/ground.ts`)
- Town layout → Terrain: reads elevation (evidence: `yard/layout.ts`)
- Town layout → Shared scene state: uses shared scene (evidence: `yard/layout.ts`)
- Terrain → Paths and routes: uses path geometry (evidence: `yard/land.ts`)
- Part geometry → Isometric projection: projects geometry (evidence: `yard/kernel/part.ts`)
- Part geometry → Visual theme: uses materials (evidence: `yard/kernel/part.ts`)
- Simulation core → Paths and routes: uses routes (evidence: `yard/sim/core.ts`)
- Road traffic → Paths and routes: follows paths (evidence: `yard/sim/cars.ts`)
- Road traffic → Terrain: reads terrain heights (evidence: `yard/sim/cars.ts`)
- Vehicles and people models → Part geometry: builds parts (evidence: `yard/models/starship.ts`)
- Factory models → Part geometry: builds factory parts (evidence: `yard/models/works.ts`)
- Town logistics → Simulation core: uses shared simulation (evidence: `yard/sim/police.ts`)
- Sahel systems → Simulation core: uses shared simulation (evidence: `yard/sim/police.ts`)
- East and Millbrook → Simulation core: uses shared simulation (evidence: `yard/sim/police.ts`)
- Special operations → Simulation core: uses shared simulation (evidence: `yard/sim/police.ts`)
- Visitor → Interactive view: selects and inspects