# fellipegoncalvesleite/society-engine architecture

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

- Interactive diagram: https://gitdiagram.com/fellipegoncalvesleite/society-engine
- Repository: https://github.com/fellipegoncalvesleite/society-engine

## Overview

Society Engine is a deterministic simulation of mobile early human societies; the React interface is an inspection and control surface. A user configures or loads a world, the runner advances it in steps, and each day moves from world ecology through band perception and knowledge to decisions, physical action, demography, and recorded history. The graph preserves the README’s principal domain stages and major capabilities, including expeditions, fission, and seasonal ecology. Some connections are documented in the README or import index; unsampled implementation details are not inferred.

Main entry points: [`src/sim/tick/advance.ts`](https://github.com/fellipegoncalvesleite/society-engine/blob/main/src/sim/tick/advance.ts) (Daily advance), [`src/sim/rules/bandDecision.ts`](https://github.com/fellipegoncalvesleite/society-engine/blob/main/src/sim/rules/bandDecision.ts) (Daily decisions), [`src/sim/runner/simRunner.ts`](https://github.com/fellipegoncalvesleite/society-engine/blob/main/src/sim/runner/simRunner.ts) (Simulation runner), [`src/ui/App.tsx`](https://github.com/fellipegoncalvesleite/society-engine/blob/main/src/ui/App.tsx) (Simulation controls)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_world["World and ecology"]
  node_worldgen["World generation<br/>[generate.ts]"]
  node_hydrology["Hydrology<br/>[hydrography.ts]"]
  node_ecology["Seasonal ecology"]
end

subgraph group_behavior["Band behavior"]
  node_perception["Perception<br/>[tileObservation.ts]"]
  node_knowledge["Band knowledge"]
  node_decisions["Daily decisions<br/>[bandDecision.ts]"]
  node_mobility["Movement and mobility<br/>[bandMobility.ts]"]
  node_expeditions["Foraging expeditions<br/>[expedition.ts]"]
  node_fission["Band fission<br/>[bandLifecycle.ts]"]
  node_demography["Demography<br/>[demography.ts]"]
  node_history["Events and history<br/>[bandHistory.ts]"]
end

subgraph group_runtime["Simulation runtime"]
  node_worker["Worker bridge<br/>[simWorker.ts]"]
  node_runner["Simulation runner<br/>[simRunner.ts]"]
  node_advance["Daily advance<br/>[advance.ts]"]
  node_snapshot["Simulation snapshot<br/>[simRunner.ts]"]
end

subgraph group_inspection["Inspection interface"]
  node_interface["Simulation controls<br/>[App.tsx]"]
  node_state["UI state<br/>[store.ts]"]
  node_display["Map renderer<br/>[canvasRenderer.ts]"]
end

node_user(("User"))

node_user -->|"configures"| node_interface
node_interface -.->|"starts run"| node_worker
node_interface -->|"updates view"| node_state
node_worker -->|"runs"| node_runner
node_runner -->|"builds world"| node_worldgen
node_worldgen -->|"uses hydrology"| node_hydrology
node_runner -->|"advances steps"| node_advance
node_advance -.->|"advances ecology"| node_ecology
node_advance -.->|"updates perception"| node_perception
node_perception -.->|"updates knowledge"| node_knowledge
node_knowledge -->|"informs decisions"| node_decisions
node_decisions -.->|"chooses actions"| node_mobility
node_decisions -.->|"chooses actions"| node_expeditions
node_advance -->|"applies demography"| node_demography
node_advance -->|"records history"| node_history
node_advance -.->|"produces snapshot"| node_snapshot
node_snapshot -.->|"refreshes state"| node_state
node_state -->|"supplies view"| node_display
node_display -->|"shows world"| node_user
node_expeditions -.->|"uses resources"| node_ecology
node_demography -->|"includes fission"| node_fission

click node_interface "https://github.com/fellipegoncalvesleite/society-engine/blob/main/src/ui/App.tsx"
click node_state "https://github.com/fellipegoncalvesleite/society-engine/blob/main/src/store.ts"
click node_display "https://github.com/fellipegoncalvesleite/society-engine/blob/main/src/render/canvasRenderer.ts"
click node_worker "https://github.com/fellipegoncalvesleite/society-engine/blob/main/src/worker/simWorker.ts"
click node_runner "https://github.com/fellipegoncalvesleite/society-engine/blob/main/src/sim/runner/simRunner.ts"
click node_worldgen "https://github.com/fellipegoncalvesleite/society-engine/blob/main/src/sim/world/generate.ts"
click node_hydrology "https://github.com/fellipegoncalvesleite/society-engine/blob/main/src/sim/world/hydrography.ts"
click node_perception "https://github.com/fellipegoncalvesleite/society-engine/blob/main/src/sim/agents/tileObservation.ts"
click node_knowledge "https://github.com/fellipegoncalvesleite/society-engine/blob/main/src/sim/agents/resourceKnowledge.ts"
click node_decisions "https://github.com/fellipegoncalvesleite/society-engine/blob/main/src/sim/rules/bandDecision.ts"
click node_mobility "https://github.com/fellipegoncalvesleite/society-engine/blob/main/src/sim/agents/bandMobility.ts"
click node_expeditions "https://github.com/fellipegoncalvesleite/society-engine/blob/main/src/sim/agents/expedition.ts"
click node_fission "https://github.com/fellipegoncalvesleite/society-engine/blob/main/src/sim/agents/bandLifecycle.ts"
click node_demography "https://github.com/fellipegoncalvesleite/society-engine/blob/main/src/sim/agents/demography.ts"
click node_history "https://github.com/fellipegoncalvesleite/society-engine/blob/main/src/sim/agents/bandHistory.ts"
click node_advance "https://github.com/fellipegoncalvesleite/society-engine/blob/main/src/sim/tick/advance.ts"
click node_snapshot "https://github.com/fellipegoncalvesleite/society-engine/blob/main/src/sim/runner/simRunner.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_worldgen,node_hydrology,node_ecology,node_user toneBlue
class node_perception,node_knowledge,node_decisions,node_mobility,node_expeditions,node_fission,node_demography,node_history toneAmber
class node_worker,node_runner,node_advance,node_snapshot toneMint
class node_interface,node_state,node_display toneRose
```

## Components

### World and ecology

- [World generation](https://github.com/fellipegoncalvesleite/society-engine/blob/main/src/sim/world/generate.ts): `src/sim/world/generate.ts`
- [Hydrology](https://github.com/fellipegoncalvesleite/society-engine/blob/main/src/sim/world/hydrography.ts): `src/sim/world/hydrography.ts`
- **Seasonal ecology**

### Band behavior

- [Perception](https://github.com/fellipegoncalvesleite/society-engine/blob/main/src/sim/agents/tileObservation.ts): `src/sim/agents/tileObservation.ts`
- [Band knowledge](https://github.com/fellipegoncalvesleite/society-engine/blob/main/src/sim/agents/resourceKnowledge.ts): `src/sim/agents/resourceKnowledge.ts`
- [Daily decisions](https://github.com/fellipegoncalvesleite/society-engine/blob/main/src/sim/rules/bandDecision.ts): `src/sim/rules/bandDecision.ts`
- [Movement and mobility](https://github.com/fellipegoncalvesleite/society-engine/blob/main/src/sim/agents/bandMobility.ts): `src/sim/agents/bandMobility.ts`
- [Foraging expeditions](https://github.com/fellipegoncalvesleite/society-engine/blob/main/src/sim/agents/expedition.ts): `src/sim/agents/expedition.ts`
- [Band fission](https://github.com/fellipegoncalvesleite/society-engine/blob/main/src/sim/agents/bandLifecycle.ts): `src/sim/agents/bandLifecycle.ts`
- [Demography](https://github.com/fellipegoncalvesleite/society-engine/blob/main/src/sim/agents/demography.ts): `src/sim/agents/demography.ts`
- [Events and history](https://github.com/fellipegoncalvesleite/society-engine/blob/main/src/sim/agents/bandHistory.ts): `src/sim/agents/bandHistory.ts`

### Simulation runtime

- [Worker bridge](https://github.com/fellipegoncalvesleite/society-engine/blob/main/src/worker/simWorker.ts): `src/worker/simWorker.ts`
- [Simulation runner](https://github.com/fellipegoncalvesleite/society-engine/blob/main/src/sim/runner/simRunner.ts): `src/sim/runner/simRunner.ts`
- [Daily advance](https://github.com/fellipegoncalvesleite/society-engine/blob/main/src/sim/tick/advance.ts): `src/sim/tick/advance.ts`
- [Simulation snapshot](https://github.com/fellipegoncalvesleite/society-engine/blob/main/src/sim/runner/simRunner.ts): `src/sim/runner/simRunner.ts`

### Inspection interface

- [Simulation controls](https://github.com/fellipegoncalvesleite/society-engine/blob/main/src/ui/App.tsx): `src/ui/App.tsx`
- [UI state](https://github.com/fellipegoncalvesleite/society-engine/blob/main/src/store.ts): `src/store.ts`
- [Map renderer](https://github.com/fellipegoncalvesleite/society-engine/blob/main/src/render/canvasRenderer.ts): `src/render/canvasRenderer.ts`

### Other components

- **User**

## Connections

- User → Simulation controls: configures (evidence: `README.md`)
- Simulation controls → Worker bridge: starts run
- Simulation controls → UI state: updates view (evidence: `src/ui/App.tsx`)
- Worker bridge → Simulation runner: runs (evidence: `src/worker/simWorker.ts`)
- Simulation runner → World generation: builds world (evidence: `src/sim/runner/simRunner.ts`)
- World generation → Hydrology: uses hydrology (evidence: `src/sim/world/generate.ts`)
- Simulation runner → Daily advance: advances steps (evidence: `src/sim/runner/simRunner.ts`)
- Daily advance → Seasonal ecology: advances ecology
- Daily advance → Perception: updates perception
- Perception → Band knowledge: updates knowledge
- Band knowledge → Daily decisions: informs decisions (evidence: `README.md`)
- Daily decisions → Movement and mobility: chooses actions
- Daily decisions → Foraging expeditions: chooses actions
- Daily advance → Demography: applies demography (evidence: `src/sim/tick/advance.ts`)
- Daily advance → Events and history: records history (evidence: `src/sim/tick/advance.ts`)
- Daily advance → Simulation snapshot: produces snapshot (evidence: `src/sim/runner/simRunner.ts`)
- Simulation snapshot → UI state: refreshes state (evidence: `src/store.ts`)
- UI state → Map renderer: supplies view (evidence: `src/store.ts`)
- Map renderer → User: shows world (evidence: `README.md`)
- Foraging expeditions → Seasonal ecology: uses resources
- Demography → Band fission: includes fission (evidence: `README.md`)
