# mateocabanal/logan architecture

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

- Interactive diagram: https://gitdiagram.com/mateocabanal/logan
- Repository: https://github.com/mateocabanal/logan

## Overview

Logan is a local-LLM compiler and inference runtime, with `logand` providing a persistent service interface. The main workflow is model selection or checkpoint input, optional hardware-aware compilation, loading into a model-specific runtime, then token generation returned through an API or chat client. Separate model paths serve sparse Qwen and dense Llama/MiniCPM workloads; shared runtime foundations cover storage, scheduling, state, and caching, while Metal provides Apple acceleration. The README documents additional format, model, and RouteScout capabilities. Some subsystem links rely on README descriptions because their implementation was not sampled.

Main entry points: [`logan-qwen4/src/lib.rs`](https://github.com/mateocabanal/logan/blob/main/logan-qwen4/src/lib.rs) (Qwen sparse runtime), [`logand/src/main.rs`](https://github.com/mateocabanal/logan/blob/main/logand/src/main.rs) (Inference daemon), [`logan-compiler/src/pipeline.rs`](https://github.com/mateocabanal/logan/blob/main/logan-compiler/src/pipeline.rs) (Model compiler), [`logan-llama/src/lib.rs`](https://github.com/mateocabanal/logan/blob/main/logan-llama/src/lib.rs) (Llama dense runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_service["Service and clients"]
  node_logand["Inference daemon<br/>[main.rs]"]
  node_chat["Interactive chat<br/>[engine.rs]"]
  node_daemonstate[("Daemon settings and jobs<br/>[main.rs]")]
end

subgraph group_compile["Compilation and formats"]
  node_compiler["Model compiler<br/>[pipeline.rs]"]
  node_ir["Compiler IR<br/>[graph.rs]"]
  node_artifact["Logan artifacts<br/>[lib.rs]"]
  node_coli["COLI compatibility<br/>[package.rs]"]
end

subgraph group_runtime["Inference runtimes"]
  node_qwen4["Qwen sparse runtime<br/>[lib.rs]"]
  node_llama["Llama dense runtime<br/>[lib.rs]"]
  node_qwen["Qwen reference runtime<br/>[lib.rs]"]
  node_spark["Spark runtime<br/>[lib.rs]"]
  node_ane["ANE execution<br/>[lib.rs]"]
  node_route["RouteScout prediction<br/>[route_predictor.rs]"]
end

subgraph group_foundation["Runtime foundations"]
  node_core["Runtime foundations<br/>[lib.rs]"]
  node_storage["Weight sources<br/>[storage.rs]"]
  node_scheduler["Scheduling and residency<br/>[runtime.rs]"]
  node_state[("State and prefix cache<br/>[mod.rs]")]
end

subgraph group_hardware["Hardware acceleration"]
  node_metal["Metal backend<br/>[lib.rs]"]
end

node_client(("API or UI client"))
node_hf["Model source"]
node_accelerator{{"Apple hardware"}}

node_client -->|"sends API requests"| node_logand
node_client -->|"enters chat"| node_chat
node_chat -->|"routes inference"| node_qwen4
node_chat -->|"routes inference"| node_llama
node_hf -->|"downloads models"| node_logand
node_logand -->|"reads and updates"| node_daemonstate
node_logand -->|"routes Qwen"| node_qwen4
node_logand -->|"routes Llama"| node_llama
node_logand -->|"quantizes models"| node_compiler
node_compiler -->|"reads checkpoints"| node_hf
node_compiler -->|"constructs representation"| node_ir
node_compiler -->|"emits packages"| node_artifact
node_compiler -.->|"supports legacy format"| node_coli
node_qwen4 -->|"resolves weights"| node_storage
node_llama -->|"resolves weights"| node_storage
node_spark -->|"loads weights"| node_storage
node_qwen4 -->|"uses scheduling"| node_scheduler
node_qwen4 -->|"uses prefix state"| node_state
node_llama -->|"uses prefix state"| node_state
node_qwen4 -->|"submits kernels"| node_metal
node_llama -->|"uses dense projections"| node_metal
node_ane -.->|"executes on ANE"| node_accelerator
node_metal -->|"executes on Metal"| node_accelerator
node_route -.->|"advises prefetch"| node_qwen4

click node_logand "https://github.com/mateocabanal/logan/blob/main/logand/src/main.rs"
click node_chat "https://github.com/mateocabanal/logan/blob/main/logan-chat/src/engine.rs"
click node_compiler "https://github.com/mateocabanal/logan/blob/main/logan-compiler/src/pipeline.rs"
click node_ir "https://github.com/mateocabanal/logan/blob/main/logan-ir/src/graph.rs"
click node_artifact "https://github.com/mateocabanal/logan/blob/main/logan-artifact/src/lib.rs"
click node_coli "https://github.com/mateocabanal/logan/blob/main/logan-format/src/package.rs"
click node_qwen4 "https://github.com/mateocabanal/logan/blob/main/logan-qwen4/src/lib.rs"
click node_llama "https://github.com/mateocabanal/logan/blob/main/logan-llama/src/lib.rs"
click node_qwen "https://github.com/mateocabanal/logan/blob/main/logan-qwen/src/lib.rs"
click node_spark "https://github.com/mateocabanal/logan/blob/main/logan-spark/src/lib.rs"
click node_ane "https://github.com/mateocabanal/logan/blob/main/logan-ane/src/lib.rs"
click node_route "https://github.com/mateocabanal/logan/blob/main/logan-qwen4/src/route_predictor.rs"
click node_core "https://github.com/mateocabanal/logan/blob/main/logan-core/src/lib.rs"
click node_storage "https://github.com/mateocabanal/logan/blob/main/logan-core/src/storage.rs"
click node_scheduler "https://github.com/mateocabanal/logan/blob/main/logan-core/src/sched/runtime.rs"
click node_state "https://github.com/mateocabanal/logan/blob/main/logan-core/src/state/mod.rs"
click node_metal "https://github.com/mateocabanal/logan/blob/main/logan-metal/src/lib.rs"
click node_daemonstate "https://github.com/mateocabanal/logan/blob/main/logand/src/main.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_logand,node_chat,node_daemonstate,node_client toneBlue
class node_compiler,node_ir,node_artifact,node_coli toneAmber
class node_qwen4,node_llama,node_qwen,node_spark,node_ane,node_route toneMint
class node_core,node_storage,node_scheduler,node_state toneRose
class node_metal,node_hf,node_accelerator toneIndigo
```

## Components

### Service and clients

- [Inference daemon](https://github.com/mateocabanal/logan/blob/main/logand/src/main.rs): `logand/src/main.rs`
- [Interactive chat](https://github.com/mateocabanal/logan/blob/main/logan-chat/src/engine.rs): `logan-chat/src/engine.rs`
- [Daemon settings and jobs](https://github.com/mateocabanal/logan/blob/main/logand/src/main.rs): `logand/src/main.rs`

### Compilation and formats

- [Model compiler](https://github.com/mateocabanal/logan/blob/main/logan-compiler/src/pipeline.rs): `logan-compiler/src/pipeline.rs`
- [Compiler IR](https://github.com/mateocabanal/logan/blob/main/logan-ir/src/graph.rs): `logan-ir/src/graph.rs`
- [Logan artifacts](https://github.com/mateocabanal/logan/blob/main/logan-artifact/src/lib.rs): `logan-artifact/src/lib.rs`
- [COLI compatibility](https://github.com/mateocabanal/logan/blob/main/logan-format/src/package.rs): `logan-format/src/package.rs`

### Inference runtimes

- [Qwen sparse runtime](https://github.com/mateocabanal/logan/blob/main/logan-qwen4/src/lib.rs): `logan-qwen4/src/lib.rs`
- [Llama dense runtime](https://github.com/mateocabanal/logan/blob/main/logan-llama/src/lib.rs): `logan-llama/src/lib.rs`
- [Qwen reference runtime](https://github.com/mateocabanal/logan/blob/main/logan-qwen/src/lib.rs): `logan-qwen/src/lib.rs`
- [Spark runtime](https://github.com/mateocabanal/logan/blob/main/logan-spark/src/lib.rs): `logan-spark/src/lib.rs`
- [ANE execution](https://github.com/mateocabanal/logan/blob/main/logan-ane/src/lib.rs): `logan-ane/src/lib.rs`
- [RouteScout prediction](https://github.com/mateocabanal/logan/blob/main/logan-qwen4/src/route_predictor.rs): `logan-qwen4/src/route_predictor.rs`

### Runtime foundations

- [Runtime foundations](https://github.com/mateocabanal/logan/blob/main/logan-core/src/lib.rs): `logan-core/src/lib.rs`
- [Weight sources](https://github.com/mateocabanal/logan/blob/main/logan-core/src/storage.rs): `logan-core/src/storage.rs`
- [Scheduling and residency](https://github.com/mateocabanal/logan/blob/main/logan-core/src/sched/runtime.rs): `logan-core/src/sched/runtime.rs`
- [State and prefix cache](https://github.com/mateocabanal/logan/blob/main/logan-core/src/state/mod.rs): `logan-core/src/state/mod.rs`

### Hardware acceleration

- [Metal backend](https://github.com/mateocabanal/logan/blob/main/logan-metal/src/lib.rs): `logan-metal/src/lib.rs`

### Other components

- **API or UI client**
- **Model source**
- **Apple hardware**

## Connections

- API or UI client → Inference daemon: sends API requests
- API or UI client → Interactive chat: enters chat
- Interactive chat → Qwen sparse runtime: routes inference
- Interactive chat → Llama dense runtime: routes inference
- Model source → Inference daemon: downloads models
- Inference daemon → Daemon settings and jobs: reads and updates
- Inference daemon → Qwen sparse runtime: routes Qwen
- Inference daemon → Llama dense runtime: routes Llama
- Inference daemon → Model compiler: quantizes models
- Model compiler → Model source: reads checkpoints
- Model compiler → Compiler IR: constructs representation
- Model compiler → Logan artifacts: emits packages
- Model compiler → COLI compatibility: supports legacy format
- Qwen sparse runtime → Weight sources: resolves weights
- Llama dense runtime → Weight sources: resolves weights
- Spark runtime → Weight sources: loads weights
- Qwen sparse runtime → Scheduling and residency: uses scheduling
- Qwen sparse runtime → State and prefix cache: uses prefix state
- Llama dense runtime → State and prefix cache: uses prefix state
- Qwen sparse runtime → Metal backend: submits kernels
- Llama dense runtime → Metal backend: uses dense projections
- ANE execution → Apple hardware: executes on ANE
- Metal backend → Apple hardware: executes on Metal
- RouteScout prediction → Qwen sparse runtime: advises prefetch