# czxieddan/ariadnion architecture

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

- Interactive diagram: https://gitdiagram.com/czxieddan/ariadnion
- Repository: https://github.com/czxieddan/ariadnion

## Overview

Ariadnion is a modular Rust service gateway and operations platform: a request enters through optional HTTP interfaces, is routed to a provider, and returns a result. The core supplies module lifecycle, capability, identity, and health contracts; optional crates provide API protocols, routing, provider integrations, accounts, identity, and persistence. The README documents independent assembly and the complete distribution model, but sampled excerpts do not show the bundle wiring or most optional runtime calls. Dashed links indicate those unverified connections.

Main entry points: [`crates/optional/ariadnion-api-http/src/public.rs`](https://github.com/czxieddan/ariadnion/blob/master/crates/optional/ariadnion-api-http/src/public.rs) (HTTP endpoints), [`crates/optional/ariadnion-routing-coordinator/src/engine.rs`](https://github.com/czxieddan/ariadnion/blob/master/crates/optional/ariadnion-routing-coordinator/src/engine.rs) (Routing coordinator), [`crates/ariadnion-core/src/lifecycle.rs`](https://github.com/czxieddan/ariadnion/blob/master/crates/ariadnion-core/src/lifecycle.rs) (Module lifecycle), [`crates/optional/ariadnion-protocol-openai/src/lib.rs`](https://github.com/czxieddan/ariadnion/blob/master/crates/optional/ariadnion-protocol-openai/src/lib.rs) (OpenAI protocol)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Core runtime"]
  node_core["Core contracts<br/>[lib.rs]"]
  node_lifecycle["Module lifecycle<br/>[lifecycle.rs]"]
  node_capabilities["Capability registry<br/>[capability.rs]"]
  node_context["Request context<br/>[context.rs]"]
end

subgraph group_api["API surface"]
  node_http["HTTP endpoints<br/>[public.rs]"]
  node_protocol["OpenAI protocol<br/>[lib.rs]"]
  node_api_domain["API contracts<br/>[lib.rs]"]
  node_stream["Stream bridge<br/>[bridge.rs]"]
end

subgraph group_routing["Routing and providers"]
  node_coordinator["Routing coordinator<br/>[engine.rs]"]
  node_dispatch["Provider dispatch<br/>[dispatch.rs]"]
  node_provider_http["HTTP provider<br/>[connector.rs]"]
end

subgraph group_platform["Platform services"]
  node_accounts["Account services<br/>[lib.rs]"]
  node_auth["Identity and auth<br/>[repository.rs]"]
  node_files["File operations<br/>[pipe.rs]"]
  node_storage[("Embedded storage<br/>[query.rs]")]
end

node_caller(("API caller"))
node_upstream["Model provider"]

node_caller -.->|"sends request"| node_http
node_http -.->|"decodes request"| node_protocol
node_http -.->|"uses contracts"| node_api_domain
node_http -.->|"submits request"| node_coordinator
node_coordinator -.->|"selects provider"| node_dispatch
node_dispatch -.->|"invokes provider"| node_provider_http
node_provider_http -.->|"sends request"| node_upstream
node_coordinator -.->|"evaluates accounts"| node_accounts
node_protocol -.->|"encodes streams"| node_stream
node_lifecycle -->|"validates capabilities"| node_capabilities
node_lifecycle -->|"uses contracts"| node_core
node_http -.->|"uses context"| node_context
node_auth -.->|"persists identity"| node_storage
node_files -.->|"uses storage"| node_storage

click node_http "https://github.com/czxieddan/ariadnion/blob/master/crates/optional/ariadnion-api-http/src/public.rs"
click node_protocol "https://github.com/czxieddan/ariadnion/blob/master/crates/optional/ariadnion-protocol-openai/src/lib.rs"
click node_api_domain "https://github.com/czxieddan/ariadnion/blob/master/crates/optional/ariadnion-api-domain/src/lib.rs"
click node_stream "https://github.com/czxieddan/ariadnion/blob/master/crates/optional/ariadnion-api-stream/src/bridge.rs"
click node_core "https://github.com/czxieddan/ariadnion/blob/master/crates/ariadnion-core/src/lib.rs"
click node_lifecycle "https://github.com/czxieddan/ariadnion/blob/master/crates/ariadnion-core/src/lifecycle.rs"
click node_capabilities "https://github.com/czxieddan/ariadnion/blob/master/crates/ariadnion-core/src/capability.rs"
click node_context "https://github.com/czxieddan/ariadnion/blob/master/crates/ariadnion-core/src/context.rs"
click node_coordinator "https://github.com/czxieddan/ariadnion/blob/master/crates/optional/ariadnion-routing-coordinator/src/engine.rs"
click node_dispatch "https://github.com/czxieddan/ariadnion/blob/master/crates/optional/ariadnion-provider-dispatch/src/dispatch.rs"
click node_provider_http "https://github.com/czxieddan/ariadnion/blob/master/crates/optional/ariadnion-provider-http/src/connector.rs"
click node_accounts "https://github.com/czxieddan/ariadnion/blob/master/crates/optional/ariadnion-account-domain/src/lib.rs"
click node_auth "https://github.com/czxieddan/ariadnion/blob/master/crates/optional/ariadnion-auth-session/src/repository.rs"
click node_files "https://github.com/czxieddan/ariadnion/blob/master/crates/optional/ariadnion-file-service/src/pipe.rs"
click node_storage "https://github.com/czxieddan/ariadnion/blob/master/crates/optional/ariadnion-storage-rnmdb/src/query.rs"

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_core,node_lifecycle,node_capabilities,node_context toneBlue
class node_http,node_protocol,node_api_domain,node_stream toneAmber
class node_coordinator,node_dispatch,node_provider_http,node_caller toneMint
class node_accounts,node_auth,node_files,node_storage toneRose
class node_upstream toneIndigo
```

## Components

### Core runtime

- [Core contracts](https://github.com/czxieddan/ariadnion/blob/master/crates/ariadnion-core/src/lib.rs): `crates/ariadnion-core/src/lib.rs`
- [Module lifecycle](https://github.com/czxieddan/ariadnion/blob/master/crates/ariadnion-core/src/lifecycle.rs): `crates/ariadnion-core/src/lifecycle.rs`
- [Capability registry](https://github.com/czxieddan/ariadnion/blob/master/crates/ariadnion-core/src/capability.rs): `crates/ariadnion-core/src/capability.rs`
- [Request context](https://github.com/czxieddan/ariadnion/blob/master/crates/ariadnion-core/src/context.rs): `crates/ariadnion-core/src/context.rs`

### API surface

- [HTTP endpoints](https://github.com/czxieddan/ariadnion/blob/master/crates/optional/ariadnion-api-http/src/public.rs): `crates/optional/ariadnion-api-http/src/public.rs`
- [OpenAI protocol](https://github.com/czxieddan/ariadnion/blob/master/crates/optional/ariadnion-protocol-openai/src/lib.rs): `crates/optional/ariadnion-protocol-openai/src/lib.rs`
- [API contracts](https://github.com/czxieddan/ariadnion/blob/master/crates/optional/ariadnion-api-domain/src/lib.rs): `crates/optional/ariadnion-api-domain/src/lib.rs`
- [Stream bridge](https://github.com/czxieddan/ariadnion/blob/master/crates/optional/ariadnion-api-stream/src/bridge.rs): `crates/optional/ariadnion-api-stream/src/bridge.rs`

### Routing and providers

- [Routing coordinator](https://github.com/czxieddan/ariadnion/blob/master/crates/optional/ariadnion-routing-coordinator/src/engine.rs): `crates/optional/ariadnion-routing-coordinator/src/engine.rs`
- [Provider dispatch](https://github.com/czxieddan/ariadnion/blob/master/crates/optional/ariadnion-provider-dispatch/src/dispatch.rs): `crates/optional/ariadnion-provider-dispatch/src/dispatch.rs`
- [HTTP provider](https://github.com/czxieddan/ariadnion/blob/master/crates/optional/ariadnion-provider-http/src/connector.rs): `crates/optional/ariadnion-provider-http/src/connector.rs`

### Platform services

- [Account services](https://github.com/czxieddan/ariadnion/blob/master/crates/optional/ariadnion-account-domain/src/lib.rs): `crates/optional/ariadnion-account-domain/src/lib.rs`
- [Identity and auth](https://github.com/czxieddan/ariadnion/blob/master/crates/optional/ariadnion-auth-session/src/repository.rs): `crates/optional/ariadnion-auth-session/src/repository.rs`
- [File operations](https://github.com/czxieddan/ariadnion/blob/master/crates/optional/ariadnion-file-service/src/pipe.rs): `crates/optional/ariadnion-file-service/src/pipe.rs`
- [Embedded storage](https://github.com/czxieddan/ariadnion/blob/master/crates/optional/ariadnion-storage-rnmdb/src/query.rs): `crates/optional/ariadnion-storage-rnmdb/src/query.rs`

### Other components

- **API caller**
- **Model provider**

## Connections

- API caller → HTTP endpoints: sends request
- HTTP endpoints → OpenAI protocol: decodes request
- HTTP endpoints → API contracts: uses contracts
- HTTP endpoints → Routing coordinator: submits request
- Routing coordinator → Provider dispatch: selects provider
- Provider dispatch → HTTP provider: invokes provider
- HTTP provider → Model provider: sends request
- Routing coordinator → Account services: evaluates accounts
- OpenAI protocol → Stream bridge: encodes streams
- Module lifecycle → Capability registry: validates capabilities (evidence: `crates/ariadnion-core/src/lifecycle.rs`)
- Module lifecycle → Core contracts: uses contracts (evidence: `crates/ariadnion-core/src/lifecycle.rs`)
- HTTP endpoints → Request context: uses context
- Identity and auth → Embedded storage: persists identity
- File operations → Embedded storage: uses storage