# haidra-org/ai-horde architecture

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

## Overview

AI Horde is a community-powered REST service that brokers image and text generation across volunteer workers. A client submits a request; API handling validates it, accounts for user priority and kudos, and queues work for compatible workers. Workers check in, advertise capabilities, and claim jobs; generation results return through the request lifecycle. The tree and README establish the product’s image/text, worker, and kudos domains. Some internal dispatch details are unsampled, so the graph omits uncertain links rather than inferring a complete pipeline.

Main entry points: [`horde/apis/v2/base.py`](https://github.com/haidra-org/ai-horde/blob/main/horde/apis/v2/base.py) (Shared API), [`horde/flask.py`](https://github.com/haidra-org/ai-horde/blob/main/horde/flask.py) (Flask application), [`horde/apis/v2/stable.py`](https://github.com/haidra-org/ai-horde/blob/main/horde/apis/v2/stable.py) (Image API), [`horde/database/kudos_reservations.py`](https://github.com/haidra-org/ai-horde/blob/main/horde/database/kudos_reservations.py) (Kudos reservations)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["API and service"]
  node_app["Flask application<br/>[flask.py]"]
  node_api_base["Shared API<br/>[base.py]"]
  node_api_stable["Image API<br/>[stable.py]"]
  node_api_text["Text API<br/>[kobold.py]"]
  node_request_models["Request models<br/>[v2.py]"]
  node_image_models["Image request models<br/>[stable_v2.py]"]
end

subgraph group_jobs["Generation and workers"]
  node_image_queue["Image queue<br/>[waiting_prompt.py]"]
  node_text_queue["Text queue<br/>[waiting_prompt.py]"]
  node_interrogation["Image interrogation<br/>[interrogation.py]"]
  node_image_worker["Image workers<br/>[worker.py]"]
  node_text_worker["Text workers<br/>[worker.py]"]
  node_interrogation_worker["Interrogation workers"]
  node_scheduler["Request scheduling"]
end

subgraph group_accounts["Users and kudos"]
  node_user[("User accounts<br/>[user.py]")]
  node_kudos[("Kudos ledger<br/>[kudos.py]")]
  node_reservations[("Kudos reservations")]
end

subgraph group_platform["State and operations"]
  node_db_functions[("Domain persistence<br/>[functions.py]")]
  node_db_threads["Background processing<br/>[threads.py]"]
  node_redis[("Redis coordination<br/>[horde_redis.py]")]
  node_model_reference["Model reference<br/>[model_reference.py]"]
  node_metrics["Metrics and telemetry<br/>[metrics.py]"]
end

node_client(("API client"))

node_client -->|"sends requests"| node_app
node_app -->|"registers API"| node_api_base
node_app -->|"starts workers"| node_db_threads
node_api_base -->|"validates with"| node_request_models
node_api_stable -->|"uses shared API"| node_api_base
node_api_text -.->|"uses shared API"| node_api_base
node_api_stable -->|"parses with"| node_image_models
node_api_stable -->|"uses queue"| node_image_queue
node_api_text -.->|"uses queue"| node_text_queue
node_api_base -->|"handles accounts"| node_user
node_api_base -->|"calls persistence"| node_db_functions
node_api_stable -->|"reserves kudos"| node_reservations
node_image_queue -.->|"scheduling support"| node_scheduler
node_image_worker -.->|"claims compatible work"| node_image_queue
node_text_worker -.->|"claims compatible work"| node_text_queue
node_interrogation_worker -.->|"processes tasks"| node_interrogation
node_image_worker -->|"validates models"| node_model_reference
node_text_worker -->|"checks model reference"| node_model_reference
node_image_worker -.->|"persists worker state"| node_db_functions
node_text_worker -.->|"persists worker state"| node_db_functions
node_interrogation_worker -->|"uses reservations"| node_reservations
node_user -->|"records movements"| node_kudos
node_kudos -->|"checks reserved balance"| node_reservations
node_db_threads -->|"calls persistence"| node_db_functions
node_db_threads -->|"uses reservations"| node_reservations
node_app -->|"connects Redis"| node_redis
node_app -->|"initializes metrics"| node_metrics
node_scheduler -->|"records scheduling"| node_metrics

click node_app "https://github.com/haidra-org/ai-horde/blob/main/horde/flask.py"
click node_api_base "https://github.com/haidra-org/ai-horde/blob/main/horde/apis/v2/base.py"
click node_api_stable "https://github.com/haidra-org/ai-horde/blob/main/horde/apis/v2/stable.py"
click node_api_text "https://github.com/haidra-org/ai-horde/blob/main/horde/apis/v2/kobold.py"
click node_request_models "https://github.com/haidra-org/ai-horde/blob/main/horde/apis/models/v2.py"
click node_image_models "https://github.com/haidra-org/ai-horde/blob/main/horde/apis/models/stable_v2.py"
click node_image_queue "https://github.com/haidra-org/ai-horde/blob/main/horde/classes/stable/waiting_prompt.py"
click node_text_queue "https://github.com/haidra-org/ai-horde/blob/main/horde/classes/kobold/waiting_prompt.py"
click node_interrogation "https://github.com/haidra-org/ai-horde/blob/main/horde/classes/stable/interrogation.py"
click node_image_worker "https://github.com/haidra-org/ai-horde/blob/main/horde/classes/stable/worker.py"
click node_text_worker "https://github.com/haidra-org/ai-horde/blob/main/horde/classes/kobold/worker.py"
click node_interrogation_worker "https://github.com/haidra-org/ai-horde/blob/main/horde/classes/stable/interrogation_worker.py"
click node_scheduler "https://github.com/haidra-org/ai-horde/blob/main/horde/request_scheduling.py"
click node_user "https://github.com/haidra-org/ai-horde/blob/main/horde/classes/base/user.py"
click node_kudos "https://github.com/haidra-org/ai-horde/blob/main/horde/classes/base/kudos.py"
click node_reservations "https://github.com/haidra-org/ai-horde/blob/main/horde/database/kudos_reservations.py"
click node_db_functions "https://github.com/haidra-org/ai-horde/blob/main/horde/database/functions.py"
click node_db_threads "https://github.com/haidra-org/ai-horde/blob/main/horde/database/threads.py"
click node_redis "https://github.com/haidra-org/ai-horde/blob/main/horde/horde_redis.py"
click node_model_reference "https://github.com/haidra-org/ai-horde/blob/main/horde/model_reference.py"
click node_metrics "https://github.com/haidra-org/ai-horde/blob/main/horde/metrics.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_app,node_api_base,node_api_stable,node_api_text,node_request_models,node_image_models,node_client toneBlue
class node_image_queue,node_text_queue,node_interrogation,node_image_worker,node_text_worker,node_interrogation_worker,node_scheduler toneAmber
class node_user,node_kudos,node_reservations toneMint
class node_db_functions,node_db_threads,node_redis,node_model_reference,node_metrics toneRose
```

## Components

### API and service

- [Flask application](https://github.com/haidra-org/ai-horde/blob/main/horde/flask.py): `horde/flask.py`
- [Shared API](https://github.com/haidra-org/ai-horde/blob/main/horde/apis/v2/base.py): `horde/apis/v2/base.py`
- [Image API](https://github.com/haidra-org/ai-horde/blob/main/horde/apis/v2/stable.py): `horde/apis/v2/stable.py`
- [Text API](https://github.com/haidra-org/ai-horde/blob/main/horde/apis/v2/kobold.py): `horde/apis/v2/kobold.py`
- [Request models](https://github.com/haidra-org/ai-horde/blob/main/horde/apis/models/v2.py): `horde/apis/models/v2.py`
- [Image request models](https://github.com/haidra-org/ai-horde/blob/main/horde/apis/models/stable_v2.py): `horde/apis/models/stable_v2.py`

### Generation and workers

- [Image queue](https://github.com/haidra-org/ai-horde/blob/main/horde/classes/stable/waiting_prompt.py): `horde/classes/stable/waiting_prompt.py`
- [Text queue](https://github.com/haidra-org/ai-horde/blob/main/horde/classes/kobold/waiting_prompt.py): `horde/classes/kobold/waiting_prompt.py`
- [Image interrogation](https://github.com/haidra-org/ai-horde/blob/main/horde/classes/stable/interrogation.py): `horde/classes/stable/interrogation.py`
- [Image workers](https://github.com/haidra-org/ai-horde/blob/main/horde/classes/stable/worker.py): `horde/classes/stable/worker.py`
- [Text workers](https://github.com/haidra-org/ai-horde/blob/main/horde/classes/kobold/worker.py): `horde/classes/kobold/worker.py`
- [Interrogation workers](https://github.com/haidra-org/ai-horde/blob/main/horde/classes/stable/interrogation_worker.py): `horde/classes/stable/interrogation_worker.py`
- [Request scheduling](https://github.com/haidra-org/ai-horde/blob/main/horde/request_scheduling.py): `horde/request_scheduling.py`

### Users and kudos

- [User accounts](https://github.com/haidra-org/ai-horde/blob/main/horde/classes/base/user.py): `horde/classes/base/user.py`
- [Kudos ledger](https://github.com/haidra-org/ai-horde/blob/main/horde/classes/base/kudos.py): `horde/classes/base/kudos.py`
- [Kudos reservations](https://github.com/haidra-org/ai-horde/blob/main/horde/database/kudos_reservations.py): `horde/database/kudos_reservations.py`

### State and operations

- [Domain persistence](https://github.com/haidra-org/ai-horde/blob/main/horde/database/functions.py): `horde/database/functions.py`
- [Background processing](https://github.com/haidra-org/ai-horde/blob/main/horde/database/threads.py): `horde/database/threads.py`
- [Redis coordination](https://github.com/haidra-org/ai-horde/blob/main/horde/horde_redis.py): `horde/horde_redis.py`
- [Model reference](https://github.com/haidra-org/ai-horde/blob/main/horde/model_reference.py): `horde/model_reference.py`
- [Metrics and telemetry](https://github.com/haidra-org/ai-horde/blob/main/horde/metrics.py): `horde/metrics.py`

### Other components

- **API client**

## Connections

- API client → Flask application: sends requests (evidence: `README.md`)
- Flask application → Shared API: registers API (evidence: `horde/flask.py`)
- Flask application → Background processing: starts workers (evidence: `horde/flask.py`)
- Shared API → Request models: validates with (evidence: `horde/apis/v2/base.py`)
- Image API → Shared API: uses shared API (evidence: `horde/apis/v2/stable.py`)
- Text API → Shared API: uses shared API
- Image API → Image request models: parses with (evidence: `horde/apis/v2/stable.py`)
- Image API → Image queue: uses queue (evidence: `horde/apis/v2/stable.py`)
- Text API → Text queue: uses queue
- Shared API → User accounts: handles accounts (evidence: `horde/apis/v2/base.py`)
- Shared API → Domain persistence: calls persistence (evidence: `horde/apis/v2/base.py`)
- Image API → Kudos reservations: reserves kudos (evidence: `horde/apis/v2/stable.py`)
- Image queue → Request scheduling: scheduling support
- Image workers → Image queue: claims compatible work
- Text workers → Text queue: claims compatible work
- Interrogation workers → Image interrogation: processes tasks (evidence: `horde/classes/stable/interrogation.py`)
- Image workers → Model reference: validates models (evidence: `horde/classes/stable/worker.py`)
- Text workers → Model reference: checks model reference (evidence: `horde/classes/kobold/worker.py`)
- Image workers → Domain persistence: persists worker state (evidence: `horde/database/functions.py`)
- Text workers → Domain persistence: persists worker state (evidence: `horde/database/functions.py`)
- Interrogation workers → Kudos reservations: uses reservations (evidence: `horde/classes/stable/interrogation_worker.py`)
- User accounts → Kudos ledger: records movements (evidence: `horde/classes/base/user.py`)
- Kudos ledger → Kudos reservations: checks reserved balance (evidence: `horde/database/kudos_reservations.py`)
- Background processing → Domain persistence: calls persistence (evidence: `horde/database/threads.py`)
- Background processing → Kudos reservations: uses reservations (evidence: `horde/database/threads.py`)
- Flask application → Redis coordination: connects Redis (evidence: `horde/flask.py`)
- Flask application → Metrics and telemetry: initializes metrics (evidence: `horde/flask.py`)
- Request scheduling → Metrics and telemetry: records scheduling (evidence: `horde/request_scheduling.py`)