# eng-cc/oasis7 architecture

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

- Interactive diagram: https://gitdiagram.com/eng-cc/oasis7
- Repository: https://github.com/eng-cc/oasis7

## Overview

oasis7 is a persistent, LLM-driven multi-agent civilization simulation with programmable WASM capabilities and decentralized world-state consensus. The principal documented path is indirect player guidance through autonomous agents, whose actions are governed by the world runtime, extended by WASM, and maintained through consensus, storage, and networking. The viewer provides observation and indirect control rather than node duties. Core simulator, node, networking, storage, and viewer components are represented; several links rely on README architecture statements or SOURCE INDEX references, since the corresponding source excerpts were not provided.

Main entry points: [`crates/oasis7/src/runtime/state.rs`](https://github.com/eng-cc/oasis7/blob/main/crates/oasis7/src/runtime/state.rs) (World Runtime), [`crates/oasis7_node/src/node_engine_core.rs`](https://github.com/eng-cc/oasis7/blob/main/crates/oasis7_node/src/node_engine_core.rs) (Node Engine), [`crates/oasis7_node/src/node_engine_replication.rs`](https://github.com/eng-cc/oasis7/blob/main/crates/oasis7_node/src/node_engine_replication.rs) (Replication), [`crates/oasis7/src/simulator/async_agent_runner.rs`](https://github.com/eng-cc/oasis7/blob/main/crates/oasis7/src/simulator/async_agent_runner.rs) (Async Agent Runner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_player["Player Access"]
  node_client_launcher["Client Launcher<br/>[main.rs]"]
  node_viewer_ui["Viewer UI<br/>[main.jsx]"]
  node_viewer_server["Viewer Server<br/>[server.rs]"]
end

subgraph group_simulation["Agent Simulation"]
  node_agent["Agent<br/>[agent.rs]"]
  node_decision_provider["Decision Provider"]
  node_cognition_policy["Cognition Policy"]
  node_async_runner["Async Agent Runner"]
  node_turn_engine["Turn Engine<br/>[turn_engine.rs]"]
end

subgraph group_world["World Rules"]
  node_wasm_modules["WASM Modules<br/>[module_store.rs]"]
  node_world_runtime["World Runtime<br/>[state.rs]"]
  node_gameplay_rules["Gameplay Rules<br/>[gameplay.rs]"]
  node_governance["Governance<br/>[governance.rs]"]
end

subgraph group_execution["Execution and Consensus"]
  node_node_engine["Node Engine"]
  node_replication["Replication"]
  node_consensus["Consensus<br/>[lib.rs]"]
end

subgraph group_infrastructure["Persistence and Access"]
  node_execution_storage[("Execution Storage")]
  node_distfs[("Distributed Storage<br/>[lib.rs]")]
  node_network["Peer Networking<br/>[peer_manager.rs]"]
  node_status["Runtime Status<br/>[status_payload.rs]"]
  node_reward_worker["Reward Worker"]
  node_storage_metrics["Storage Metrics<br/>[storage_metrics.rs]"]
end

node_player_actor(("Player"))

node_player_actor -->|"guides indirectly"| node_client_launcher
node_player_actor -->|"observes and guides"| node_viewer_ui
node_viewer_ui -.->|"sends requests"| node_viewer_server
node_viewer_server -->|"serves snapshots"| node_world_runtime
node_agent -->|"requests decisions"| node_decision_provider
node_async_runner -->|"runs"| node_agent
node_async_runner -->|"applies policy"| node_cognition_policy
node_turn_engine -->|"delegates turns"| node_async_runner
node_turn_engine -->|"requires runtime proof"| node_world_runtime
node_player_actor -->|"guides development"| node_wasm_modules
node_wasm_modules -->|"extends rules"| node_world_runtime
node_world_runtime -.->|"validates actions"| node_gameplay_rules
node_world_runtime -.->|"applies governance"| node_governance
node_world_runtime -->|"supplies world execution"| node_node_engine
node_node_engine -->|"proposes state"| node_consensus
node_node_engine -->|"dispatches replication"| node_replication
node_replication -.->|"fetches and persists"| node_execution_storage
node_execution_storage -.->|"writes execution data"| node_distfs
node_consensus -->|"coordinates peers"| node_network
node_replication -.->|"syncs peers"| node_network
node_status -->|"reports worker status"| node_reward_worker
node_status -->|"reports storage usage"| node_storage_metrics

click node_client_launcher "https://github.com/eng-cc/oasis7/blob/main/crates/oasis7_client_launcher/src/main.rs"
click node_viewer_ui "https://github.com/eng-cc/oasis7/blob/main/crates/oasis7_viewer/software_safe_src/main.jsx"
click node_viewer_server "https://github.com/eng-cc/oasis7/blob/main/crates/oasis7/src/viewer/server.rs"
click node_agent "https://github.com/eng-cc/oasis7/blob/main/crates/oasis7/src/simulator/agent.rs"
click node_decision_provider "https://github.com/eng-cc/oasis7/blob/main/crates/oasis7/src/simulator/decision_provider.rs"
click node_cognition_policy "https://github.com/eng-cc/oasis7/blob/main/crates/oasis7/src/simulator/cognition_policy.rs"
click node_async_runner "https://github.com/eng-cc/oasis7/blob/main/crates/oasis7/src/simulator/async_agent_runner.rs"
click node_turn_engine "https://github.com/eng-cc/oasis7/blob/main/crates/oasis7/src/simulator/turn_engine.rs"
click node_wasm_modules "https://github.com/eng-cc/oasis7/blob/main/crates/oasis7/src/runtime/module_store.rs"
click node_world_runtime "https://github.com/eng-cc/oasis7/blob/main/crates/oasis7/src/runtime/state.rs"
click node_gameplay_rules "https://github.com/eng-cc/oasis7/blob/main/crates/oasis7/src/runtime/gameplay.rs"
click node_governance "https://github.com/eng-cc/oasis7/blob/main/crates/oasis7/src/runtime/governance.rs"
click node_node_engine "https://github.com/eng-cc/oasis7/blob/main/crates/oasis7_node/src/node_engine_core.rs"
click node_replication "https://github.com/eng-cc/oasis7/blob/main/crates/oasis7_node/src/node_engine_replication.rs"
click node_consensus "https://github.com/eng-cc/oasis7/blob/main/crates/oasis7_consensus/src/lib.rs"
click node_execution_storage "https://github.com/eng-cc/oasis7/blob/main/crates/oasis7_net/src/execution_storage.rs"
click node_distfs "https://github.com/eng-cc/oasis7/blob/main/crates/oasis7_distfs/src/lib.rs"
click node_network "https://github.com/eng-cc/oasis7/blob/main/crates/oasis7_net/src/libp2p_net/peer_manager.rs"
click node_status "https://github.com/eng-cc/oasis7/blob/main/crates/oasis7/src/bin/oasis7_chain_runtime/status_payload.rs"
click node_reward_worker "https://github.com/eng-cc/oasis7/blob/main/crates/oasis7/src/bin/oasis7_chain_runtime/reward_runtime_worker.rs"
click node_storage_metrics "https://github.com/eng-cc/oasis7/blob/main/crates/oasis7/src/bin/oasis7_chain_runtime/storage_metrics.rs"

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_client_launcher,node_viewer_ui,node_viewer_server toneBlue
class node_agent,node_decision_provider,node_cognition_policy,node_async_runner,node_turn_engine toneAmber
class node_wasm_modules,node_world_runtime,node_gameplay_rules,node_governance toneMint
class node_node_engine,node_replication,node_consensus toneRose
class node_execution_storage,node_distfs,node_network,node_status,node_reward_worker,node_storage_metrics,node_player_actor toneIndigo
```

## Components

### Player Access

- [Client Launcher](https://github.com/eng-cc/oasis7/blob/main/crates/oasis7_client_launcher/src/main.rs): `crates/oasis7_client_launcher/src/main.rs`
- [Viewer UI](https://github.com/eng-cc/oasis7/blob/main/crates/oasis7_viewer/software_safe_src/main.jsx): `crates/oasis7_viewer/software_safe_src/main.jsx`
- [Viewer Server](https://github.com/eng-cc/oasis7/blob/main/crates/oasis7/src/viewer/server.rs): `crates/oasis7/src/viewer/server.rs`

### Agent Simulation

- [Agent](https://github.com/eng-cc/oasis7/blob/main/crates/oasis7/src/simulator/agent.rs): `crates/oasis7/src/simulator/agent.rs`
- [Decision Provider](https://github.com/eng-cc/oasis7/blob/main/crates/oasis7/src/simulator/decision_provider.rs): `crates/oasis7/src/simulator/decision_provider.rs`
- [Cognition Policy](https://github.com/eng-cc/oasis7/blob/main/crates/oasis7/src/simulator/cognition_policy.rs): `crates/oasis7/src/simulator/cognition_policy.rs`
- [Async Agent Runner](https://github.com/eng-cc/oasis7/blob/main/crates/oasis7/src/simulator/async_agent_runner.rs): `crates/oasis7/src/simulator/async_agent_runner.rs`
- [Turn Engine](https://github.com/eng-cc/oasis7/blob/main/crates/oasis7/src/simulator/turn_engine.rs): `crates/oasis7/src/simulator/turn_engine.rs`

### World Rules

- [WASM Modules](https://github.com/eng-cc/oasis7/blob/main/crates/oasis7/src/runtime/module_store.rs): `crates/oasis7/src/runtime/module_store.rs`
- [World Runtime](https://github.com/eng-cc/oasis7/blob/main/crates/oasis7/src/runtime/state.rs): `crates/oasis7/src/runtime/state.rs`
- [Gameplay Rules](https://github.com/eng-cc/oasis7/blob/main/crates/oasis7/src/runtime/gameplay.rs): `crates/oasis7/src/runtime/gameplay.rs`
- [Governance](https://github.com/eng-cc/oasis7/blob/main/crates/oasis7/src/runtime/governance.rs): `crates/oasis7/src/runtime/governance.rs`

### Execution and Consensus

- [Node Engine](https://github.com/eng-cc/oasis7/blob/main/crates/oasis7_node/src/node_engine_core.rs): `crates/oasis7_node/src/node_engine_core.rs`
- [Replication](https://github.com/eng-cc/oasis7/blob/main/crates/oasis7_node/src/node_engine_replication.rs): `crates/oasis7_node/src/node_engine_replication.rs`
- [Consensus](https://github.com/eng-cc/oasis7/blob/main/crates/oasis7_consensus/src/lib.rs): `crates/oasis7_consensus/src/lib.rs`

### Persistence and Access

- [Execution Storage](https://github.com/eng-cc/oasis7/blob/main/crates/oasis7_net/src/execution_storage.rs): `crates/oasis7_net/src/execution_storage.rs`
- [Distributed Storage](https://github.com/eng-cc/oasis7/blob/main/crates/oasis7_distfs/src/lib.rs): `crates/oasis7_distfs/src/lib.rs`
- [Peer Networking](https://github.com/eng-cc/oasis7/blob/main/crates/oasis7_net/src/libp2p_net/peer_manager.rs): `crates/oasis7_net/src/libp2p_net/peer_manager.rs`
- [Runtime Status](https://github.com/eng-cc/oasis7/blob/main/crates/oasis7/src/bin/oasis7_chain_runtime/status_payload.rs): `crates/oasis7/src/bin/oasis7_chain_runtime/status_payload.rs`
- [Reward Worker](https://github.com/eng-cc/oasis7/blob/main/crates/oasis7/src/bin/oasis7_chain_runtime/reward_runtime_worker.rs): `crates/oasis7/src/bin/oasis7_chain_runtime/reward_runtime_worker.rs`
- [Storage Metrics](https://github.com/eng-cc/oasis7/blob/main/crates/oasis7/src/bin/oasis7_chain_runtime/storage_metrics.rs): `crates/oasis7/src/bin/oasis7_chain_runtime/storage_metrics.rs`

### Other components

- **Player**

## Connections

- Player → Client Launcher: guides indirectly (evidence: `README.md`)
- Player → Viewer UI: observes and guides (evidence: `README.md`)
- Viewer UI → Viewer Server: sends requests
- Viewer Server → World Runtime: serves snapshots (evidence: `crates/oasis7/src/viewer/server.rs`)
- Agent → Decision Provider: requests decisions (evidence: `crates/oasis7/src/simulator/agent.rs`)
- Async Agent Runner → Agent: runs (evidence: `crates/oasis7/src/simulator/async_agent_runner.rs`)
- Async Agent Runner → Cognition Policy: applies policy (evidence: `crates/oasis7/src/simulator/async_agent_runner.rs`)
- Turn Engine → Async Agent Runner: delegates turns (evidence: `crates/oasis7/src/simulator/turn_engine.rs`)
- Turn Engine → World Runtime: requires runtime proof (evidence: `crates/oasis7/src/simulator/turn_engine.rs`)
- Player → WASM Modules: guides development (evidence: `README.md`)
- WASM Modules → World Runtime: extends rules (evidence: `README.md`)
- World Runtime → Gameplay Rules: validates actions
- World Runtime → Governance: applies governance
- World Runtime → Node Engine: supplies world execution (evidence: `README.md`)
- Node Engine → Consensus: proposes state (evidence: `README.md`)
- Node Engine → Replication: dispatches replication (evidence: `crates/oasis7_node/src/node_engine_replication.rs`)
- Replication → Execution Storage: fetches and persists
- Execution Storage → Distributed Storage: writes execution data
- Consensus → Peer Networking: coordinates peers (evidence: `README.md`)
- Replication → Peer Networking: syncs peers
- Runtime Status → Reward Worker: reports worker status (evidence: `crates/oasis7/src/bin/oasis7_chain_runtime/status_payload.rs`)
- Runtime Status → Storage Metrics: reports storage usage (evidence: `crates/oasis7/src/bin/oasis7_chain_runtime/status_payload.rs`)