# archestra-ai/openappa architecture

> Architecture diagram of the GitHub repository archestra-ai/openappa, 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/archestra-ai/openappa
- Repository: https://github.com/archestra-ai/openappa

## Overview

OpenAPPA mediates agent tool use: a call enters through a host integration, the runtime reconstructs the trajectory state, and the pure APPA engine decides whether the proposed data flow is allowed before dispatch. The runtime records durable trajectory events and supports policy configuration, installation, and reporting. The README documents the main integration and product capabilities; source excerpts and the SOURCE INDEX support only selected internal links, so unsampled subsystem relationships are omitted rather than inferred.

Main entry points: [`appa-runtime/src/api/mod.rs`](https://github.com/archestra-ai/openappa/blob/main/appa-runtime/src/api/mod.rs) (Session handling), [`appa-runtime/src/engine.rs`](https://github.com/archestra-ai/openappa/blob/main/appa-runtime/src/engine.rs) (Engine boundary), [`appa-engine/src/engine.rs`](https://github.com/archestra-ai/openappa/blob/main/appa-engine/src/engine.rs) (APPA decision core), [`appa-runtime-api/src/lib.rs`](https://github.com/archestra-ai/openappa/blob/main/appa-runtime-api/src/lib.rs) (Runtime API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_integrations["Agent integrations"]
  node_claude["Claude Code adapter<br/>[parse.rs]"]
  node_amp["Amp adapter<br/>[lib.rs]"]
  node_kagent["Kagent adapter<br/>[lib.rs]"]
end

subgraph group_runtime["Runtime orchestration"]
  node_runtime_api["Runtime API<br/>[lib.rs]"]
  node_runtime["Runtime host<br/>[main.rs]"]
  node_session_api["Session handling<br/>[mod.rs]"]
  node_runtime_engine["Engine boundary<br/>[engine.rs]"]
  node_dispatch["Tool dispatch<br/>[mod.rs]"]
end

subgraph group_decision["Policy decisions"]
  node_engine["APPA decision core<br/>[engine.rs]"]
  node_call_check["Flow check<br/>[check.rs]"]
  node_audience["Audience evidence<br/>[audience.rs]"]
  node_contracts["Tool contracts<br/>[contract.rs]"]
end

subgraph group_state["Policy and state"]
  node_policy["Policy configuration<br/>[config.rs]"]
  node_eventlog[("Trajectory event log<br/>[lib.rs]")]
end

subgraph group_operations["Deployment and reporting"]
  node_marketplace["Package marketplace<br/>[marketplace.rs]"]
  node_installation["Runtime installation<br/>[installation.rs]"]
  node_batteries["Batteries and checks<br/>[batteries.rs]"]
  node_yell["User reporting<br/>[mod.rs]"]
  node_receiver["Report receiver<br/>[main.py]"]
end

node_agent(("Agent user"))
node_tool{{"Agent tools"}}

node_agent -->|"submits hooks"| node_claude
node_claude -.->|"sends events"| node_runtime_api
node_amp -->|"checks calls"| node_runtime_api
node_kagent -.->|"integrates runtime"| node_runtime_api
node_runtime -->|"serves sessions"| node_session_api
node_session_api -->|"requests decisions"| node_runtime_engine
node_runtime_engine -->|"evaluates calls"| node_engine
node_engine -.->|"checks policy"| node_call_check
node_call_check -.->|"uses evidence"| node_audience
node_engine -.->|"reads contracts"| node_contracts
node_session_api -.->|"loads policy"| node_policy
node_runtime_engine -->|"rebuilds view"| node_eventlog
node_session_api -->|"authorizes dispatch"| node_dispatch
node_dispatch -->|"dispatches allowed calls"| node_tool
node_marketplace -->|"supplies packages"| node_installation
node_installation -->|"deploys runtime"| node_runtime
node_batteries -->|"provides sources"| node_audience
node_yell -.->|"sends report"| node_receiver

click node_claude "https://github.com/archestra-ai/openappa/blob/main/appa-adapter-claude-code/src/parse.rs"
click node_amp "https://github.com/archestra-ai/openappa/blob/main/appa-adapter-amp/src/lib.rs"
click node_kagent "https://github.com/archestra-ai/openappa/blob/main/appa-adapter-kagent/src/lib.rs"
click node_runtime_api "https://github.com/archestra-ai/openappa/blob/main/appa-runtime-api/src/lib.rs"
click node_runtime "https://github.com/archestra-ai/openappa/blob/main/appa-runtime/src/main.rs"
click node_session_api "https://github.com/archestra-ai/openappa/blob/main/appa-runtime/src/api/mod.rs"
click node_runtime_engine "https://github.com/archestra-ai/openappa/blob/main/appa-runtime/src/engine.rs"
click node_dispatch "https://github.com/archestra-ai/openappa/blob/main/appa-runtime/src/api/mod.rs"
click node_engine "https://github.com/archestra-ai/openappa/blob/main/appa-engine/src/engine.rs"
click node_call_check "https://github.com/archestra-ai/openappa/blob/main/appa-engine/src/check.rs"
click node_audience "https://github.com/archestra-ai/openappa/blob/main/appa-engine/src/audience.rs"
click node_contracts "https://github.com/archestra-ai/openappa/blob/main/appa-engine/src/contract.rs"
click node_policy "https://github.com/archestra-ai/openappa/blob/main/appa-policy/src/config.rs"
click node_eventlog "https://github.com/archestra-ai/openappa/blob/main/appa-eventlog/src/lib.rs"
click node_marketplace "https://github.com/archestra-ai/openappa/blob/main/appa-package/src/marketplace.rs"
click node_installation "https://github.com/archestra-ai/openappa/blob/main/appa-runtime/src/installation.rs"
click node_batteries "https://github.com/archestra-ai/openappa/blob/main/appa-runtime/src/batteries.rs"
click node_yell "https://github.com/archestra-ai/openappa/blob/main/appa-runtime/src/yell/mod.rs"
click node_receiver "https://github.com/archestra-ai/openappa/blob/main/receiver/appa-yell/main.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_claude,node_amp,node_kagent,node_agent toneBlue
class node_runtime_api,node_runtime,node_session_api,node_runtime_engine,node_dispatch toneAmber
class node_engine,node_call_check,node_audience,node_contracts toneMint
class node_policy,node_eventlog toneRose
class node_marketplace,node_installation,node_batteries,node_yell,node_receiver,node_tool toneIndigo
```

## Components

### Agent integrations

- [Claude Code adapter](https://github.com/archestra-ai/openappa/blob/main/appa-adapter-claude-code/src/parse.rs): `appa-adapter-claude-code/src/parse.rs`
- [Amp adapter](https://github.com/archestra-ai/openappa/blob/main/appa-adapter-amp/src/lib.rs): `appa-adapter-amp/src/lib.rs`
- [Kagent adapter](https://github.com/archestra-ai/openappa/blob/main/appa-adapter-kagent/src/lib.rs): `appa-adapter-kagent/src/lib.rs`

### Runtime orchestration

- [Runtime API](https://github.com/archestra-ai/openappa/blob/main/appa-runtime-api/src/lib.rs): `appa-runtime-api/src/lib.rs`
- [Runtime host](https://github.com/archestra-ai/openappa/blob/main/appa-runtime/src/main.rs): `appa-runtime/src/main.rs`
- [Session handling](https://github.com/archestra-ai/openappa/blob/main/appa-runtime/src/api/mod.rs): `appa-runtime/src/api/mod.rs`
- [Engine boundary](https://github.com/archestra-ai/openappa/blob/main/appa-runtime/src/engine.rs): `appa-runtime/src/engine.rs`
- [Tool dispatch](https://github.com/archestra-ai/openappa/blob/main/appa-runtime/src/api/mod.rs): `appa-runtime/src/api/mod.rs`

### Policy decisions

- [APPA decision core](https://github.com/archestra-ai/openappa/blob/main/appa-engine/src/engine.rs): `appa-engine/src/engine.rs`
- [Flow check](https://github.com/archestra-ai/openappa/blob/main/appa-engine/src/check.rs): `appa-engine/src/check.rs`
- [Audience evidence](https://github.com/archestra-ai/openappa/blob/main/appa-engine/src/audience.rs): `appa-engine/src/audience.rs`
- [Tool contracts](https://github.com/archestra-ai/openappa/blob/main/appa-engine/src/contract.rs): `appa-engine/src/contract.rs`

### Policy and state

- [Policy configuration](https://github.com/archestra-ai/openappa/blob/main/appa-policy/src/config.rs): `appa-policy/src/config.rs`
- [Trajectory event log](https://github.com/archestra-ai/openappa/blob/main/appa-eventlog/src/lib.rs): `appa-eventlog/src/lib.rs`

### Deployment and reporting

- [Package marketplace](https://github.com/archestra-ai/openappa/blob/main/appa-package/src/marketplace.rs): `appa-package/src/marketplace.rs`
- [Runtime installation](https://github.com/archestra-ai/openappa/blob/main/appa-runtime/src/installation.rs): `appa-runtime/src/installation.rs`
- [Batteries and checks](https://github.com/archestra-ai/openappa/blob/main/appa-runtime/src/batteries.rs): `appa-runtime/src/batteries.rs`
- [User reporting](https://github.com/archestra-ai/openappa/blob/main/appa-runtime/src/yell/mod.rs): `appa-runtime/src/yell/mod.rs`
- [Report receiver](https://github.com/archestra-ai/openappa/blob/main/receiver/appa-yell/main.py): `receiver/appa-yell/main.py`

### Other components

- **Agent user**
- **Agent tools**

## Connections

- Agent user → Claude Code adapter: submits hooks (evidence: `README.md`)
- Claude Code adapter → Runtime API: sends events
- Amp adapter → Runtime API: checks calls (evidence: `README.md`)
- Kagent adapter → Runtime API: integrates runtime
- Runtime host → Session handling: serves sessions (evidence: `appa-runtime/src/main.rs`)
- Session handling → Engine boundary: requests decisions (evidence: `appa-runtime/src/api/mod.rs`)
- Engine boundary → APPA decision core: evaluates calls (evidence: `appa-runtime/src/engine.rs`)
- APPA decision core → Flow check: checks policy
- Flow check → Audience evidence: uses evidence (evidence: `appa-engine/src/check.rs`)
- APPA decision core → Tool contracts: reads contracts
- Session handling → Policy configuration: loads policy
- Engine boundary → Trajectory event log: rebuilds view (evidence: `appa-runtime/src/engine.rs`)
- Session handling → Tool dispatch: authorizes dispatch (evidence: `README.md`)
- Tool dispatch → Agent tools: dispatches allowed calls (evidence: `README.md`)
- Package marketplace → Runtime installation: supplies packages (evidence: `README.md`)
- Runtime installation → Runtime host: deploys runtime (evidence: `README.md`)
- Batteries and checks → Audience evidence: provides sources (evidence: `appa-engine/src/audience.rs`)
- User reporting → Report receiver: sends report