# theory903/open-ippoc architecture

> Architecture diagram of the GitHub repository theory903/open-ippoc, 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/theory903/open-ippoc
- Repository: https://github.com/theory903/open-ippoc

## Overview

IPPOC-OS is a sovereign cognitive operating system: an operator submits signals or controls autonomy, Cortex processes cognitive work and invokes tools, and Soma supplies identity, trust, and memory services. Its documented capabilities also include persistent memory, intent/reflection loops, auditable execution, and optional OpenClaw integration. The source excerpts support the cognitive-to-tool path; README statements support the service and CLI capabilities. Several subsystems are represented from documentation and the tree, so their internal links are omitted where source wiring was not shown.

Main entry points: [`src/ippoc/cortex/cortex/server.py`](https://github.com/theory903/open-ippoc/blob/main/src/ippoc/cortex/cortex/server.py) (Cortex API), [`src/ippoc/cortex/core/orchestrator.py`](https://github.com/theory903/open-ippoc/blob/main/src/ippoc/cortex/core/orchestrator.py) (Tool Orchestrator), [`src/ippoc/cortex/cortex/langgraph_engine.py`](https://github.com/theory903/open-ippoc/blob/main/src/ippoc/cortex/cortex/langgraph_engine.py) (Cognitive Workflow), [`src/ippoc/soma/src/main.rs`](https://github.com/theory903/open-ippoc/blob/main/src/ippoc/soma/src/main.rs) (Soma Identity and Trust)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime and API"]
  node_cli["IPPOC CLI<br/>[main.py]"]
  node_startup["Service Startup<br/>[genesis.ts]"]
  node_cortex_api["Cortex API<br/>[server.py]"]
  node_openclaw["OpenClaw Adapter"]
end

subgraph group_cognition["Cognition and Autonomy"]
  node_cognitive_state["Cognitive Schemas<br/>[schemas.py]"]
  node_langgraph["Cognitive Workflow"]
  node_two_tower["Two-Tower Reasoning<br/>[two_tower.py]"]
  node_telepathy["Telepathy Swarm<br/>[telepathy.py]"]
  node_intent["Intent Engine<br/>[intent_engine.py]"]
  node_reflection["Reflection Engine"]
  node_autonomy["Autonomy Controls<br/>[autonomy.py]"]
end

subgraph group_execution["Policy and Execution"]
  node_orchestrator["Tool Orchestrator<br/>[orchestrator.py]"]
  node_tool_contract["Tool Contract<br/>[base.py]"]
  node_capability_tools["Capability Tools"]
  node_ledger[("Action Ledger<br/>[ledger.py]")]
end

subgraph group_state["Identity and Memory"]
  node_soma["Soma Identity and Trust<br/>[main.rs]"]
  node_mnemosyne[("Memory Services")]
end

node_operator(("Operator"))

node_operator -->|"controls"| node_cli
node_operator -->|"submits signals"| node_cortex_api
node_cli -.->|"starts services"| node_startup
node_startup -->|"starts first"| node_soma
node_startup -->|"starts next"| node_cortex_api
node_cortex_api -->|"uses schemas"| node_cognitive_state
node_cortex_api -->|"dispatches cognition"| node_langgraph
node_langgraph -->|"requests impulse"| node_two_tower
node_langgraph -->|"uses swarm"| node_telepathy
node_langgraph -->|"invokes tools"| node_orchestrator
node_orchestrator -->|"executes contract"| node_tool_contract
node_orchestrator -->|"dispatches"| node_capability_tools
node_orchestrator -.->|"audits actions"| node_ledger
node_orchestrator -.->|"authenticates with"| node_soma
node_cortex_api -->|"validates keys"| node_soma
node_cortex_api -.->|"uses persistent memory"| node_mnemosyne
node_reflection -->|"reads recent memory"| node_soma
node_reflection -->|"creates intents"| node_intent
node_intent -->|"emits thoughts"| node_cognitive_state
node_operator -->|"sets autonomy"| node_autonomy
node_cortex_api -->|"exposes controls"| node_autonomy
node_operator -.->|"integrates optionally"| node_openclaw

click node_cli "https://github.com/theory903/open-ippoc/blob/main/src/ippoc/cli/main.py"
click node_startup "https://github.com/theory903/open-ippoc/blob/main/src/ippoc/runtime/bootstrap/genesis.ts"
click node_cortex_api "https://github.com/theory903/open-ippoc/blob/main/src/ippoc/cortex/cortex/server.py"
click node_cognitive_state "https://github.com/theory903/open-ippoc/blob/main/src/ippoc/cortex/cortex/schemas.py"
click node_langgraph "https://github.com/theory903/open-ippoc/blob/main/src/ippoc/cortex/cortex/langgraph_engine.py"
click node_two_tower "https://github.com/theory903/open-ippoc/blob/main/src/ippoc/cortex/cortex/two_tower.py"
click node_telepathy "https://github.com/theory903/open-ippoc/blob/main/src/ippoc/cortex/cortex/telepathy.py"
click node_intent "https://github.com/theory903/open-ippoc/blob/main/src/ippoc/maksad/intent_engine.py"
click node_reflection "https://github.com/theory903/open-ippoc/blob/main/src/ippoc/maksad/reflection_engine.py"
click node_orchestrator "https://github.com/theory903/open-ippoc/blob/main/src/ippoc/cortex/core/orchestrator.py"
click node_tool_contract "https://github.com/theory903/open-ippoc/blob/main/src/ippoc/cortex/core/tools/base.py"
click node_capability_tools "https://github.com/theory903/open-ippoc/tree/main/src/ippoc/cortex/core/tools"
click node_ledger "https://github.com/theory903/open-ippoc/blob/main/src/ippoc/cortex/core/ledger.py"
click node_soma "https://github.com/theory903/open-ippoc/blob/main/src/ippoc/soma/src/main.rs"
click node_mnemosyne "https://github.com/theory903/open-ippoc/tree/main/src/ippoc/mnemosyne"
click node_autonomy "https://github.com/theory903/open-ippoc/blob/main/src/ippoc/cortex/core/autonomy.py"
click node_openclaw "https://github.com/theory903/open-ippoc/blob/main/src/ippoc/cortex/plugins/openclaw/openclaw_adapter.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_cli,node_startup,node_cortex_api,node_openclaw toneBlue
class node_cognitive_state,node_langgraph,node_two_tower,node_telepathy,node_intent,node_reflection,node_autonomy toneAmber
class node_orchestrator,node_tool_contract,node_capability_tools,node_ledger toneMint
class node_soma,node_mnemosyne toneRose
class node_operator toneIndigo
```

## Components

### Runtime and API

- [IPPOC CLI](https://github.com/theory903/open-ippoc/blob/main/src/ippoc/cli/main.py): `src/ippoc/cli/main.py`
- [Service Startup](https://github.com/theory903/open-ippoc/blob/main/src/ippoc/runtime/bootstrap/genesis.ts): `src/ippoc/runtime/bootstrap/genesis.ts`
- [Cortex API](https://github.com/theory903/open-ippoc/blob/main/src/ippoc/cortex/cortex/server.py): `src/ippoc/cortex/cortex/server.py`
- [OpenClaw Adapter](https://github.com/theory903/open-ippoc/blob/main/src/ippoc/cortex/plugins/openclaw/openclaw_adapter.py): `src/ippoc/cortex/plugins/openclaw/openclaw_adapter.py`

### Cognition and Autonomy

- [Cognitive Schemas](https://github.com/theory903/open-ippoc/blob/main/src/ippoc/cortex/cortex/schemas.py): `src/ippoc/cortex/cortex/schemas.py`
- [Cognitive Workflow](https://github.com/theory903/open-ippoc/blob/main/src/ippoc/cortex/cortex/langgraph_engine.py): `src/ippoc/cortex/cortex/langgraph_engine.py`
- [Two-Tower Reasoning](https://github.com/theory903/open-ippoc/blob/main/src/ippoc/cortex/cortex/two_tower.py): `src/ippoc/cortex/cortex/two_tower.py`
- [Telepathy Swarm](https://github.com/theory903/open-ippoc/blob/main/src/ippoc/cortex/cortex/telepathy.py): `src/ippoc/cortex/cortex/telepathy.py`
- [Intent Engine](https://github.com/theory903/open-ippoc/blob/main/src/ippoc/maksad/intent_engine.py): `src/ippoc/maksad/intent_engine.py`
- [Reflection Engine](https://github.com/theory903/open-ippoc/blob/main/src/ippoc/maksad/reflection_engine.py): `src/ippoc/maksad/reflection_engine.py`
- [Autonomy Controls](https://github.com/theory903/open-ippoc/blob/main/src/ippoc/cortex/core/autonomy.py): `src/ippoc/cortex/core/autonomy.py`

### Policy and Execution

- [Tool Orchestrator](https://github.com/theory903/open-ippoc/blob/main/src/ippoc/cortex/core/orchestrator.py): `src/ippoc/cortex/core/orchestrator.py`
- [Tool Contract](https://github.com/theory903/open-ippoc/blob/main/src/ippoc/cortex/core/tools/base.py): `src/ippoc/cortex/core/tools/base.py`
- [Capability Tools](https://github.com/theory903/open-ippoc/tree/main/src/ippoc/cortex/core/tools): `src/ippoc/cortex/core/tools`
- [Action Ledger](https://github.com/theory903/open-ippoc/blob/main/src/ippoc/cortex/core/ledger.py): `src/ippoc/cortex/core/ledger.py`

### Identity and Memory

- [Soma Identity and Trust](https://github.com/theory903/open-ippoc/blob/main/src/ippoc/soma/src/main.rs): `src/ippoc/soma/src/main.rs`
- [Memory Services](https://github.com/theory903/open-ippoc/tree/main/src/ippoc/mnemosyne): `src/ippoc/mnemosyne`

### Other components

- **Operator**

## Connections

- Operator → IPPOC CLI: controls (evidence: `README.md`)
- Operator → Cortex API: submits signals (evidence: `README.md`)
- IPPOC CLI → Service Startup: starts services
- Service Startup → Soma Identity and Trust: starts first (evidence: `README.md`)
- Service Startup → Cortex API: starts next (evidence: `README.md`)
- Cortex API → Cognitive Schemas: uses schemas
- Cortex API → Cognitive Workflow: dispatches cognition
- Cognitive Workflow → Two-Tower Reasoning: requests impulse (evidence: `src/ippoc/cortex/cortex/langgraph_engine.py`)
- Cognitive Workflow → Telepathy Swarm: uses swarm (evidence: `src/ippoc/cortex/cortex/langgraph_engine.py`)
- Cognitive Workflow → Tool Orchestrator: invokes tools (evidence: `src/ippoc/cortex/cortex/langgraph_engine.py`)
- Tool Orchestrator → Tool Contract: executes contract
- Tool Orchestrator → Capability Tools: dispatches (evidence: `src/ippoc/cortex/core/orchestrator.py`)
- Tool Orchestrator → Action Ledger: audits actions
- Tool Orchestrator → Soma Identity and Trust: authenticates with
- Cortex API → Soma Identity and Trust: validates keys
- Cortex API → Memory Services: uses persistent memory
- Reflection Engine → Soma Identity and Trust: reads recent memory (evidence: `src/ippoc/maksad/reflection_engine.py`)
- Reflection Engine → Intent Engine: creates intents (evidence: `src/ippoc/maksad/reflection_engine.py`)
- Intent Engine → Cognitive Schemas: emits thoughts (evidence: `src/ippoc/maksad/intent_engine.py`)
- Operator → Autonomy Controls: sets autonomy (evidence: `README.md`)
- Cortex API → Autonomy Controls: exposes controls
- Operator → OpenClaw Adapter: integrates optionally (evidence: `README.md`)
