# benedictking/ccx architecture

> Architecture diagram of the GitHub repository benedictking/ccx, 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/benedictking/ccx
- Repository: https://github.com/benedictking/ccx

## Overview

CCX is an AI API proxy and protocol-translation gateway, with a web administration console and a native desktop management option. The principal workflow accepts a client request, selects an eligible upstream channel, translates and forwards the request, then returns the upstream response. Separate capabilities cover channel/key administration, health checks and failover, usage monitoring, and Autopilot routing. The README documents the supported protocols and scheduling features; sampled source shows route registration, capability-test requests, health-check orchestration, and selected supporting logic, but not every runtime call path.

Main entry points: [`backend-go/internal/handlers`](https://github.com/benedictking/ccx/tree/main/backend-go/internal/handlers) (Protocol Handlers), [`backend-go/internal/scheduler/channel_scheduler.go`](https://github.com/benedictking/ccx/blob/main/backend-go/internal/scheduler/channel_scheduler.go) (Channel Scheduler), [`backend-go/main.go`](https://github.com/benedictking/ccx/blob/main/backend-go/main.go) (HTTP Entrypoint), [`backend-go/internal/healthcheck/manager.go`](https://github.com/benedictking/ccx/blob/main/backend-go/internal/healthcheck/manager.go) (Health Checks)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_gateway["Proxy Gateway"]
  node_entry["HTTP Entrypoint<br/>[main.go]"]
  node_protocols["Protocol Handlers"]
  node_converters["Protocol Converters"]
  node_compression["Request Compression<br/>[engine.go]"]
  node_upstream["Model Providers"]
end

subgraph group_routing["Routing and Health"]
  node_scheduler["Channel Scheduler"]
  node_config["Channel Configuration<br/>[config.go]"]
  node_health["Health Checks<br/>[manager.go]"]
  node_metrics["Metrics and Logs"]
  node_state[("Metrics Store<br/>[sqlite_store.go]")]
  node_autopilot["Autopilot Routing"]
end

subgraph group_admin["Administration"]
  node_web["Web Admin Console<br/>[App.vue]"]
  node_api["Admin API"]
  node_capability["Capability Testing"]
end

subgraph group_management["Desktop Management"]
  node_desktop["Desktop Shell<br/>[app.go]"]
  node_backend_manager["Backend Manager<br/>[manager.go]"]
end

node_client(("API Client"))
node_services(("AI Services"))

node_client -->|"sends requests"| node_entry
node_entry -->|"dispatches API"| node_protocols
node_protocols -->|"selects channel"| node_scheduler
node_scheduler -->|"reads channels"| node_config
node_protocols -->|"translates payloads"| node_converters
node_protocols -.->|"may compress"| node_compression
node_protocols -->|"forwards requests"| node_upstream
node_upstream -->|"calls models"| node_services
node_health -->|"probes channels"| node_services
node_health -->|"records health"| node_state
node_health -->|"reports failures"| node_scheduler
node_scheduler -->|"records traffic"| node_metrics
node_metrics -->|"persists metrics"| node_state
node_web -->|"calls admin APIs"| node_api
node_entry -->|"registers admin routes"| node_api
node_api -->|"manages channels"| node_config
node_api -->|"starts tests"| node_capability
node_capability -->|"tests capabilities"| node_services
node_autopilot -->|"advises routing"| node_scheduler
node_desktop -->|"manages process"| node_backend_manager
node_backend_manager -->|"starts or attaches"| node_entry

click node_entry "https://github.com/benedictking/ccx/blob/main/backend-go/main.go"
click node_protocols "https://github.com/benedictking/ccx/tree/main/backend-go/internal/handlers"
click node_converters "https://github.com/benedictking/ccx/tree/main/backend-go/internal/converters"
click node_compression "https://github.com/benedictking/ccx/blob/main/backend-go/internal/compression/engine.go"
click node_scheduler "https://github.com/benedictking/ccx/blob/main/backend-go/internal/scheduler/channel_scheduler.go"
click node_config "https://github.com/benedictking/ccx/blob/main/backend-go/internal/config/config.go"
click node_health "https://github.com/benedictking/ccx/blob/main/backend-go/internal/healthcheck/manager.go"
click node_metrics "https://github.com/benedictking/ccx/tree/main/backend-go/internal/metrics"
click node_state "https://github.com/benedictking/ccx/blob/main/backend-go/internal/metrics/sqlite_store.go"
click node_upstream "https://github.com/benedictking/ccx/tree/main/backend-go/internal/providers"
click node_web "https://github.com/benedictking/ccx/blob/main/frontend/src/App.vue"
click node_api "https://github.com/benedictking/ccx/tree/main/backend-go/internal/handlers"
click node_capability "https://github.com/benedictking/ccx/blob/main/backend-go/internal/handlers/capability_test_handler.go"
click node_autopilot "https://github.com/benedictking/ccx/tree/main/backend-go/internal/autopilot"
click node_desktop "https://github.com/benedictking/ccx/blob/main/desktop/app.go"
click node_backend_manager "https://github.com/benedictking/ccx/blob/main/desktop/internal/backend/manager.go"

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_entry,node_protocols,node_converters,node_compression,node_upstream,node_client toneBlue
class node_scheduler,node_config,node_health,node_metrics,node_state,node_autopilot toneAmber
class node_web,node_api,node_capability toneMint
class node_desktop,node_backend_manager toneRose
class node_services toneIndigo
```

## Components

### Proxy Gateway

- [HTTP Entrypoint](https://github.com/benedictking/ccx/blob/main/backend-go/main.go): `backend-go/main.go`
- [Protocol Handlers](https://github.com/benedictking/ccx/tree/main/backend-go/internal/handlers): `backend-go/internal/handlers`
- [Protocol Converters](https://github.com/benedictking/ccx/tree/main/backend-go/internal/converters): `backend-go/internal/converters`
- [Request Compression](https://github.com/benedictking/ccx/blob/main/backend-go/internal/compression/engine.go): `backend-go/internal/compression/engine.go`
- [Model Providers](https://github.com/benedictking/ccx/tree/main/backend-go/internal/providers): `backend-go/internal/providers`

### Routing and Health

- [Channel Scheduler](https://github.com/benedictking/ccx/blob/main/backend-go/internal/scheduler/channel_scheduler.go): `backend-go/internal/scheduler/channel_scheduler.go`
- [Channel Configuration](https://github.com/benedictking/ccx/blob/main/backend-go/internal/config/config.go): `backend-go/internal/config/config.go`
- [Health Checks](https://github.com/benedictking/ccx/blob/main/backend-go/internal/healthcheck/manager.go): `backend-go/internal/healthcheck/manager.go`
- [Metrics and Logs](https://github.com/benedictking/ccx/tree/main/backend-go/internal/metrics): `backend-go/internal/metrics`
- [Metrics Store](https://github.com/benedictking/ccx/blob/main/backend-go/internal/metrics/sqlite_store.go): `backend-go/internal/metrics/sqlite_store.go`
- [Autopilot Routing](https://github.com/benedictking/ccx/tree/main/backend-go/internal/autopilot): `backend-go/internal/autopilot`

### Administration

- [Web Admin Console](https://github.com/benedictking/ccx/blob/main/frontend/src/App.vue): `frontend/src/App.vue`
- [Admin API](https://github.com/benedictking/ccx/tree/main/backend-go/internal/handlers): `backend-go/internal/handlers`
- [Capability Testing](https://github.com/benedictking/ccx/blob/main/backend-go/internal/handlers/capability_test_handler.go): `backend-go/internal/handlers/capability_test_handler.go`

### Desktop Management

- [Desktop Shell](https://github.com/benedictking/ccx/blob/main/desktop/app.go): `desktop/app.go`
- [Backend Manager](https://github.com/benedictking/ccx/blob/main/desktop/internal/backend/manager.go): `desktop/internal/backend/manager.go`

### Other components

- **API Client**
- **AI Services**

## Connections

- API Client → HTTP Entrypoint: sends requests
- HTTP Entrypoint → Protocol Handlers: dispatches API
- Protocol Handlers → Channel Scheduler: selects channel
- Channel Scheduler → Channel Configuration: reads channels
- Protocol Handlers → Protocol Converters: translates payloads
- Protocol Handlers → Request Compression: may compress
- Protocol Handlers → Model Providers: forwards requests
- Model Providers → AI Services: calls models
- Health Checks → AI Services: probes channels
- Health Checks → Metrics Store: records health
- Health Checks → Channel Scheduler: reports failures
- Channel Scheduler → Metrics and Logs: records traffic
- Metrics and Logs → Metrics Store: persists metrics
- Web Admin Console → Admin API: calls admin APIs
- HTTP Entrypoint → Admin API: registers admin routes
- Admin API → Channel Configuration: manages channels
- Admin API → Capability Testing: starts tests
- Capability Testing → AI Services: tests capabilities
- Autopilot Routing → Channel Scheduler: advises routing
- Desktop Shell → Backend Manager: manages process
- Backend Manager → HTTP Entrypoint: starts or attaches