# stringke/claudex architecture

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

- Interactive diagram: https://gitdiagram.com/stringke/claudex
- Repository: https://github.com/stringke/claudex

## Overview

Claudex manages Claude Code profiles and runs them through a local proxy that routes provider requests, translates protocols, and can enrich conversation context. The graph also includes documented OAuth, configuration-set, and dashboard capabilities. The proxy and context wiring is partly supported by sampled source and README; unsampled subsystem internals and uncertain call paths are kept at directory-level granularity.

Main entry points: [`src/proxy/handler.rs`](https://github.com/stringke/claudex/blob/main/src/proxy/handler.rs) (Request handler), [`src/main.rs`](https://github.com/stringke/claudex/blob/main/src/main.rs) (CLI dispatcher), [`src/proxy/context_engine.rs`](https://github.com/stringke/claudex/blob/main/src/proxy/context_engine.rs) (Context preprocessing), [`src/sets/mod.rs`](https://github.com/stringke/claudex/blob/main/src/sets/mod.rs) (Configuration sets)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["CLI runtime"]
  node_main["CLI dispatcher<br/>[main.rs]"]
  node_cli["Command definitions<br/>[cli.rs]"]
  node_process["Launch and daemon<br/>[launch.rs]"]
end

subgraph group_proxy["Proxy and providers"]
  node_proxyserver["Proxy server<br/>[mod.rs]"]
  node_handler["Request handler<br/>[handler.rs]"]
  node_router["Intent router<br/>[classifier.rs]"]
  node_adapters["Provider adapters<br/>[mod.rs]"]
  node_translate["Protocol translation<br/>[mod.rs]"]
  node_fallback["Failover logic<br/>[fallback.rs]"]
end

subgraph group_context["Context engine"]
  node_contextengine["Context preprocessing<br/>[context_engine.rs]"]
  node_rag["Local RAG<br/>[rag.rs]"]
  node_sharing["Context sharing<br/>[sharing.rs]"]
  node_compression["Conversation compression<br/>[compression.rs]"]
end

subgraph group_accounts["Profiles and auth"]
  node_config["Configuration<br/>[mod.rs]"]
  node_profile["Profile management<br/>[profile.rs]"]
  node_oauthmgr["OAuth token manager<br/>[manager.rs]"]
  node_oauthflow["OAuth login flows<br/>[providers.rs]"]
  node_oauthserver["OAuth callback server<br/>[server.rs]"]
end

subgraph group_operations["Management tools"]
  node_sets["Configuration sets<br/>[mod.rs]"]
  node_setsource["Set sources<br/>[source.rs]"]
  node_setinstall["Set installer<br/>[install.rs]"]
  node_setlock[("Set registry<br/>[lock.rs]")]
  node_dashboard["TUI dashboard<br/>[mod.rs]"]
  node_metrics["Proxy metrics<br/>[metrics.rs]"]
  node_health["Provider health<br/>[health.rs]"]
end

node_user(("Operator"))
node_claude(("Claude Code"))
node_providers["AI providers"]

node_user -->|"runs commands"| node_main
node_main -->|"parses arguments"| node_cli
node_main -->|"loads config"| node_config
node_main -->|"manages profiles"| node_profile
node_main -->|"launches session"| node_process
node_process -->|"starts proxy"| node_proxyserver
node_process -->|"executes with env"| node_claude
node_claude -->|"sends API requests"| node_handler
node_proxyserver -->|"dispatches requests"| node_handler
node_handler -->|"resolves profile"| node_config
node_handler -->|"classifies intent"| node_router
node_handler -->|"preprocesses request"| node_contextengine
node_contextengine -->|"searches index"| node_rag
node_contextengine -->|"loads shared context"| node_sharing
node_contextengine -->|"compresses history"| node_compression
node_handler -->|"selects provider adapter"| node_adapters
node_adapters -->|"translates protocols"| node_translate
node_adapters -->|"forwards requests"| node_providers
node_handler -->|"retries on failure"| node_fallback
node_handler -->|"gets access token"| node_oauthmgr
node_oauthflow -->|"receives callback"| node_oauthserver
node_oauthmgr -->|"loads credentials"| node_oauthflow
node_main -->|"runs auth commands"| node_oauthflow
node_main -->|"manages sets"| node_sets
node_sets -->|"resolves source"| node_setsource
node_sets -->|"installs components"| node_setinstall
node_sets -->|"reads and writes lock"| node_setlock
node_main -->|"opens dashboard"| node_dashboard
node_dashboard -->|"displays metrics"| node_metrics
node_dashboard -->|"displays health"| node_health
node_handler -->|"records requests"| node_metrics
node_handler -->|"tracks provider status"| node_health

click node_main "https://github.com/stringke/claudex/blob/main/src/main.rs"
click node_cli "https://github.com/stringke/claudex/blob/main/src/cli.rs"
click node_process "https://github.com/stringke/claudex/blob/main/src/process/launch.rs"
click node_config "https://github.com/stringke/claudex/blob/main/src/config/mod.rs"
click node_profile "https://github.com/stringke/claudex/blob/main/src/config/profile.rs"
click node_proxyserver "https://github.com/stringke/claudex/blob/main/src/proxy/mod.rs"
click node_handler "https://github.com/stringke/claudex/blob/main/src/proxy/handler.rs"
click node_router "https://github.com/stringke/claudex/blob/main/src/router/classifier.rs"
click node_adapters "https://github.com/stringke/claudex/blob/main/src/proxy/adapter/mod.rs"
click node_translate "https://github.com/stringke/claudex/blob/main/src/proxy/translate/mod.rs"
click node_fallback "https://github.com/stringke/claudex/blob/main/src/proxy/fallback.rs"
click node_oauthmgr "https://github.com/stringke/claudex/blob/main/src/oauth/manager.rs"
click node_oauthflow "https://github.com/stringke/claudex/blob/main/src/oauth/providers.rs"
click node_oauthserver "https://github.com/stringke/claudex/blob/main/src/oauth/server.rs"
click node_contextengine "https://github.com/stringke/claudex/blob/main/src/proxy/context_engine.rs"
click node_rag "https://github.com/stringke/claudex/blob/main/src/context/rag.rs"
click node_sharing "https://github.com/stringke/claudex/blob/main/src/context/sharing.rs"
click node_compression "https://github.com/stringke/claudex/blob/main/src/context/compression.rs"
click node_sets "https://github.com/stringke/claudex/blob/main/src/sets/mod.rs"
click node_setsource "https://github.com/stringke/claudex/blob/main/src/sets/source.rs"
click node_setinstall "https://github.com/stringke/claudex/blob/main/src/sets/install.rs"
click node_setlock "https://github.com/stringke/claudex/blob/main/src/sets/lock.rs"
click node_dashboard "https://github.com/stringke/claudex/blob/main/src/tui/mod.rs"
click node_metrics "https://github.com/stringke/claudex/blob/main/src/proxy/metrics.rs"
click node_health "https://github.com/stringke/claudex/blob/main/src/proxy/health.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_main,node_cli,node_process toneBlue
class node_proxyserver,node_handler,node_router,node_adapters,node_translate,node_fallback toneAmber
class node_contextengine,node_rag,node_sharing,node_compression toneMint
class node_config,node_profile,node_oauthmgr,node_oauthflow,node_oauthserver toneRose
class node_sets,node_setsource,node_setinstall,node_setlock,node_dashboard,node_metrics,node_health,node_user,node_claude,node_providers toneIndigo
```

## Components

### CLI runtime

- [CLI dispatcher](https://github.com/stringke/claudex/blob/main/src/main.rs): `src/main.rs`
- [Command definitions](https://github.com/stringke/claudex/blob/main/src/cli.rs): `src/cli.rs`
- [Launch and daemon](https://github.com/stringke/claudex/blob/main/src/process/launch.rs): `src/process/launch.rs`

### Proxy and providers

- [Proxy server](https://github.com/stringke/claudex/blob/main/src/proxy/mod.rs): `src/proxy/mod.rs`
- [Request handler](https://github.com/stringke/claudex/blob/main/src/proxy/handler.rs): `src/proxy/handler.rs`
- [Intent router](https://github.com/stringke/claudex/blob/main/src/router/classifier.rs): `src/router/classifier.rs`
- [Provider adapters](https://github.com/stringke/claudex/blob/main/src/proxy/adapter/mod.rs): `src/proxy/adapter/mod.rs`
- [Protocol translation](https://github.com/stringke/claudex/blob/main/src/proxy/translate/mod.rs): `src/proxy/translate/mod.rs`
- [Failover logic](https://github.com/stringke/claudex/blob/main/src/proxy/fallback.rs): `src/proxy/fallback.rs`

### Context engine

- [Context preprocessing](https://github.com/stringke/claudex/blob/main/src/proxy/context_engine.rs): `src/proxy/context_engine.rs`
- [Local RAG](https://github.com/stringke/claudex/blob/main/src/context/rag.rs): `src/context/rag.rs`
- [Context sharing](https://github.com/stringke/claudex/blob/main/src/context/sharing.rs): `src/context/sharing.rs`
- [Conversation compression](https://github.com/stringke/claudex/blob/main/src/context/compression.rs): `src/context/compression.rs`

### Profiles and auth

- [Configuration](https://github.com/stringke/claudex/blob/main/src/config/mod.rs): `src/config/mod.rs`
- [Profile management](https://github.com/stringke/claudex/blob/main/src/config/profile.rs): `src/config/profile.rs`
- [OAuth token manager](https://github.com/stringke/claudex/blob/main/src/oauth/manager.rs): `src/oauth/manager.rs`
- [OAuth login flows](https://github.com/stringke/claudex/blob/main/src/oauth/providers.rs): `src/oauth/providers.rs`
- [OAuth callback server](https://github.com/stringke/claudex/blob/main/src/oauth/server.rs): `src/oauth/server.rs`

### Management tools

- [Configuration sets](https://github.com/stringke/claudex/blob/main/src/sets/mod.rs): `src/sets/mod.rs`
- [Set sources](https://github.com/stringke/claudex/blob/main/src/sets/source.rs): `src/sets/source.rs`
- [Set installer](https://github.com/stringke/claudex/blob/main/src/sets/install.rs): `src/sets/install.rs`
- [Set registry](https://github.com/stringke/claudex/blob/main/src/sets/lock.rs): `src/sets/lock.rs`
- [TUI dashboard](https://github.com/stringke/claudex/blob/main/src/tui/mod.rs): `src/tui/mod.rs`
- [Proxy metrics](https://github.com/stringke/claudex/blob/main/src/proxy/metrics.rs): `src/proxy/metrics.rs`
- [Provider health](https://github.com/stringke/claudex/blob/main/src/proxy/health.rs): `src/proxy/health.rs`

### Other components

- **Operator**
- **Claude Code**
- **AI providers**

## Connections

- Operator → CLI dispatcher: runs commands
- CLI dispatcher → Command definitions: parses arguments
- CLI dispatcher → Configuration: loads config
- CLI dispatcher → Profile management: manages profiles
- CLI dispatcher → Launch and daemon: launches session
- Launch and daemon → Proxy server: starts proxy
- Launch and daemon → Claude Code: executes with env
- Claude Code → Request handler: sends API requests
- Proxy server → Request handler: dispatches requests
- Request handler → Configuration: resolves profile
- Request handler → Intent router: classifies intent
- Request handler → Context preprocessing: preprocesses request
- Context preprocessing → Local RAG: searches index
- Context preprocessing → Context sharing: loads shared context
- Context preprocessing → Conversation compression: compresses history
- Request handler → Provider adapters: selects provider adapter
- Provider adapters → Protocol translation: translates protocols
- Provider adapters → AI providers: forwards requests
- Request handler → Failover logic: retries on failure
- Request handler → OAuth token manager: gets access token
- OAuth login flows → OAuth callback server: receives callback
- OAuth token manager → OAuth login flows: loads credentials
- CLI dispatcher → OAuth login flows: runs auth commands
- CLI dispatcher → Configuration sets: manages sets
- Configuration sets → Set sources: resolves source
- Configuration sets → Set installer: installs components
- Configuration sets → Set registry: reads and writes lock
- CLI dispatcher → TUI dashboard: opens dashboard
- TUI dashboard → Proxy metrics: displays metrics
- TUI dashboard → Provider health: displays health
- Request handler → Proxy metrics: records requests
- Request handler → Provider health: tracks provider status