# oranai-ltd/oransim architecture

> Architecture diagram of the GitHub repository oranai-ltd/oransim, 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/oranai-ltd/oransim
- Repository: https://github.com/oranai-ltd/oransim

## Overview

Oransim is a causal marketing-campaign simulator: teams define a campaign scenario, simulate audience exposure and consumer response, and inspect predicted KPIs or counterfactual outcomes. The documented use cases include pre-launch ROI ranking, mid-campaign interventions, and post-mortem comparisons. The graph highlights the API workflow and major modeling subsystems; some links are based on README descriptions because their implementation files were not excerpted.

Main entry points: [`backend/oransim/api_routers/predict.py`](https://github.com/oranai-ltd/oransim/blob/main/backend/oransim/api_routers/predict.py) (Prediction API), [`backend/oransim/api_state.py`](https://github.com/oranai-ltd/oransim/blob/main/backend/oransim/api_state.py) (Runtime bootstrap), [`backend/oransim/sandbox/engine.py`](https://github.com/oranai-ltd/oransim/blob/main/backend/oransim/sandbox/engine.py) (Scenario sandbox), [`backend/oransim/platforms`](https://github.com/oranai-ltd/oransim/tree/main/backend/oransim/platforms) (Platform adapters)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Scenario API"]
  node_predict_api["Prediction API<br/>[predict.py]"]
  node_runtime_state["Runtime bootstrap<br/>[api_state.py]"]
  node_sandbox["Scenario sandbox<br/>[engine.py]"]
  node_results["KPIs and traces<br/>[predict.py]"]
end

subgraph group_simulation["Campaign Simulation"]
  node_platform_world["Platform exposure model"]
  node_platform_adapters["Platform adapters"]
  node_recsys["Recommendation simulation<br/>[recsys_rl.py]"]
  node_campaign_effects["Campaign dynamics<br/>[legacy_hawkes.py]"]
  node_embedding_bus["Embedding bus<br/>[embedding_bus.py]"]
  node_real_embedder["Real embedder<br/>[real_embedder.py]"]
end

subgraph group_causal["Causal Analysis"]
  node_causal_model["Structural causal model<br/>[scm.py]"]
  node_counterfactual["Counterfactual engine<br/>[counterfactual.py]"]
end

subgraph group_agents["Consumer Agents"]
  node_response["Consumer response<br/>[statistical.py]"]
  node_soul_agents["Persona agents<br/>[soul.py]"]
  node_llm_souls["LLM persona responses<br/>[soul_llm.py]"]
  node_llm_provider["LLM providers"]
end

subgraph group_data["Simulation Inputs"]
  node_population["Virtual population<br/>[population.py]"]
  node_campaign_inputs["Creative and KOL data<br/>[creatives.py]"]
  node_platform_data["Platform configuration<br/>[platforms.py]"]
end

node_team(("Growth team"))

node_team -->|"submits scenario"| node_predict_api
node_predict_api -->|"uses runtime"| node_runtime_state
node_runtime_state -->|"generates"| node_population
node_runtime_state -->|"initializes"| node_sandbox
node_predict_api -->|"uses platform data"| node_platform_data
node_predict_api -->|"simulates exposure"| node_platform_world
node_predict_api -->|"uses recommendation model"| node_recsys
node_predict_api -->|"runs lifecycle"| node_campaign_effects
node_predict_api -->|"runs causal graph"| node_causal_model
node_predict_api -->|"simulates responses"| node_response
node_predict_api -->|"uses persona agents"| node_soul_agents
node_predict_api -.->|"optionally simulates discourse"| node_llm_souls
node_llm_souls -->|"routes generation"| node_llm_provider
node_predict_api -->|"supports interventions"| node_counterfactual
node_sandbox -->|"recomputes scenarios"| node_counterfactual
node_predict_api -->|"returns KPIs"| node_results
node_predict_api -->|"uses creative and KOL inputs"| node_campaign_inputs
node_platform_adapters -.->|"implements platform behavior"| node_platform_world
node_runtime_state -->|"indexes simulation data"| node_embedding_bus
node_embedding_bus -->|"supports real embeddings"| node_real_embedder
node_predict_api -.->|"supports multiple platforms"| node_platform_adapters

click node_predict_api "https://github.com/oranai-ltd/oransim/blob/main/backend/oransim/api_routers/predict.py"
click node_runtime_state "https://github.com/oranai-ltd/oransim/blob/main/backend/oransim/api_state.py"
click node_sandbox "https://github.com/oranai-ltd/oransim/blob/main/backend/oransim/sandbox/engine.py"
click node_population "https://github.com/oranai-ltd/oransim/blob/main/backend/oransim/data/population.py"
click node_campaign_inputs "https://github.com/oranai-ltd/oransim/blob/main/backend/oransim/data/creatives.py"
click node_platform_data "https://github.com/oranai-ltd/oransim/blob/main/backend/oransim/data/platforms.py"
click node_platform_world "https://github.com/oranai-ltd/oransim/blob/main/backend/oransim/platforms/xhs/world_model_legacy.py"
click node_platform_adapters "https://github.com/oranai-ltd/oransim/tree/main/backend/oransim/platforms"
click node_recsys "https://github.com/oranai-ltd/oransim/blob/main/backend/oransim/platforms/xhs/recsys_rl.py"
click node_response "https://github.com/oranai-ltd/oransim/blob/main/backend/oransim/agents/statistical.py"
click node_soul_agents "https://github.com/oranai-ltd/oransim/blob/main/backend/oransim/agents/soul.py"
click node_llm_souls "https://github.com/oranai-ltd/oransim/blob/main/backend/oransim/agents/soul_llm.py"
click node_campaign_effects "https://github.com/oranai-ltd/oransim/blob/main/backend/oransim/diffusion/legacy_hawkes.py"
click node_causal_model "https://github.com/oranai-ltd/oransim/blob/main/backend/oransim/causal/scm.py"
click node_counterfactual "https://github.com/oranai-ltd/oransim/blob/main/backend/oransim/causal/counterfactual.py"
click node_embedding_bus "https://github.com/oranai-ltd/oransim/blob/main/backend/oransim/runtime/embedding_bus.py"
click node_real_embedder "https://github.com/oranai-ltd/oransim/blob/main/backend/oransim/runtime/real_embedder.py"
click node_llm_provider "https://github.com/oranai-ltd/oransim/tree/main/backend/oransim/agents/llm_providers"
click node_results "https://github.com/oranai-ltd/oransim/blob/main/backend/oransim/api_routers/predict.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_predict_api,node_runtime_state,node_sandbox,node_results toneBlue
class node_platform_world,node_platform_adapters,node_recsys,node_campaign_effects,node_embedding_bus,node_real_embedder toneAmber
class node_causal_model,node_counterfactual toneMint
class node_response,node_soul_agents,node_llm_souls,node_llm_provider toneRose
class node_population,node_campaign_inputs,node_platform_data,node_team toneIndigo
```

## Components

### Scenario API

- [Prediction API](https://github.com/oranai-ltd/oransim/blob/main/backend/oransim/api_routers/predict.py): `backend/oransim/api_routers/predict.py`
- [Runtime bootstrap](https://github.com/oranai-ltd/oransim/blob/main/backend/oransim/api_state.py): `backend/oransim/api_state.py`
- [Scenario sandbox](https://github.com/oranai-ltd/oransim/blob/main/backend/oransim/sandbox/engine.py): `backend/oransim/sandbox/engine.py`
- [KPIs and traces](https://github.com/oranai-ltd/oransim/blob/main/backend/oransim/api_routers/predict.py): `backend/oransim/api_routers/predict.py`

### Campaign Simulation

- [Platform exposure model](https://github.com/oranai-ltd/oransim/blob/main/backend/oransim/platforms/xhs/world_model_legacy.py): `backend/oransim/platforms/xhs/world_model_legacy.py`
- [Platform adapters](https://github.com/oranai-ltd/oransim/tree/main/backend/oransim/platforms): `backend/oransim/platforms`
- [Recommendation simulation](https://github.com/oranai-ltd/oransim/blob/main/backend/oransim/platforms/xhs/recsys_rl.py): `backend/oransim/platforms/xhs/recsys_rl.py`
- [Campaign dynamics](https://github.com/oranai-ltd/oransim/blob/main/backend/oransim/diffusion/legacy_hawkes.py): `backend/oransim/diffusion/legacy_hawkes.py`
- [Embedding bus](https://github.com/oranai-ltd/oransim/blob/main/backend/oransim/runtime/embedding_bus.py): `backend/oransim/runtime/embedding_bus.py`
- [Real embedder](https://github.com/oranai-ltd/oransim/blob/main/backend/oransim/runtime/real_embedder.py): `backend/oransim/runtime/real_embedder.py`

### Causal Analysis

- [Structural causal model](https://github.com/oranai-ltd/oransim/blob/main/backend/oransim/causal/scm.py): `backend/oransim/causal/scm.py`
- [Counterfactual engine](https://github.com/oranai-ltd/oransim/blob/main/backend/oransim/causal/counterfactual.py): `backend/oransim/causal/counterfactual.py`

### Consumer Agents

- [Consumer response](https://github.com/oranai-ltd/oransim/blob/main/backend/oransim/agents/statistical.py): `backend/oransim/agents/statistical.py`
- [Persona agents](https://github.com/oranai-ltd/oransim/blob/main/backend/oransim/agents/soul.py): `backend/oransim/agents/soul.py`
- [LLM persona responses](https://github.com/oranai-ltd/oransim/blob/main/backend/oransim/agents/soul_llm.py): `backend/oransim/agents/soul_llm.py`
- [LLM providers](https://github.com/oranai-ltd/oransim/tree/main/backend/oransim/agents/llm_providers): `backend/oransim/agents/llm_providers`

### Simulation Inputs

- [Virtual population](https://github.com/oranai-ltd/oransim/blob/main/backend/oransim/data/population.py): `backend/oransim/data/population.py`
- [Creative and KOL data](https://github.com/oranai-ltd/oransim/blob/main/backend/oransim/data/creatives.py): `backend/oransim/data/creatives.py`
- [Platform configuration](https://github.com/oranai-ltd/oransim/blob/main/backend/oransim/data/platforms.py): `backend/oransim/data/platforms.py`

### Other components

- **Growth team**

## Connections

- Growth team → Prediction API: submits scenario
- Prediction API → Runtime bootstrap: uses runtime (evidence: `backend/oransim/api_routers/predict.py`)
- Runtime bootstrap → Virtual population: generates (evidence: `backend/oransim/api_state.py`)
- Runtime bootstrap → Scenario sandbox: initializes (evidence: `backend/oransim/api_state.py`)
- Prediction API → Platform configuration: uses platform data (evidence: `backend/oransim/api_routers/predict.py`)
- Prediction API → Platform exposure model: simulates exposure (evidence: `backend/oransim/api_routers/predict.py`)
- Prediction API → Recommendation simulation: uses recommendation model (evidence: `backend/oransim/api_routers/predict.py`)
- Prediction API → Campaign dynamics: runs lifecycle (evidence: `backend/oransim/api_routers/predict.py`)
- Prediction API → Structural causal model: runs causal graph (evidence: `backend/oransim/api_routers/predict.py`)
- Prediction API → Consumer response: simulates responses (evidence: `backend/oransim/api_routers/predict.py`)
- Prediction API → Persona agents: uses persona agents (evidence: `backend/oransim/api_routers/predict.py`)
- Prediction API → LLM persona responses: optionally simulates discourse (evidence: `backend/oransim/api_routers/predict.py`)
- LLM persona responses → LLM providers: routes generation (evidence: `backend/oransim/agents/soul_llm.py`)
- Prediction API → Counterfactual engine: supports interventions
- Scenario sandbox → Counterfactual engine: recomputes scenarios (evidence: `backend/oransim/sandbox/engine.py`)
- Prediction API → KPIs and traces: returns KPIs (evidence: `backend/oransim/api_routers/predict.py`)
- Prediction API → Creative and KOL data: uses creative and KOL inputs (evidence: `backend/oransim/api_routers/predict.py`)
- Platform adapters → Platform exposure model: implements platform behavior (evidence: `backend/oransim/platforms/xhs/recsys_rl.py`)
- Runtime bootstrap → Embedding bus: indexes simulation data (evidence: `backend/oransim/api_state.py`)
- Embedding bus → Real embedder: supports real embeddings (evidence: `backend/oransim/runtime/embedding_bus.py`)
- Prediction API → Platform adapters: supports multiple platforms (evidence: `backend/oransim/api_routers/predict.py`)
