# edward-lyz/codex-mixin architecture

> Architecture diagram of the GitHub repository edward-lyz/codex-mixin, 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/edward-lyz/codex-mixin
- Repository: https://github.com/edward-lyz/codex-mixin

## Overview

Codex Mixin is a cross-platform local gateway and control plane for connecting custom model providers to official Codex and other clients. The main request path is a client calling the local API, where the server handles authentication and protocol-specific requests, the gateway routes model work, and upstream transport communicates with providers. Users also manage providers, models, configuration, and service state through CLI/TUI and desktop controls. The README documents Fusion, client integrations, and usage/benchmark observability; their detailed wiring is not fully visible in the sampled source.

Main entry points: [`src/server/routes.rs`](https://github.com/edward-lyz/codex-mixin/blob/main/src/server/routes.rs) (HTTP routes), [`src/cli/mod.rs`](https://github.com/edward-lyz/codex-mixin/blob/main/src/cli/mod.rs) (CLI commands), [`src/server/mod.rs`](https://github.com/edward-lyz/codex-mixin/blob/main/src/server/mod.rs) (Request handlers), [`src/gateway/router.rs`](https://github.com/edward-lyz/codex-mixin/blob/main/src/gateway/router.rs) (Model routing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["User controls"]
  node_cli["CLI commands<br/>[mod.rs]"]
  node_tui["Terminal console<br/>[mod.rs]"]
  node_macos["macOS controls<br/>[MenuBarApp.swift]"]
  node_windows["Windows app<br/>[main.cpp]"]
  node_service["Service lifecycle<br/>[service.rs]"]
end

subgraph group_gateway["Gateway runtime"]
  node_routes["HTTP routes<br/>[routes.rs]"]
  node_server["Request handlers<br/>[mod.rs]"]
  node_protocol["Protocol conversion<br/>[mod.rs]"]
  node_router["Model routing<br/>[router.rs]"]
  node_upstream["Upstream transport<br/>[mod.rs]"]
end

subgraph group_providers["Providers and models"]
  node_registry["Provider registry<br/>[registry.rs]"]
  node_discovery["Model discovery<br/>[discovery.rs]"]
  node_catalog["Model catalog<br/>[service.rs]"]
end

subgraph group_state["Configuration and telemetry"]
  node_config["Config management<br/>[config.rs]"]
  node_config_store[("Encrypted config<br/>[storage.rs]")]
  node_capabilities[("Capability state<br/>[storage.rs]")]
  node_telemetry["Usage and benchmarks<br/>[routes.rs]"]
end

subgraph group_extensions["Integrations and Fusion"]
  node_fusion["Fusion workflow<br/>[engine.rs]"]
  node_client_sync["Client integration<br/>[mod.rs]"]
  node_client_configs["Client configurations<br/>[files.rs]"]
end

node_codex(("Codex and clients"))
node_operator(("Operator"))
node_model_services{{"Model providers"}}

node_codex -->|"API requests"| node_routes
node_routes -->|"dispatches"| node_server
node_server -->|"routes models"| node_router
node_server -->|"converts protocols"| node_protocol
node_router -->|"resolves providers"| node_registry
node_router -->|"sends requests"| node_upstream
node_upstream -->|"calls upstream"| node_model_services
node_operator -->|"runs commands"| node_cli
node_operator -->|"uses console"| node_tui
node_operator -->|"uses controls"| node_macos
node_operator -->|"uses controls"| node_windows
node_tui -->|"invokes commands"| node_cli
node_cli -->|"manages settings"| node_config
node_config -->|"reads and writes"| node_config_store
node_cli -->|"manages providers"| node_registry
node_registry -->|"discovers models"| node_discovery
node_discovery -->|"stores probe state"| node_capabilities
node_service -->|"starts gateway"| node_routes
node_service -->|"syncs models"| node_client_sync
node_client_sync -->|"updates files"| node_client_configs
node_routes -->|"serves catalog"| node_catalog
node_routes -->|"serves metrics"| node_telemetry
node_operator -.->|"requests review"| node_fusion
node_fusion -.->|"runs model stages"| node_upstream

click node_cli "https://github.com/edward-lyz/codex-mixin/blob/main/src/cli/mod.rs"
click node_tui "https://github.com/edward-lyz/codex-mixin/blob/main/tui/mod.rs"
click node_macos "https://github.com/edward-lyz/codex-mixin/blob/main/macos/MenuBarApp.swift"
click node_windows "https://github.com/edward-lyz/codex-mixin/blob/main/windows/windows/runner/main.cpp"
click node_service "https://github.com/edward-lyz/codex-mixin/blob/main/src/cli/service.rs"
click node_routes "https://github.com/edward-lyz/codex-mixin/blob/main/src/server/routes.rs"
click node_server "https://github.com/edward-lyz/codex-mixin/blob/main/src/server/mod.rs"
click node_protocol "https://github.com/edward-lyz/codex-mixin/blob/main/src/protocol/mod.rs"
click node_router "https://github.com/edward-lyz/codex-mixin/blob/main/src/gateway/router.rs"
click node_fusion "https://github.com/edward-lyz/codex-mixin/blob/main/src/fusion/engine.rs"
click node_upstream "https://github.com/edward-lyz/codex-mixin/blob/main/src/upstream/mod.rs"
click node_registry "https://github.com/edward-lyz/codex-mixin/blob/main/src/provider/registry.rs"
click node_discovery "https://github.com/edward-lyz/codex-mixin/blob/main/src/provider/discovery.rs"
click node_catalog "https://github.com/edward-lyz/codex-mixin/blob/main/src/catalog/service.rs"
click node_config "https://github.com/edward-lyz/codex-mixin/blob/main/src/config.rs"
click node_config_store "https://github.com/edward-lyz/codex-mixin/blob/main/src/config/storage.rs"
click node_capabilities "https://github.com/edward-lyz/codex-mixin/blob/main/src/provider/capabilities/storage.rs"
click node_telemetry "https://github.com/edward-lyz/codex-mixin/blob/main/src/server/routes.rs"
click node_client_sync "https://github.com/edward-lyz/codex-mixin/blob/main/src/clients/mod.rs"
click node_client_configs "https://github.com/edward-lyz/codex-mixin/blob/main/src/clients/files.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_cli,node_tui,node_macos,node_windows,node_service,node_codex toneBlue
class node_routes,node_server,node_protocol,node_router,node_upstream toneAmber
class node_registry,node_discovery,node_catalog toneMint
class node_config,node_config_store,node_capabilities,node_telemetry toneRose
class node_fusion,node_client_sync,node_client_configs,node_operator,node_model_services toneIndigo
```

## Components

### User controls

- [CLI commands](https://github.com/edward-lyz/codex-mixin/blob/main/src/cli/mod.rs): `src/cli/mod.rs`
- [Terminal console](https://github.com/edward-lyz/codex-mixin/blob/main/tui/mod.rs): `tui/mod.rs`
- [macOS controls](https://github.com/edward-lyz/codex-mixin/blob/main/macos/MenuBarApp.swift): `macos/MenuBarApp.swift`
- [Windows app](https://github.com/edward-lyz/codex-mixin/blob/main/windows/windows/runner/main.cpp): `windows/windows/runner/main.cpp`
- [Service lifecycle](https://github.com/edward-lyz/codex-mixin/blob/main/src/cli/service.rs): `src/cli/service.rs`

### Gateway runtime

- [HTTP routes](https://github.com/edward-lyz/codex-mixin/blob/main/src/server/routes.rs): `src/server/routes.rs`
- [Request handlers](https://github.com/edward-lyz/codex-mixin/blob/main/src/server/mod.rs): `src/server/mod.rs`
- [Protocol conversion](https://github.com/edward-lyz/codex-mixin/blob/main/src/protocol/mod.rs): `src/protocol/mod.rs`
- [Model routing](https://github.com/edward-lyz/codex-mixin/blob/main/src/gateway/router.rs): `src/gateway/router.rs`
- [Upstream transport](https://github.com/edward-lyz/codex-mixin/blob/main/src/upstream/mod.rs): `src/upstream/mod.rs`

### Providers and models

- [Provider registry](https://github.com/edward-lyz/codex-mixin/blob/main/src/provider/registry.rs): `src/provider/registry.rs`
- [Model discovery](https://github.com/edward-lyz/codex-mixin/blob/main/src/provider/discovery.rs): `src/provider/discovery.rs`
- [Model catalog](https://github.com/edward-lyz/codex-mixin/blob/main/src/catalog/service.rs): `src/catalog/service.rs`

### Configuration and telemetry

- [Config management](https://github.com/edward-lyz/codex-mixin/blob/main/src/config.rs): `src/config.rs`
- [Encrypted config](https://github.com/edward-lyz/codex-mixin/blob/main/src/config/storage.rs): `src/config/storage.rs`
- [Capability state](https://github.com/edward-lyz/codex-mixin/blob/main/src/provider/capabilities/storage.rs): `src/provider/capabilities/storage.rs`
- [Usage and benchmarks](https://github.com/edward-lyz/codex-mixin/blob/main/src/server/routes.rs): `src/server/routes.rs`

### Integrations and Fusion

- [Fusion workflow](https://github.com/edward-lyz/codex-mixin/blob/main/src/fusion/engine.rs): `src/fusion/engine.rs`
- [Client integration](https://github.com/edward-lyz/codex-mixin/blob/main/src/clients/mod.rs): `src/clients/mod.rs`
- [Client configurations](https://github.com/edward-lyz/codex-mixin/blob/main/src/clients/files.rs): `src/clients/files.rs`

### Other components

- **Codex and clients**
- **Operator**
- **Model providers**

## Connections

- Codex and clients → HTTP routes: API requests
- HTTP routes → Request handlers: dispatches
- Request handlers → Model routing: routes models
- Request handlers → Protocol conversion: converts protocols
- Model routing → Provider registry: resolves providers
- Model routing → Upstream transport: sends requests
- Upstream transport → Model providers: calls upstream
- Operator → CLI commands: runs commands
- Operator → Terminal console: uses console
- Operator → macOS controls: uses controls
- Operator → Windows app: uses controls
- Terminal console → CLI commands: invokes commands
- CLI commands → Config management: manages settings
- Config management → Encrypted config: reads and writes
- CLI commands → Provider registry: manages providers
- Provider registry → Model discovery: discovers models
- Model discovery → Capability state: stores probe state
- Service lifecycle → HTTP routes: starts gateway
- Service lifecycle → Client integration: syncs models
- Client integration → Client configurations: updates files
- HTTP routes → Model catalog: serves catalog
- HTTP routes → Usage and benchmarks: serves metrics
- Operator → Fusion workflow: requests review
- Fusion workflow → Upstream transport: runs model stages