# akadaan310/ora architecture

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

- Interactive diagram: https://gitdiagram.com/akadaan310/ora
- Repository: https://github.com/akadaan310/ora

## Overview

ORA is a model-free engine with an HTTP service and Python/TypeScript clients. The main workflow is an owner or script creating an ORA, explicitly reviewing and activating it, submitting a granted mission, and retrieving its result; the engine records transitions and mission events in a hash-chained SQLite ledger. The graph also includes documented catalog, PURL, listener, and native-kernel capabilities. Source excerpts establish the HTTP-to-engine and native-call paths; unsampled subsystems are included only where README capabilities support them.

Main entry points: [`service/engine.py`](https://github.com/akadaan310/ora/blob/main/service/engine.py) (Engine), [`service/app.py`](https://github.com/akadaan310/ora/blob/main/service/app.py) (HTTP service), [`sdk/python/ora_client.py`](https://github.com/akadaan310/ora/blob/main/sdk/python/ora_client.py) (Python SDK), [`sdk/typescript/ora.ts`](https://github.com/akadaan310/ora/blob/main/sdk/typescript/ora.ts) (TypeScript SDK)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Client and API"]
  node_python_sdk["Python SDK<br/>[ora_client.py]"]
  node_typescript_sdk["TypeScript SDK<br/>[ora.ts]"]
  node_http_api["HTTP service<br/>[app.py]"]
end

subgraph group_runtime["ORA Runtime"]
  node_engine["Engine<br/>[engine.py]"]
  node_lifecycle["ORA lifecycle<br/>[engine.py]"]
  node_mission_queue["Mission worker<br/>[engine.py]"]
  node_capabilities["Mission capabilities<br/>[engine.py]"]
  node_listener["Event listener<br/>[engine.py]"]
  node_ledger[("SQLite event ledger<br/>[engine.py]")]
end

subgraph group_native["Native Kernel"]
  node_native_bridge["Native bridge<br/>[native.py]"]
  node_c_api["C ABI<br/>[c_api.cpp]"]
  node_cpp_kernel["C++ primitives<br/>[tower.cpp]"]
  node_tower_types["Kernel interfaces<br/>[tower.hpp]"]
end

subgraph group_protocol["Catalog and Protocol"]
  node_catalog["Candidate catalog"]
  node_purl["PURL preview<br/>[engine.py]"]
end

node_owner(("Owner or script"))

node_owner -->|"uses"| node_python_sdk
node_owner -->|"uses"| node_typescript_sdk
node_python_sdk -->|"calls HTTP"| node_http_api
node_typescript_sdk -->|"calls HTTP"| node_http_api
node_http_api -->|"routes requests"| node_engine
node_http_api -->|"reads candidates"| node_catalog
node_http_api -->|"compiles previews"| node_purl
node_engine -->|"creates and transitions"| node_lifecycle
node_engine -->|"queues missions"| node_mission_queue
node_mission_queue -->|"dispatches missions"| node_capabilities
node_engine -->|"handles observations"| node_listener
node_engine -->|"reads and writes"| node_ledger
node_capabilities -->|"uses for scenes"| node_native_bridge
node_native_bridge -->|"calls ABI"| node_c_api
node_c_api -->|"calls primitives"| node_cpp_kernel
node_cpp_kernel -->|"implements"| node_tower_types

click node_python_sdk "https://github.com/akadaan310/ora/blob/main/sdk/python/ora_client.py"
click node_typescript_sdk "https://github.com/akadaan310/ora/blob/main/sdk/typescript/ora.ts"
click node_http_api "https://github.com/akadaan310/ora/blob/main/service/app.py"
click node_engine "https://github.com/akadaan310/ora/blob/main/service/engine.py"
click node_lifecycle "https://github.com/akadaan310/ora/blob/main/service/engine.py"
click node_mission_queue "https://github.com/akadaan310/ora/blob/main/service/engine.py"
click node_capabilities "https://github.com/akadaan310/ora/blob/main/service/engine.py"
click node_listener "https://github.com/akadaan310/ora/blob/main/service/engine.py"
click node_ledger "https://github.com/akadaan310/ora/blob/main/service/engine.py"
click node_native_bridge "https://github.com/akadaan310/ora/blob/main/service/native.py"
click node_c_api "https://github.com/akadaan310/ora/blob/main/src/c_api.cpp"
click node_cpp_kernel "https://github.com/akadaan310/ora/blob/main/src/tower.cpp"
click node_tower_types "https://github.com/akadaan310/ora/blob/main/include/ora/tower.hpp"
click node_catalog "https://github.com/akadaan310/ora/blob/main/catalog/160_candidates.json"
click node_purl "https://github.com/akadaan310/ora/blob/main/service/engine.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_python_sdk,node_typescript_sdk,node_http_api toneBlue
class node_engine,node_lifecycle,node_mission_queue,node_capabilities,node_listener,node_ledger toneAmber
class node_native_bridge,node_c_api,node_cpp_kernel,node_tower_types toneMint
class node_catalog,node_purl toneRose
class node_owner toneIndigo
```

## Components

### Client and API

- [Python SDK](https://github.com/akadaan310/ora/blob/main/sdk/python/ora_client.py): `sdk/python/ora_client.py`
- [TypeScript SDK](https://github.com/akadaan310/ora/blob/main/sdk/typescript/ora.ts): `sdk/typescript/ora.ts`
- [HTTP service](https://github.com/akadaan310/ora/blob/main/service/app.py): `service/app.py`

### ORA Runtime

- [Engine](https://github.com/akadaan310/ora/blob/main/service/engine.py): `service/engine.py`
- [ORA lifecycle](https://github.com/akadaan310/ora/blob/main/service/engine.py): `service/engine.py`
- [Mission worker](https://github.com/akadaan310/ora/blob/main/service/engine.py): `service/engine.py`
- [Mission capabilities](https://github.com/akadaan310/ora/blob/main/service/engine.py): `service/engine.py`
- [Event listener](https://github.com/akadaan310/ora/blob/main/service/engine.py): `service/engine.py`
- [SQLite event ledger](https://github.com/akadaan310/ora/blob/main/service/engine.py): `service/engine.py`

### Native Kernel

- [Native bridge](https://github.com/akadaan310/ora/blob/main/service/native.py): `service/native.py`
- [C ABI](https://github.com/akadaan310/ora/blob/main/src/c_api.cpp): `src/c_api.cpp`
- [C++ primitives](https://github.com/akadaan310/ora/blob/main/src/tower.cpp): `src/tower.cpp`
- [Kernel interfaces](https://github.com/akadaan310/ora/blob/main/include/ora/tower.hpp): `include/ora/tower.hpp`

### Catalog and Protocol

- [Candidate catalog](https://github.com/akadaan310/ora/blob/main/catalog/160_candidates.json): `catalog/160_candidates.json`
- [PURL preview](https://github.com/akadaan310/ora/blob/main/service/engine.py): `service/engine.py`

### Other components

- **Owner or script**

## Connections

- Owner or script → Python SDK: uses (evidence: `README.md`)
- Owner or script → TypeScript SDK: uses (evidence: `README.md`)
- Python SDK → HTTP service: calls HTTP (evidence: `sdk/python/ora_client.py`)
- TypeScript SDK → HTTP service: calls HTTP (evidence: `sdk/typescript/ora.ts`)
- HTTP service → Engine: routes requests (evidence: `service/app.py`)
- HTTP service → Candidate catalog: reads candidates (evidence: `service/app.py`)
- HTTP service → PURL preview: compiles previews (evidence: `service/app.py`)
- Engine → ORA lifecycle: creates and transitions (evidence: `service/engine.py`)
- Engine → Mission worker: queues missions (evidence: `service/engine.py`)
- Mission worker → Mission capabilities: dispatches missions (evidence: `service/engine.py`)
- Engine → Event listener: handles observations (evidence: `service/app.py`)
- Engine → SQLite event ledger: reads and writes (evidence: `service/engine.py`)
- Mission capabilities → Native bridge: uses for scenes (evidence: `service/engine.py`)
- Native bridge → C ABI: calls ABI (evidence: `service/native.py`)
- C ABI → C++ primitives: calls primitives (evidence: `src/c_api.cpp`)
- C++ primitives → Kernel interfaces: implements (evidence: `src/tower.cpp`)