# ssunnykhhetarpal/free-claude-code architecture

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

- Interactive diagram: https://gitdiagram.com/ssunnykhhetarpal/free-claude-code
- Repository: https://github.com/ssunnykhhetarpal/free-claude-code

## Overview

Free Claude Code is a local model-routing gateway and coding-agent integration suite. A user configures providers and model policy in the Admin UI, launches a supported harness or connects an API client, and requests are routed through protocol adapters to provider implementations with streaming responses. Separate product branches provide native code sessions, desktop/IDE integrations, and Discord/Telegram messaging. The README documents breadth beyond sampled source; those branches are represented at their supported directory paths, while edges are limited to visible imports or documented workflows.

Main entry points: [`src/free_claude_code/api/routes.py`](https://github.com/ssunnykhhetarpal/free-claude-code/blob/main/src/free_claude_code/api/routes.py) (API routes), [`src/free_claude_code/runtime/provider_manager.py`](https://github.com/ssunnykhhetarpal/free-claude-code/blob/main/src/free_claude_code/runtime/provider_manager.py) (Provider runtime), [`src/free_claude_code/api/admin_routes.py`](https://github.com/ssunnykhhetarpal/free-claude-code/blob/main/src/free_claude_code/api/admin_routes.py) (Admin UI), [`src/free_claude_code/cli/launchers`](https://github.com/ssunnykhhetarpal/free-claude-code/tree/main/src/free_claude_code/cli/launchers) (Harness launchers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Clients and entrypoints"]
  node_coding_clients(("Coding clients"))
  node_cli_launchers["Harness launchers"]
  node_server["Local server<br/>[uvicorn_server.py]"]
end

subgraph group_gateway["Gateway and routing"]
  node_api_routes["API routes<br/>[routes.py]"]
  node_api_handlers["Protocol handlers"]
  node_router["Model routing<br/>[routing.py]"]
  node_protocols["Protocol conversion"]
  node_runtime["Application runtime<br/>[application.py]"]
end

subgraph group_providers["Providers and models"]
  node_provider_manager["Provider runtime"]
  node_provider_adapters["Provider adapters"]
  node_provider_catalog["Provider catalog"]
end

subgraph group_management["Configuration and integrations"]
  node_admin_ui["Admin UI<br/>[admin_routes.py]"]
  node_settings["Settings and model policy<br/>[settings.py]"]
  node_harness_integrations["Harness integrations"]
end

subgraph group_sessions["Sessions and messaging"]
  node_code_sessions["Browser code sessions"]
  node_session_api["Code session API"]
  node_messaging["Chat platforms"]
  node_messaging_storage[("Messaging storage")]
  node_code_storage[("Session storage")]
end

node_user(("User"))
node_provider_services(("Model providers"))
node_chat_platforms(("Discord and Telegram"))

node_user -->|"launches harness"| node_cli_launchers
node_coding_clients -->|"sends requests"| node_api_routes
node_cli_launchers -.->|"uses local proxy"| node_server
node_server -.->|"serves API"| node_api_routes
node_api_routes -->|"dispatches"| node_api_handlers
node_api_routes -->|"resolves models"| node_router
node_api_routes -->|"uses protocol adapters"| node_protocols
node_api_routes -->|"uses application ports"| node_runtime
node_runtime -->|"manages providers"| node_provider_manager
node_provider_manager -->|"creates provider runtime"| node_provider_adapters
node_provider_manager -->|"discovers providers"| node_provider_catalog
node_provider_adapters -.->|"sends model requests"| node_provider_services
node_user -->|"configures gateway"| node_admin_ui
node_admin_ui -.->|"updates model config"| node_settings
node_admin_ui -->|"manages integrations"| node_harness_integrations
node_user -->|"opens code session"| node_session_api
node_session_api -->|"delegates session work"| node_code_sessions
node_code_sessions -.->|"persists session state"| node_code_storage
node_chat_platforms -->|"sends messages"| node_messaging
node_messaging -.->|"persists messaging state"| node_messaging_storage

click node_cli_launchers "https://github.com/ssunnykhhetarpal/free-claude-code/tree/main/src/free_claude_code/cli/launchers"
click node_server "https://github.com/ssunnykhhetarpal/free-claude-code/blob/main/src/free_claude_code/cli/uvicorn_server.py"
click node_api_routes "https://github.com/ssunnykhhetarpal/free-claude-code/blob/main/src/free_claude_code/api/routes.py"
click node_api_handlers "https://github.com/ssunnykhhetarpal/free-claude-code/tree/main/src/free_claude_code/api/handlers"
click node_router "https://github.com/ssunnykhhetarpal/free-claude-code/blob/main/src/free_claude_code/application/routing.py"
click node_protocols "https://github.com/ssunnykhhetarpal/free-claude-code/tree/main/src/free_claude_code/core"
click node_runtime "https://github.com/ssunnykhhetarpal/free-claude-code/blob/main/src/free_claude_code/runtime/application.py"
click node_provider_manager "https://github.com/ssunnykhhetarpal/free-claude-code/blob/main/src/free_claude_code/runtime/provider_manager.py"
click node_provider_adapters "https://github.com/ssunnykhhetarpal/free-claude-code/tree/main/src/free_claude_code/providers"
click node_provider_catalog "https://github.com/ssunnykhhetarpal/free-claude-code/blob/main/src/free_claude_code/config/provider_catalog.py"
click node_admin_ui "https://github.com/ssunnykhhetarpal/free-claude-code/blob/main/src/free_claude_code/api/admin_routes.py"
click node_settings "https://github.com/ssunnykhhetarpal/free-claude-code/blob/main/src/free_claude_code/config/settings.py"
click node_harness_integrations "https://github.com/ssunnykhhetarpal/free-claude-code/tree/main/src/free_claude_code/harnesses"
click node_code_sessions "https://github.com/ssunnykhhetarpal/free-claude-code/tree/main/src/free_claude_code/application/code_sessions"
click node_session_api "https://github.com/ssunnykhhetarpal/free-claude-code/blob/main/src/free_claude_code/api/code_sessions_routes.py"
click node_messaging "https://github.com/ssunnykhhetarpal/free-claude-code/tree/main/src/free_claude_code/messaging"
click node_messaging_storage "https://github.com/ssunnykhhetarpal/free-claude-code/blob/main/src/free_claude_code/runtime/messaging_sqlite.py"
click node_code_storage "https://github.com/ssunnykhhetarpal/free-claude-code/blob/main/src/free_claude_code/runtime/code_sessions_sqlite.py"

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_coding_clients,node_cli_launchers,node_server,node_user toneBlue
class node_api_routes,node_api_handlers,node_router,node_protocols,node_runtime toneAmber
class node_provider_manager,node_provider_adapters,node_provider_catalog toneMint
class node_admin_ui,node_settings,node_harness_integrations toneRose
class node_code_sessions,node_session_api,node_messaging,node_messaging_storage,node_code_storage,node_provider_services,node_chat_platforms toneIndigo
```

## Components

### Clients and entrypoints

- **Coding clients**
- [Harness launchers](https://github.com/ssunnykhhetarpal/free-claude-code/tree/main/src/free_claude_code/cli/launchers): `src/free_claude_code/cli/launchers`
- [Local server](https://github.com/ssunnykhhetarpal/free-claude-code/blob/main/src/free_claude_code/cli/uvicorn_server.py): `src/free_claude_code/cli/uvicorn_server.py`

### Gateway and routing

- [API routes](https://github.com/ssunnykhhetarpal/free-claude-code/blob/main/src/free_claude_code/api/routes.py): `src/free_claude_code/api/routes.py`
- [Protocol handlers](https://github.com/ssunnykhhetarpal/free-claude-code/tree/main/src/free_claude_code/api/handlers): `src/free_claude_code/api/handlers`
- [Model routing](https://github.com/ssunnykhhetarpal/free-claude-code/blob/main/src/free_claude_code/application/routing.py): `src/free_claude_code/application/routing.py`
- [Protocol conversion](https://github.com/ssunnykhhetarpal/free-claude-code/tree/main/src/free_claude_code/core): `src/free_claude_code/core`
- [Application runtime](https://github.com/ssunnykhhetarpal/free-claude-code/blob/main/src/free_claude_code/runtime/application.py): `src/free_claude_code/runtime/application.py`

### Providers and models

- [Provider runtime](https://github.com/ssunnykhhetarpal/free-claude-code/blob/main/src/free_claude_code/runtime/provider_manager.py): `src/free_claude_code/runtime/provider_manager.py`
- [Provider adapters](https://github.com/ssunnykhhetarpal/free-claude-code/tree/main/src/free_claude_code/providers): `src/free_claude_code/providers`
- [Provider catalog](https://github.com/ssunnykhhetarpal/free-claude-code/blob/main/src/free_claude_code/config/provider_catalog.py): `src/free_claude_code/config/provider_catalog.py`

### Configuration and integrations

- [Admin UI](https://github.com/ssunnykhhetarpal/free-claude-code/blob/main/src/free_claude_code/api/admin_routes.py): `src/free_claude_code/api/admin_routes.py`
- [Settings and model policy](https://github.com/ssunnykhhetarpal/free-claude-code/blob/main/src/free_claude_code/config/settings.py): `src/free_claude_code/config/settings.py`
- [Harness integrations](https://github.com/ssunnykhhetarpal/free-claude-code/tree/main/src/free_claude_code/harnesses): `src/free_claude_code/harnesses`

### Sessions and messaging

- [Browser code sessions](https://github.com/ssunnykhhetarpal/free-claude-code/tree/main/src/free_claude_code/application/code_sessions): `src/free_claude_code/application/code_sessions`
- [Code session API](https://github.com/ssunnykhhetarpal/free-claude-code/blob/main/src/free_claude_code/api/code_sessions_routes.py): `src/free_claude_code/api/code_sessions_routes.py`
- [Chat platforms](https://github.com/ssunnykhhetarpal/free-claude-code/tree/main/src/free_claude_code/messaging): `src/free_claude_code/messaging`
- [Messaging storage](https://github.com/ssunnykhhetarpal/free-claude-code/blob/main/src/free_claude_code/runtime/messaging_sqlite.py): `src/free_claude_code/runtime/messaging_sqlite.py`
- [Session storage](https://github.com/ssunnykhhetarpal/free-claude-code/blob/main/src/free_claude_code/runtime/code_sessions_sqlite.py): `src/free_claude_code/runtime/code_sessions_sqlite.py`

### Other components

- **User**
- **Model providers**
- **Discord and Telegram**

## Connections

- User → Harness launchers: launches harness
- Coding clients → API routes: sends requests
- Harness launchers → Local server: uses local proxy
- Local server → API routes: serves API
- API routes → Protocol handlers: dispatches (evidence: `src/free_claude_code/api/routes.py`)
- API routes → Model routing: resolves models (evidence: `src/free_claude_code/api/routes.py`)
- API routes → Protocol conversion: uses protocol adapters (evidence: `src/free_claude_code/api/routes.py`)
- API routes → Application runtime: uses application ports (evidence: `src/free_claude_code/api/routes.py`)
- Application runtime → Provider runtime: manages providers (evidence: `src/free_claude_code/runtime/application.py`)
- Provider runtime → Provider adapters: creates provider runtime (evidence: `src/free_claude_code/runtime/provider_manager.py`)
- Provider runtime → Provider catalog: discovers providers (evidence: `src/free_claude_code/runtime/provider_manager.py`)
- Provider adapters → Model providers: sends model requests
- User → Admin UI: configures gateway
- Admin UI → Settings and model policy: updates model config
- Admin UI → Harness integrations: manages integrations (evidence: `src/free_claude_code/api/admin_routes.py`)
- User → Code session API: opens code session
- Code session API → Browser code sessions: delegates session work (evidence: `src/free_claude_code/api/code_sessions_routes.py`)
- Browser code sessions → Session storage: persists session state
- Discord and Telegram → Chat platforms: sends messages
- Chat platforms → Messaging storage: persists messaging state