# ilgsupreme/orin architecture

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

- Interactive diagram: https://gitdiagram.com/ilgsupreme/orin
- Repository: https://github.com/ilgsupreme/orin

## Overview

Orin connects user requests to a persistent Cortex agent workflow: ingress becomes agent work, which may use inference and discovered backends, while goals and observations persist in Memory and results return through polling or the terminal client. Separate services provide model execution, Kubernetes discovery and administration, and signed Federation work exchange. Common protocols and job management form an internal runtime layer. Several links reflect README-described behavior because the corresponding implementation was not sampled; unsampled deployment and Federation details are represented conservatively.

Main entry points: [`src/cortex/app.py`](https://github.com/ilgsupreme/orin/blob/main/src/cortex/app.py) (Cortex API), [`src/cortex/cortex/agent.py`](https://github.com/ilgsupreme/orin/blob/main/src/cortex/cortex/agent.py) (Agent runtime), [`src/llm/app.py`](https://github.com/ilgsupreme/orin/blob/main/src/llm/app.py) (LLM service), [`src/federation/app.py`](https://github.com/ilgsupreme/orin/blob/main/src/federation/app.py) (Federation API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cortex["Cortex assistant"]
  node_cortex_api["Cortex API<br/>[app.py]"]
  node_agent["Agent runtime<br/>[agent.py]"]
  node_agent_support["Goals and memory<br/>[goal_store.py]"]
  node_actions["Agent actions<br/>[actions.py]"]
  node_cli["Admin commands<br/>[command_router.py]"]
end

subgraph group_runtime["Inference and runtime"]
  node_inference["Inference routing<br/>[inference.py]"]
  node_router["Backend router<br/>[service.py]"]
  node_primer["Primer model runtime<br/>[primer.py]"]
  node_llm_api["LLM service<br/>[app.py]"]
  node_llm_runtime["LLM execution<br/>[runtime.py]"]
  node_common_protocol["Work protocols<br/>[routing_types.py]"]
  node_jobs["Job manager<br/>[jobs.py]"]
end

subgraph group_cluster["Cluster services"]
  node_discovery["Backend discovery<br/>[services.py]"]
  node_backend_client["Backend client<br/>[client.py]"]
  node_deployment["Kubernetes deployment<br/>[service.py]"]
end

subgraph group_memory["Memory persistence"]
  node_memory_api["Memory service<br/>[app.py]"]
  node_memory_runtime["Memory runtime<br/>[runtime.py]"]
  node_memory_sql[("SQL persistence<br/>[sql.py]")]
end

subgraph group_federation["Federation"]
  node_federation_api["Federation API<br/>[app.py]"]
  node_federation_bridge["Cortex bridge<br/>[cortex_bridge.py]"]
  node_federation_security["Federation identity and policy<br/>[identity.py]"]
  node_federation_storage["Federation storage<br/>[storage.py]"]
end

node_user(("User"))
node_terminal["Terminal client<br/>[terminal-chat.py]"]
node_peer(("Federation peer"))
node_kubernetes["Kubernetes cluster"]

node_user -->|"submits requests"| node_terminal
node_terminal -->|"sends chat"| node_cortex_api
node_user -->|"submits chat"| node_cortex_api
node_cortex_api -->|"dispatches turns"| node_agent
node_agent -->|"requests inference"| node_inference
node_agent -->|"persists goals"| node_agent_support
node_agent -->|"runs actions"| node_actions
node_agent -.->|"submits backend work"| node_router
node_terminal -->|"polls goals"| node_cortex_api
node_cortex_api -->|"routes commands"| node_cli
node_cli -->|"administers cluster"| node_deployment
node_deployment -->|"manages workloads"| node_kubernetes
node_inference -->|"runs local inference"| node_primer
node_inference -.->|"selects backend work"| node_router
node_router -->|"selects backends"| node_discovery
node_router -->|"submits work"| node_backend_client
node_backend_client -->|"sends work packets"| node_llm_api
node_llm_api -->|"dispatches work"| node_llm_runtime
node_llm_runtime -->|"generates output"| node_primer
node_cortex_api -->|"accepts work packets"| node_common_protocol
node_llm_api -->|"accepts work packets"| node_common_protocol
node_llm_api -->|"starts jobs"| node_jobs
node_memory_api -->|"dispatches requests"| node_memory_runtime
node_memory_runtime -->|"reads and writes"| node_memory_sql
node_agent_support -.->|"persists state"| node_memory_api
node_federation_api -->|"submits accepted work"| node_federation_bridge
node_federation_api -->|"checks signatures"| node_federation_security
node_federation_api -->|"stores records"| node_federation_storage
node_federation_bridge -->|"submits work"| node_cortex_api
node_federation_storage -->|"stores federation records"| node_memory_api
node_peer -->|"exchanges work"| node_federation_api

click node_terminal "https://github.com/ilgsupreme/orin/blob/main/terminal-chat.py"
click node_cortex_api "https://github.com/ilgsupreme/orin/blob/main/src/cortex/app.py"
click node_agent "https://github.com/ilgsupreme/orin/blob/main/src/cortex/cortex/agent.py"
click node_agent_support "https://github.com/ilgsupreme/orin/blob/main/src/cortex/cortex/goal_store.py"
click node_actions "https://github.com/ilgsupreme/orin/blob/main/src/cortex/cortex/actions.py"
click node_cli "https://github.com/ilgsupreme/orin/blob/main/src/cortex/cli/command_router.py"
click node_inference "https://github.com/ilgsupreme/orin/blob/main/src/cortex/cortex/inference.py"
click node_router "https://github.com/ilgsupreme/orin/blob/main/src/cortex/router/service.py"
click node_discovery "https://github.com/ilgsupreme/orin/blob/main/src/cortex/cluster/discovery/services.py"
click node_backend_client "https://github.com/ilgsupreme/orin/blob/main/src/cortex/cluster/discovery/client.py"
click node_primer "https://github.com/ilgsupreme/orin/blob/main/src/common/primer.py"
click node_llm_api "https://github.com/ilgsupreme/orin/blob/main/src/llm/app.py"
click node_llm_runtime "https://github.com/ilgsupreme/orin/blob/main/src/llm/runtime.py"
click node_common_protocol "https://github.com/ilgsupreme/orin/blob/main/src/common/protocol/routing_types.py"
click node_jobs "https://github.com/ilgsupreme/orin/blob/main/src/common/jobs.py"
click node_deployment "https://github.com/ilgsupreme/orin/blob/main/src/cortex/cluster/deployment/service.py"
click node_memory_api "https://github.com/ilgsupreme/orin/blob/main/src/memory/app.py"
click node_memory_runtime "https://github.com/ilgsupreme/orin/blob/main/src/memory/runtime.py"
click node_memory_sql "https://github.com/ilgsupreme/orin/blob/main/src/memory/sql.py"
click node_federation_api "https://github.com/ilgsupreme/orin/blob/main/src/federation/app.py"
click node_federation_bridge "https://github.com/ilgsupreme/orin/blob/main/src/federation/cortex_bridge.py"
click node_federation_security "https://github.com/ilgsupreme/orin/blob/main/src/federation/identity.py"
click node_federation_storage "https://github.com/ilgsupreme/orin/blob/main/src/federation/storage.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_cortex_api,node_agent,node_agent_support,node_actions,node_cli,node_user,node_terminal toneBlue
class node_inference,node_router,node_primer,node_llm_api,node_llm_runtime,node_common_protocol,node_jobs toneAmber
class node_discovery,node_backend_client,node_deployment toneMint
class node_memory_api,node_memory_runtime,node_memory_sql toneRose
class node_federation_api,node_federation_bridge,node_federation_security,node_federation_storage,node_peer,node_kubernetes toneIndigo
```

## Components

### Cortex assistant

- [Cortex API](https://github.com/ilgsupreme/orin/blob/main/src/cortex/app.py): `src/cortex/app.py`
- [Agent runtime](https://github.com/ilgsupreme/orin/blob/main/src/cortex/cortex/agent.py): `src/cortex/cortex/agent.py`
- [Goals and memory](https://github.com/ilgsupreme/orin/blob/main/src/cortex/cortex/goal_store.py): `src/cortex/cortex/goal_store.py`
- [Agent actions](https://github.com/ilgsupreme/orin/blob/main/src/cortex/cortex/actions.py): `src/cortex/cortex/actions.py`
- [Admin commands](https://github.com/ilgsupreme/orin/blob/main/src/cortex/cli/command_router.py): `src/cortex/cli/command_router.py`

### Inference and runtime

- [Inference routing](https://github.com/ilgsupreme/orin/blob/main/src/cortex/cortex/inference.py): `src/cortex/cortex/inference.py`
- [Backend router](https://github.com/ilgsupreme/orin/blob/main/src/cortex/router/service.py): `src/cortex/router/service.py`
- [Primer model runtime](https://github.com/ilgsupreme/orin/blob/main/src/common/primer.py): `src/common/primer.py`
- [LLM service](https://github.com/ilgsupreme/orin/blob/main/src/llm/app.py): `src/llm/app.py`
- [LLM execution](https://github.com/ilgsupreme/orin/blob/main/src/llm/runtime.py): `src/llm/runtime.py`
- [Work protocols](https://github.com/ilgsupreme/orin/blob/main/src/common/protocol/routing_types.py): `src/common/protocol/routing_types.py`
- [Job manager](https://github.com/ilgsupreme/orin/blob/main/src/common/jobs.py): `src/common/jobs.py`

### Cluster services

- [Backend discovery](https://github.com/ilgsupreme/orin/blob/main/src/cortex/cluster/discovery/services.py): `src/cortex/cluster/discovery/services.py`
- [Backend client](https://github.com/ilgsupreme/orin/blob/main/src/cortex/cluster/discovery/client.py): `src/cortex/cluster/discovery/client.py`
- [Kubernetes deployment](https://github.com/ilgsupreme/orin/blob/main/src/cortex/cluster/deployment/service.py): `src/cortex/cluster/deployment/service.py`

### Memory persistence

- [Memory service](https://github.com/ilgsupreme/orin/blob/main/src/memory/app.py): `src/memory/app.py`
- [Memory runtime](https://github.com/ilgsupreme/orin/blob/main/src/memory/runtime.py): `src/memory/runtime.py`
- [SQL persistence](https://github.com/ilgsupreme/orin/blob/main/src/memory/sql.py): `src/memory/sql.py`

### Federation

- [Federation API](https://github.com/ilgsupreme/orin/blob/main/src/federation/app.py): `src/federation/app.py`
- [Cortex bridge](https://github.com/ilgsupreme/orin/blob/main/src/federation/cortex_bridge.py): `src/federation/cortex_bridge.py`
- [Federation identity and policy](https://github.com/ilgsupreme/orin/blob/main/src/federation/identity.py): `src/federation/identity.py`
- [Federation storage](https://github.com/ilgsupreme/orin/blob/main/src/federation/storage.py): `src/federation/storage.py`

### Other components

- **User**
- [Terminal client](https://github.com/ilgsupreme/orin/blob/main/terminal-chat.py): `terminal-chat.py`
- **Federation peer**
- **Kubernetes cluster**

## Connections

- User → Terminal client: submits requests (evidence: `README.md`)
- Terminal client → Cortex API: sends chat (evidence: `README.md`)
- User → Cortex API: submits chat (evidence: `README.md`)
- Cortex API → Agent runtime: dispatches turns (evidence: `src/cortex/app.py`)
- Agent runtime → Inference routing: requests inference (evidence: `README.md`)
- Agent runtime → Goals and memory: persists goals (evidence: `README.md`)
- Agent runtime → Agent actions: runs actions (evidence: `README.md`)
- Agent runtime → Backend router: submits backend work
- Terminal client → Cortex API: polls goals (evidence: `README.md`)
- Cortex API → Admin commands: routes commands (evidence: `src/cortex/app.py`)
- Admin commands → Kubernetes deployment: administers cluster (evidence: `src/cortex/cli/command_router.py`)
- Kubernetes deployment → Kubernetes cluster: manages workloads (evidence: `src/cortex/cluster/deployment/service.py`)
- Inference routing → Primer model runtime: runs local inference (evidence: `README.md`)
- Inference routing → Backend router: selects backend work
- Backend router → Backend discovery: selects backends (evidence: `src/cortex/router/service.py`)
- Backend router → Backend client: submits work (evidence: `src/cortex/router/service.py`)
- Backend client → LLM service: sends work packets (evidence: `README.md`)
- LLM service → LLM execution: dispatches work (evidence: `src/llm/app.py`)
- LLM execution → Primer model runtime: generates output (evidence: `src/llm/runtime.py`)
- Cortex API → Work protocols: accepts work packets (evidence: `src/cortex/app.py`)
- LLM service → Work protocols: accepts work packets (evidence: `src/llm/app.py`)
- LLM service → Job manager: starts jobs (evidence: `src/llm/app.py`)
- Memory service → Memory runtime: dispatches requests (evidence: `src/memory/app.py`)
- Memory runtime → SQL persistence: reads and writes (evidence: `src/memory/runtime.py`)
- Goals and memory → Memory service: persists state
- Federation API → Cortex bridge: submits accepted work (evidence: `src/federation/app.py`)
- Federation API → Federation identity and policy: checks signatures (evidence: `src/federation/app.py`)
- Federation API → Federation storage: stores records (evidence: `src/federation/app.py`)
- Cortex bridge → Cortex API: submits work (evidence: `README.md`)
- Federation storage → Memory service: stores federation records (evidence: `src/federation/storage.py`)
- Federation peer → Federation API: exchanges work (evidence: `README.md`)