# oliverevans96/blueberries-voi architecture

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

- Interactive diagram: https://gitdiagram.com/oliverevans96/blueberries-voi
- Repository: https://github.com/oliverevans96/blueberries-voi

## Overview

Blueberries-VOI models a perishable blueberry store, estimates hidden inventory freshness, evaluates ordering and value of information, and exposes the same Rust simulation through Python and a browser studio. The primary interactive workflow is operator input → studio → WebAssembly engine → daily simulation results; notebooks and batch studies use the Python package and native Rust engine. The graph includes the major documented capabilities and indexed core modules. Some subsystem links are supported by imports listed in the source index rather than sampled call bodies; browser-to-engine wiring is documented in the README.

Main entry points: [`crates/voi_core/src/session.rs`](https://github.com/oliverevans96/blueberries-voi/blob/main/crates/voi_core/src/session.rs) (Engine session), [`crates/voi_core/src/physics.rs`](https://github.com/oliverevans96/blueberries-voi/blob/main/crates/voi_core/src/physics.rs) (Daily physics), [`src/blueberries_voi/filter/belief.py`](https://github.com/oliverevans96/blueberries-voi/blob/main/src/blueberries_voi/filter/belief.py) (Particle filter), [`src/blueberries_voi/experiments/voi_profit.py`](https://github.com/oliverevans96/blueberries-voi/blob/main/src/blueberries_voi/experiments/voi_profit.py) (Batch studies)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_browser["Interactive studio"]
  node_studio["Studio UI<br/>[App.tsx]"]
  node_worker["WASM worker<br/>[wasmWorker.ts]"]
  node_wasm["WASM interface<br/>[lib.rs]"]
end

subgraph group_engine["Simulation engine"]
  node_session["Engine session<br/>[session.rs]"]
  node_physics["Daily physics<br/>[physics.rs]"]
  node_params["Model parameters<br/>[params.rs]"]
  node_demand["Demand calendar<br/>[demand_profile.rs]"]
  node_arrival["Arrival freshness<br/>[arrival.rs]"]
  node_shipments["Shipment lifecycle<br/>[shipments.rs]"]
  node_rng["Random streams<br/>[spawn_rng.rs]"]
  node_sim["Episode simulation<br/>[order_schedule.py]"]
end

subgraph group_inference["Belief and control"]
  node_filter["Particle filter<br/>[belief.py]"]
  node_obs["Observation contract<br/>[types.py]"]
  node_controller["Ordering policies<br/>[session_loop.py]"]
end

subgraph group_analysis["Analysis and interfaces"]
  node_profit["Profit metrics<br/>[profit.py]"]
  node_voi["VOI analysis<br/>[sweep.py]"]
  node_pyapi["Python engine API<br/>[lib.rs]"]
  node_research["Batch studies<br/>[voi_profit.py]"]
end

node_operator(("Store operator"))

node_operator -->|"operates"| node_studio
node_studio -->|"uses worker"| node_worker
node_worker -->|"runs kernel"| node_wasm
node_wasm -.->|"exposes engine"| node_session
node_session -->|"uses model"| node_arrival
node_session -->|"advances days"| node_physics
node_session -->|"uses shipments"| node_shipments
node_session -->|"configures"| node_params
node_session -->|"uses profile"| node_demand
node_physics -->|"reads parameters"| node_params
node_physics -->|"reads profile"| node_demand
node_physics -->|"draws randomness"| node_rng
node_params -->|"selects corridor"| node_arrival
node_session -->|"maintains beliefs"| node_filter
node_session -.->|"dispatches actions"| node_controller
node_controller -->|"reads beliefs"| node_filter
node_controller -->|"steps engine"| node_sim
node_sim -->|"scores days"| node_profit
node_research -->|"evaluates episodes"| node_sim
node_research -->|"evaluates beliefs"| node_filter
node_research -.->|"measures value"| node_voi
node_pyapi -->|"provides native access"| node_session
node_obs -.->|"defines observations"| node_filter

click node_studio "https://github.com/oliverevans96/blueberries-voi/blob/main/web/src/App.tsx"
click node_worker "https://github.com/oliverevans96/blueberries-voi/blob/main/web/src/engine/wasmWorker.ts"
click node_wasm "https://github.com/oliverevans96/blueberries-voi/blob/main/crates/voi_wasm/src/lib.rs"
click node_session "https://github.com/oliverevans96/blueberries-voi/blob/main/crates/voi_core/src/session.rs"
click node_physics "https://github.com/oliverevans96/blueberries-voi/blob/main/crates/voi_core/src/physics.rs"
click node_params "https://github.com/oliverevans96/blueberries-voi/blob/main/crates/voi_core/src/params.rs"
click node_demand "https://github.com/oliverevans96/blueberries-voi/blob/main/crates/voi_core/src/demand_profile.rs"
click node_arrival "https://github.com/oliverevans96/blueberries-voi/blob/main/crates/voi_core/src/arrival.rs"
click node_shipments "https://github.com/oliverevans96/blueberries-voi/blob/main/crates/voi_core/src/shipments.rs"
click node_rng "https://github.com/oliverevans96/blueberries-voi/blob/main/crates/voi_core/src/spawn_rng.rs"
click node_filter "https://github.com/oliverevans96/blueberries-voi/blob/main/src/blueberries_voi/filter/belief.py"
click node_obs "https://github.com/oliverevans96/blueberries-voi/blob/main/src/blueberries_voi/filter/types.py"
click node_controller "https://github.com/oliverevans96/blueberries-voi/blob/main/src/blueberries_voi/controller/session_loop.py"
click node_sim "https://github.com/oliverevans96/blueberries-voi/blob/main/src/blueberries_voi/sim/order_schedule.py"
click node_profit "https://github.com/oliverevans96/blueberries-voi/blob/main/src/blueberries_voi/sim/profit.py"
click node_voi "https://github.com/oliverevans96/blueberries-voi/blob/main/src/blueberries_voi/voi/sweep.py"
click node_pyapi "https://github.com/oliverevans96/blueberries-voi/blob/main/crates/voi_py/src/lib.rs"
click node_research "https://github.com/oliverevans96/blueberries-voi/blob/main/src/blueberries_voi/experiments/voi_profit.py"

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_studio,node_worker,node_wasm toneBlue
class node_session,node_physics,node_params,node_demand,node_arrival,node_shipments,node_rng,node_sim toneAmber
class node_filter,node_obs,node_controller toneMint
class node_profit,node_voi,node_pyapi,node_research toneRose
class node_operator toneIndigo
```

## Components

### Interactive studio

- [Studio UI](https://github.com/oliverevans96/blueberries-voi/blob/main/web/src/App.tsx): `web/src/App.tsx`
- [WASM worker](https://github.com/oliverevans96/blueberries-voi/blob/main/web/src/engine/wasmWorker.ts): `web/src/engine/wasmWorker.ts`
- [WASM interface](https://github.com/oliverevans96/blueberries-voi/blob/main/crates/voi_wasm/src/lib.rs): `crates/voi_wasm/src/lib.rs`

### Simulation engine

- [Engine session](https://github.com/oliverevans96/blueberries-voi/blob/main/crates/voi_core/src/session.rs): `crates/voi_core/src/session.rs`
- [Daily physics](https://github.com/oliverevans96/blueberries-voi/blob/main/crates/voi_core/src/physics.rs): `crates/voi_core/src/physics.rs`
- [Model parameters](https://github.com/oliverevans96/blueberries-voi/blob/main/crates/voi_core/src/params.rs): `crates/voi_core/src/params.rs`
- [Demand calendar](https://github.com/oliverevans96/blueberries-voi/blob/main/crates/voi_core/src/demand_profile.rs): `crates/voi_core/src/demand_profile.rs`
- [Arrival freshness](https://github.com/oliverevans96/blueberries-voi/blob/main/crates/voi_core/src/arrival.rs): `crates/voi_core/src/arrival.rs`
- [Shipment lifecycle](https://github.com/oliverevans96/blueberries-voi/blob/main/crates/voi_core/src/shipments.rs): `crates/voi_core/src/shipments.rs`
- [Random streams](https://github.com/oliverevans96/blueberries-voi/blob/main/crates/voi_core/src/spawn_rng.rs): `crates/voi_core/src/spawn_rng.rs`
- [Episode simulation](https://github.com/oliverevans96/blueberries-voi/blob/main/src/blueberries_voi/sim/order_schedule.py): `src/blueberries_voi/sim/order_schedule.py`

### Belief and control

- [Particle filter](https://github.com/oliverevans96/blueberries-voi/blob/main/src/blueberries_voi/filter/belief.py): `src/blueberries_voi/filter/belief.py`
- [Observation contract](https://github.com/oliverevans96/blueberries-voi/blob/main/src/blueberries_voi/filter/types.py): `src/blueberries_voi/filter/types.py`
- [Ordering policies](https://github.com/oliverevans96/blueberries-voi/blob/main/src/blueberries_voi/controller/session_loop.py): `src/blueberries_voi/controller/session_loop.py`

### Analysis and interfaces

- [Profit metrics](https://github.com/oliverevans96/blueberries-voi/blob/main/src/blueberries_voi/sim/profit.py): `src/blueberries_voi/sim/profit.py`
- [VOI analysis](https://github.com/oliverevans96/blueberries-voi/blob/main/src/blueberries_voi/voi/sweep.py): `src/blueberries_voi/voi/sweep.py`
- [Python engine API](https://github.com/oliverevans96/blueberries-voi/blob/main/crates/voi_py/src/lib.rs): `crates/voi_py/src/lib.rs`
- [Batch studies](https://github.com/oliverevans96/blueberries-voi/blob/main/src/blueberries_voi/experiments/voi_profit.py): `src/blueberries_voi/experiments/voi_profit.py`

### Other components

- **Store operator**

## Connections

- Store operator → Studio UI: operates (evidence: `README.md`)
- Studio UI → WASM worker: uses worker (evidence: `README.md`)
- WASM worker → WASM interface: runs kernel (evidence: `README.md`)
- WASM interface → Engine session: exposes engine
- Engine session → Arrival freshness: uses model (evidence: `crates/voi_core/src/session.rs`)
- Engine session → Daily physics: advances days (evidence: `crates/voi_core/src/session.rs`)
- Engine session → Shipment lifecycle: uses shipments (evidence: `crates/voi_core/src/session.rs`)
- Engine session → Model parameters: configures (evidence: `crates/voi_core/src/session.rs`)
- Engine session → Demand calendar: uses profile (evidence: `crates/voi_core/src/session.rs`)
- Daily physics → Model parameters: reads parameters (evidence: `crates/voi_core/src/physics.rs`)
- Daily physics → Demand calendar: reads profile (evidence: `crates/voi_core/src/physics.rs`)
- Daily physics → Random streams: draws randomness (evidence: `crates/voi_core/src/physics.rs`)
- Model parameters → Arrival freshness: selects corridor (evidence: `crates/voi_core/src/params.rs`)
- Engine session → Particle filter: maintains beliefs (evidence: `crates/voi_core/src/session.rs`)
- Engine session → Ordering policies: dispatches actions
- Ordering policies → Particle filter: reads beliefs (evidence: `src/blueberries_voi/controller/session_loop.py`)
- Ordering policies → Episode simulation: steps engine (evidence: `src/blueberries_voi/controller/session_loop.py`)
- Episode simulation → Profit metrics: scores days (evidence: `src/blueberries_voi/controller/session_loop.py`)
- Batch studies → Episode simulation: evaluates episodes (evidence: `src/blueberries_voi/experiments/voi_profit.py`)
- Batch studies → Particle filter: evaluates beliefs (evidence: `src/blueberries_voi/experiments/voi_profit.py`)
- Batch studies → VOI analysis: measures value
- Python engine API → Engine session: provides native access (evidence: `README.md`)
- Observation contract → Particle filter: defines observations
