# lich0821/ccnexus architecture

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

## Overview

ccNexus is a cross-platform Claude Code/Codex proxy with desktop and headless-server entry points. Its main workflow accepts client API requests, selects an endpoint, transforms formats as needed, and forwards requests; configuration, credentials, persistence, and usage statistics support that flow. Desktop and server interfaces expose endpoint and statistics management, while README-documented capabilities include Codex token pools, model listing, Basic Auth, and WebDAV sync. Some runtime wiring is not shown in the excerpts, so uncertain links are omitted or marked unverified.

Main entry points: [`internal/proxy/proxy.go`](https://github.com/lich0821/ccnexus/blob/master/internal/proxy/proxy.go) (Proxy server), [`internal/storage/sqlite.go`](https://github.com/lich0821/ccnexus/blob/master/internal/storage/sqlite.go) (SQLite state), [`internal/proxy/proxy_request.go`](https://github.com/lich0821/ccnexus/blob/master/internal/proxy/proxy_request.go) (Request routing), [`cmd/desktop/app.go`](https://github.com/lich0821/ccnexus/blob/master/cmd/desktop/app.go) (Desktop bridge)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Proxy runtime"]
  node_proxy["Proxy server<br/>[proxy.go]"]
  node_request["Request routing<br/>[proxy_request.go]"]
  node_transform["Format conversion"]
  node_count["Token estimation<br/>[estimator.go]"]
  node_server["Headless entry<br/>[main.go]"]
end

subgraph group_domain["Endpoint domain"]
  node_endpointsvc["Endpoint management<br/>[endpoint.go]"]
  node_config["App configuration<br/>[config.go]"]
  node_tokenpool["Codex token pool<br/>[interface.go]"]
  node_stats["Usage statistics<br/>[stats.go]"]
end

subgraph group_persistence["State and sync"]
  node_database[("SQLite state<br/>[sqlite.go]")]
  node_webdav["WebDAV sync<br/>[sync.go]"]
end

subgraph group_desktop["Desktop app"]
  node_desktop["Desktop bridge<br/>[app.go]"]
  node_desktopui["Desktop interface<br/>[main.js]"]
end

subgraph group_serverui["Server console"]
  node_webuiapi["Admin API<br/>[handler.go]"]
  node_webui["Server console<br/>[main.js]"]
end

node_client(("API client"))
node_upstream(("Provider endpoints"))

node_client -->|"sends requests"| node_proxy
node_proxy -.->|"dispatches requests"| node_request
node_request -.->|"forwards requests"| node_upstream
node_request -->|"converts formats"| node_transform
node_proxy -->|"estimates tokens"| node_count
node_endpointsvc -->|"updates configuration"| node_proxy
node_endpointsvc -->|"persists configuration"| node_database
node_proxy -.->|"records usage"| node_stats
node_tokenpool -.->|"stores credentials"| node_database
node_webdav -.->|"syncs state"| node_database
node_server -->|"starts service"| node_proxy
node_server -->|"opens storage"| node_database
node_webuiapi -->|"updates proxy config"| node_proxy
node_webui -.->|"calls admin API"| node_webuiapi
node_desktopui -.->|"invokes bindings"| node_desktop
node_desktop -->|"starts proxy"| node_proxy
node_desktop -.->|"manages endpoints"| node_endpointsvc
node_desktopui -.->|"shows statistics"| node_stats

click node_proxy "https://github.com/lich0821/ccnexus/blob/master/internal/proxy/proxy.go"
click node_request "https://github.com/lich0821/ccnexus/blob/master/internal/proxy/proxy_request.go"
click node_transform "https://github.com/lich0821/ccnexus/tree/master/internal/transformer/convert"
click node_count "https://github.com/lich0821/ccnexus/blob/master/internal/tokencount/estimator.go"
click node_endpointsvc "https://github.com/lich0821/ccnexus/blob/master/internal/service/endpoint.go"
click node_config "https://github.com/lich0821/ccnexus/blob/master/internal/config/config.go"
click node_tokenpool "https://github.com/lich0821/ccnexus/blob/master/internal/storage/interface.go"
click node_stats "https://github.com/lich0821/ccnexus/blob/master/internal/proxy/stats.go"
click node_database "https://github.com/lich0821/ccnexus/blob/master/internal/storage/sqlite.go"
click node_webdav "https://github.com/lich0821/ccnexus/blob/master/internal/webdav/sync.go"
click node_desktop "https://github.com/lich0821/ccnexus/blob/master/cmd/desktop/app.go"
click node_desktopui "https://github.com/lich0821/ccnexus/blob/master/cmd/desktop/frontend/src/main.js"
click node_webuiapi "https://github.com/lich0821/ccnexus/blob/master/cmd/server/webui/api/handler.go"
click node_webui "https://github.com/lich0821/ccnexus/blob/master/cmd/server/webui/ui/js/main.js"
click node_server "https://github.com/lich0821/ccnexus/blob/master/cmd/server/main.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_proxy,node_request,node_transform,node_count,node_server,node_client toneBlue
class node_endpointsvc,node_config,node_tokenpool,node_stats toneAmber
class node_database,node_webdav toneMint
class node_desktop,node_desktopui toneRose
class node_webuiapi,node_webui,node_upstream toneIndigo
```

## Components

### Proxy runtime

- [Proxy server](https://github.com/lich0821/ccnexus/blob/master/internal/proxy/proxy.go): `internal/proxy/proxy.go`
- [Request routing](https://github.com/lich0821/ccnexus/blob/master/internal/proxy/proxy_request.go): `internal/proxy/proxy_request.go`
- [Format conversion](https://github.com/lich0821/ccnexus/tree/master/internal/transformer/convert): `internal/transformer/convert`
- [Token estimation](https://github.com/lich0821/ccnexus/blob/master/internal/tokencount/estimator.go): `internal/tokencount/estimator.go`
- [Headless entry](https://github.com/lich0821/ccnexus/blob/master/cmd/server/main.go): `cmd/server/main.go`

### Endpoint domain

- [Endpoint management](https://github.com/lich0821/ccnexus/blob/master/internal/service/endpoint.go): `internal/service/endpoint.go`
- [App configuration](https://github.com/lich0821/ccnexus/blob/master/internal/config/config.go): `internal/config/config.go`
- [Codex token pool](https://github.com/lich0821/ccnexus/blob/master/internal/storage/interface.go): `internal/storage/interface.go`
- [Usage statistics](https://github.com/lich0821/ccnexus/blob/master/internal/proxy/stats.go): `internal/proxy/stats.go`

### State and sync

- [SQLite state](https://github.com/lich0821/ccnexus/blob/master/internal/storage/sqlite.go): `internal/storage/sqlite.go`
- [WebDAV sync](https://github.com/lich0821/ccnexus/blob/master/internal/webdav/sync.go): `internal/webdav/sync.go`

### Desktop app

- [Desktop bridge](https://github.com/lich0821/ccnexus/blob/master/cmd/desktop/app.go): `cmd/desktop/app.go`
- [Desktop interface](https://github.com/lich0821/ccnexus/blob/master/cmd/desktop/frontend/src/main.js): `cmd/desktop/frontend/src/main.js`

### Server console

- [Admin API](https://github.com/lich0821/ccnexus/blob/master/cmd/server/webui/api/handler.go): `cmd/server/webui/api/handler.go`
- [Server console](https://github.com/lich0821/ccnexus/blob/master/cmd/server/webui/ui/js/main.js): `cmd/server/webui/ui/js/main.js`

### Other components

- **API client**
- **Provider endpoints**

## Connections

- API client → Proxy server: sends requests (evidence: `README.md`)
- Proxy server → Request routing: dispatches requests
- Request routing → Provider endpoints: forwards requests
- Request routing → Format conversion: converts formats (evidence: `internal/proxy/proxy_request.go`)
- Proxy server → Token estimation: estimates tokens
- Endpoint management → Proxy server: updates configuration (evidence: `internal/service/endpoint.go`)
- Endpoint management → SQLite state: persists configuration (evidence: `internal/service/endpoint.go`)
- Proxy server → Usage statistics: records usage
- Codex token pool → SQLite state: stores credentials
- WebDAV sync → SQLite state: syncs state
- Headless entry → Proxy server: starts service (evidence: `cmd/server/main.go`)
- Headless entry → SQLite state: opens storage (evidence: `cmd/server/main.go`)
- Admin API → Proxy server: updates proxy config (evidence: `cmd/server/webui/api/handler.go`)
- Server console → Admin API: calls admin API
- Desktop interface → Desktop bridge: invokes bindings
- Desktop bridge → Proxy server: starts proxy (evidence: `cmd/desktop/app.go`)
- Desktop bridge → Endpoint management: manages endpoints
- Desktop interface → Usage statistics: shows statistics
