# capsize-games/airunner architecture

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

- Interactive diagram: https://gitdiagram.com/capsize-games/airunner
- Repository: https://github.com/capsize-games/airunner

## Overview

AI Runner is a local-first desktop companion and AI-art workspace backed by a headless service daemon. The primary flow is user conversation through the GUI and daemon to the LLM runtime, with streamed responses returned to the client; companion memory, RAG, and voice are adjacent stages. A separate canvas workflow covers image generation and editing. The README documents additional capabilities such as safety, environmental awareness, and model downloads. Those branches are represented at directory level where source was not sampled; edges are limited to documented package links and sampled calls.

Main entry points: [`src/airunner`](https://github.com/capsize-games/airunner/tree/master/src/airunner) (Desktop GUI), [`services/src/airunner_services/api/server.py`](https://github.com/capsize-games/airunner/blob/master/services/src/airunner_services/api/server.py) (HTTP API), [`src/airunner/components/llm/api/llm_services.py`](https://github.com/capsize-games/airunner/blob/master/src/airunner/components/llm/api/llm_services.py) (LLM client), [`services/src/airunner_services/api/routes/llm_stream_routes.py`](https://github.com/capsize-games/airunner/blob/master/services/src/airunner_services/api/routes/llm_stream_routes.py) (LLM streaming)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Desktop client"]
  node_gui["Desktop GUI"]
  node_gui_llm["LLM client<br/>[llm_services.py]"]
  node_document_route["Document routing"]
  node_daemon_client["Daemon client"]
end

subgraph group_service["Daemon and API"]
  node_api_server["HTTP API<br/>[server.py]"]
  node_stream_route["LLM streaming"]
  node_model_route["Model controls"]
  node_runtime["LLM runtime boundary<br/>[llm_runtime.py]"]
  node_worker["Generation worker"]
  node_art_api["Art API<br/>[art.py]"]
end

subgraph group_models["AI capabilities"]
  node_llm_manager["LLM model manager"]
  node_companion["Companion agents"]
  node_voice["Speech services<br/>[tts_services.py]"]
  node_art_engine["Image generation"]
  node_safety["Safety filters"]
  node_downloads["Model downloads"]
  node_weather["Local weather<br/>[geolocation.py]"]
end

subgraph group_state["Local state"]
  node_history["Conversation history"]
  node_database[("Local database")]
end

node_user(("User"))
node_external_weather(("Weather provider"))
node_external_models(("Model sources"))

node_user -->|"interacts"| node_gui
node_gui -->|"submits chat"| node_gui_llm
node_gui_llm -->|"forwards requests"| node_daemon_client
node_daemon_client -->|"calls daemon"| node_api_server
node_api_server -->|"dispatches stream"| node_stream_route
node_stream_route -->|"resolves client"| node_runtime
node_stream_route -->|"streams request"| node_runtime
node_api_server -->|"dispatches model"| node_model_route
node_model_route -->|"runs actions"| node_runtime
node_worker -->|"handles request"| node_llm_manager
node_gui_llm -->|"emits response"| node_gui
node_document_route -->|"routes prompt"| node_gui_llm
node_gui -->|"requests art"| node_art_api
node_art_api -->|"generates image"| node_art_engine
node_worker -->|"loads history"| node_history
node_history -->|"reads and writes"| node_database
node_model_route -->|"persists selection"| node_database
node_gui -->|"uses speech"| node_voice
node_api_server -.->|"applies filtering"| node_safety
node_downloads -.->|"downloads models"| node_external_models
node_weather -.->|"queries weather"| node_external_weather

click node_gui "https://github.com/capsize-games/airunner/tree/master/src/airunner"
click node_gui_llm "https://github.com/capsize-games/airunner/blob/master/src/airunner/components/llm/api/llm_services.py"
click node_document_route "https://github.com/capsize-games/airunner/blob/master/src/airunner/components/llm/utils/document_query_routing.py"
click node_daemon_client "https://github.com/capsize-games/airunner/blob/master/services/src/airunner_services/daemon_client/gui_daemon_client.py"
click node_api_server "https://github.com/capsize-games/airunner/blob/master/services/src/airunner_services/api/server.py"
click node_stream_route "https://github.com/capsize-games/airunner/blob/master/services/src/airunner_services/api/routes/llm_stream_routes.py"
click node_model_route "https://github.com/capsize-games/airunner/blob/master/services/src/airunner_services/api/routes/llm_model_routes.py"
click node_runtime "https://github.com/capsize-games/airunner/blob/master/services/src/airunner_services/api/routes/llm_runtime.py"
click node_worker "https://github.com/capsize-games/airunner/blob/master/services/src/airunner_services/workers/llm_generate_worker.py"
click node_llm_manager "https://github.com/capsize-games/airunner/blob/master/services/src/airunner_services/model_management/llm_model_manager.py"
click node_companion "https://github.com/capsize-games/airunner/tree/master/services/src/airunner_services/agents"
click node_voice "https://github.com/capsize-games/airunner/blob/master/services/src/airunner_services/api/services/tts_services.py"
click node_art_api "https://github.com/capsize-games/airunner/blob/master/services/src/airunner_services/api/routes/art.py"
click node_art_engine "https://github.com/capsize-games/airunner/blob/master/services/src/airunner_services/art/managers/stablediffusion/image_generation.py"
click node_safety "https://github.com/capsize-games/airunner/tree/master/services/src/airunner_services/content_safety"
click node_downloads "https://github.com/capsize-games/airunner/tree/master/services/src/airunner_services/bin"
click node_history "https://github.com/capsize-games/airunner/blob/master/services/src/airunner_services/conversations/conversation_history_manager.py"
click node_database "https://github.com/capsize-games/airunner/tree/master/services/src/airunner_services/database"
click node_weather "https://github.com/capsize-games/airunner/blob/master/services/src/airunner_services/api/routes/geolocation.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_gui,node_gui_llm,node_document_route,node_daemon_client,node_user toneBlue
class node_api_server,node_stream_route,node_model_route,node_runtime,node_worker,node_art_api toneAmber
class node_llm_manager,node_companion,node_voice,node_art_engine,node_safety,node_downloads,node_weather toneMint
class node_history,node_database toneRose
class node_external_weather,node_external_models toneIndigo
```

## Components

### Desktop client

- [Desktop GUI](https://github.com/capsize-games/airunner/tree/master/src/airunner): `src/airunner`
- [LLM client](https://github.com/capsize-games/airunner/blob/master/src/airunner/components/llm/api/llm_services.py): `src/airunner/components/llm/api/llm_services.py`
- [Document routing](https://github.com/capsize-games/airunner/blob/master/src/airunner/components/llm/utils/document_query_routing.py): `src/airunner/components/llm/utils/document_query_routing.py`
- [Daemon client](https://github.com/capsize-games/airunner/blob/master/services/src/airunner_services/daemon_client/gui_daemon_client.py): `services/src/airunner_services/daemon_client/gui_daemon_client.py`

### Daemon and API

- [HTTP API](https://github.com/capsize-games/airunner/blob/master/services/src/airunner_services/api/server.py): `services/src/airunner_services/api/server.py`
- [LLM streaming](https://github.com/capsize-games/airunner/blob/master/services/src/airunner_services/api/routes/llm_stream_routes.py): `services/src/airunner_services/api/routes/llm_stream_routes.py`
- [Model controls](https://github.com/capsize-games/airunner/blob/master/services/src/airunner_services/api/routes/llm_model_routes.py): `services/src/airunner_services/api/routes/llm_model_routes.py`
- [LLM runtime boundary](https://github.com/capsize-games/airunner/blob/master/services/src/airunner_services/api/routes/llm_runtime.py): `services/src/airunner_services/api/routes/llm_runtime.py`
- [Generation worker](https://github.com/capsize-games/airunner/blob/master/services/src/airunner_services/workers/llm_generate_worker.py): `services/src/airunner_services/workers/llm_generate_worker.py`
- [Art API](https://github.com/capsize-games/airunner/blob/master/services/src/airunner_services/api/routes/art.py): `services/src/airunner_services/api/routes/art.py`

### AI capabilities

- [LLM model manager](https://github.com/capsize-games/airunner/blob/master/services/src/airunner_services/model_management/llm_model_manager.py): `services/src/airunner_services/model_management/llm_model_manager.py`
- [Companion agents](https://github.com/capsize-games/airunner/tree/master/services/src/airunner_services/agents): `services/src/airunner_services/agents`
- [Speech services](https://github.com/capsize-games/airunner/blob/master/services/src/airunner_services/api/services/tts_services.py): `services/src/airunner_services/api/services/tts_services.py`
- [Image generation](https://github.com/capsize-games/airunner/blob/master/services/src/airunner_services/art/managers/stablediffusion/image_generation.py): `services/src/airunner_services/art/managers/stablediffusion/image_generation.py`
- [Safety filters](https://github.com/capsize-games/airunner/tree/master/services/src/airunner_services/content_safety): `services/src/airunner_services/content_safety`
- [Model downloads](https://github.com/capsize-games/airunner/tree/master/services/src/airunner_services/bin): `services/src/airunner_services/bin`
- [Local weather](https://github.com/capsize-games/airunner/blob/master/services/src/airunner_services/api/routes/geolocation.py): `services/src/airunner_services/api/routes/geolocation.py`

### Local state

- [Conversation history](https://github.com/capsize-games/airunner/blob/master/services/src/airunner_services/conversations/conversation_history_manager.py): `services/src/airunner_services/conversations/conversation_history_manager.py`
- [Local database](https://github.com/capsize-games/airunner/tree/master/services/src/airunner_services/database): `services/src/airunner_services/database`

### Other components

- **User**
- **Weather provider**
- **Model sources**

## Connections

- User → Desktop GUI: interacts
- Desktop GUI → LLM client: submits chat
- LLM client → Daemon client: forwards requests
- Daemon client → HTTP API: calls daemon
- HTTP API → LLM streaming: dispatches stream
- LLM streaming → LLM runtime boundary: resolves client
- LLM streaming → LLM runtime boundary: streams request
- HTTP API → Model controls: dispatches model
- Model controls → LLM runtime boundary: runs actions
- Generation worker → LLM model manager: handles request
- LLM client → Desktop GUI: emits response
- Document routing → LLM client: routes prompt
- Desktop GUI → Art API: requests art
- Art API → Image generation: generates image
- Generation worker → Conversation history: loads history
- Conversation history → Local database: reads and writes
- Model controls → Local database: persists selection
- Desktop GUI → Speech services: uses speech
- HTTP API → Safety filters: applies filtering
- Model downloads → Model sources: downloads models
- Local weather → Weather provider: queries weather
