# premable/free-claude-code architecture

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

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

## Overview

Free Claude Code is a local AI coding gateway: users connect coding harnesses and clients, configure providers and models, then send requests through protocol-compatible APIs for upstream model responses. The map also includes administration, native browser code sessions, messaging, and harness integrations documented as product capabilities. Source excerpts support key API, routing, and provider-runtime links; several broader features are represented from the README and tree, so their internal wiring is not inferred.

Main entry points: [`src/free_claude_code/application/routing.py`](https://github.com/premable/free-claude-code/blob/main/src/free_claude_code/application/routing.py) (Model Routing), [`src/free_claude_code/api/routes.py`](https://github.com/premable/free-claude-code/blob/main/src/free_claude_code/api/routes.py) (Protocol API), [`src/free_claude_code/providers`](https://github.com/premable/free-claude-code/tree/main/src/free_claude_code/providers) (Provider Adapters), [`src/free_claude_code/api/admin_routes.py`](https://github.com/premable/free-claude-code/blob/main/src/free_claude_code/api/admin_routes.py) (Admin APIs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Gateway API"]
  node_api["Protocol API<br/>[routes.py]"]
  node_protocol["Protocol Adapters"]
end

subgraph group_routing["Models And Providers"]
  node_router["Model Routing<br/>[routing.py]"]
  node_modelrefs["Model References<br/>[model_refs.py]"]
  node_catalog["Provider Catalog"]
  node_provider_runtime["Provider Runtime"]
  node_provider_adapters["Provider Adapters"]
end

subgraph group_admin["Configuration And Admin"]
  node_settings["Model Settings<br/>[settings.py]"]
  node_admin_ui["Admin APIs<br/>[admin_routes.py]"]
  node_runtime["Application Runtime<br/>[application.py]"]
end

subgraph group_sessions["Sessions And Messaging"]
  node_code_sessions["Browser Code Sessions<br/>[service.py]"]
  node_session_api["Code Session API"]
  node_messaging["Phone Messaging<br/>[workflow.py]"]
end

subgraph group_clients["Client Integrations"]
  node_harness["Coding Harnesses"]
  node_cli["Launch Commands<br/>[runner.py]"]
  node_desktop["Desktop App<br/>[desktop.py]"]
end

node_user(("User"))
node_external_providers{{"Model Providers"}}

node_user -->|"uses"| node_harness
node_harness -.->|"launches through"| node_cli
node_cli -.->|"sends requests"| node_api
node_api -->|"resolves models"| node_router
node_api -->|"adapts protocols"| node_protocol
node_router -->|"reads settings"| node_settings
node_router -->|"parses model refs"| node_modelrefs
node_router -->|"consults catalog"| node_catalog
node_provider_runtime -->|"discovers providers"| node_provider_adapters
node_provider_adapters -.->|"calls upstream"| node_external_providers
node_user -->|"configures gateway"| node_admin_ui
node_admin_ui -->|"uses services"| node_runtime
node_user -->|"uses browser sessions"| node_code_sessions
node_session_api -->|"serves sessions"| node_code_sessions
node_user -->|"messages via phone"| node_messaging
node_user -->|"uses desktop app"| node_desktop

click node_harness "https://github.com/premable/free-claude-code/tree/main/src/free_claude_code/harnesses"
click node_cli "https://github.com/premable/free-claude-code/blob/main/src/free_claude_code/cli/launchers/runner.py"
click node_api "https://github.com/premable/free-claude-code/blob/main/src/free_claude_code/api/routes.py"
click node_protocol "https://github.com/premable/free-claude-code/tree/main/src/free_claude_code/core/anthropic"
click node_router "https://github.com/premable/free-claude-code/blob/main/src/free_claude_code/application/routing.py"
click node_settings "https://github.com/premable/free-claude-code/blob/main/src/free_claude_code/config/settings.py"
click node_modelrefs "https://github.com/premable/free-claude-code/blob/main/src/free_claude_code/config/model_refs.py"
click node_catalog "https://github.com/premable/free-claude-code/blob/main/src/free_claude_code/config/provider_catalog.py"
click node_provider_runtime "https://github.com/premable/free-claude-code/blob/main/src/free_claude_code/runtime/provider_manager.py"
click node_provider_adapters "https://github.com/premable/free-claude-code/tree/main/src/free_claude_code/providers"
click node_admin_ui "https://github.com/premable/free-claude-code/blob/main/src/free_claude_code/api/admin_routes.py"
click node_runtime "https://github.com/premable/free-claude-code/blob/main/src/free_claude_code/runtime/application.py"
click node_code_sessions "https://github.com/premable/free-claude-code/blob/main/src/free_claude_code/application/code_sessions/service.py"
click node_session_api "https://github.com/premable/free-claude-code/blob/main/src/free_claude_code/api/code_sessions_routes.py"
click node_messaging "https://github.com/premable/free-claude-code/blob/main/src/free_claude_code/messaging/workflow.py"
click node_desktop "https://github.com/premable/free-claude-code/blob/main/src/free_claude_code/cli/desktop.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_api,node_protocol,node_user toneBlue
class node_router,node_modelrefs,node_catalog,node_provider_runtime,node_provider_adapters toneAmber
class node_settings,node_admin_ui,node_runtime toneMint
class node_code_sessions,node_session_api,node_messaging toneRose
class node_harness,node_cli,node_desktop,node_external_providers toneIndigo
```

## Components

### Gateway API

- [Protocol API](https://github.com/premable/free-claude-code/blob/main/src/free_claude_code/api/routes.py): `src/free_claude_code/api/routes.py`
- [Protocol Adapters](https://github.com/premable/free-claude-code/tree/main/src/free_claude_code/core/anthropic): `src/free_claude_code/core/anthropic`

### Models And Providers

- [Model Routing](https://github.com/premable/free-claude-code/blob/main/src/free_claude_code/application/routing.py): `src/free_claude_code/application/routing.py`
- [Model References](https://github.com/premable/free-claude-code/blob/main/src/free_claude_code/config/model_refs.py): `src/free_claude_code/config/model_refs.py`
- [Provider Catalog](https://github.com/premable/free-claude-code/blob/main/src/free_claude_code/config/provider_catalog.py): `src/free_claude_code/config/provider_catalog.py`
- [Provider Runtime](https://github.com/premable/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/premable/free-claude-code/tree/main/src/free_claude_code/providers): `src/free_claude_code/providers`

### Configuration And Admin

- [Model Settings](https://github.com/premable/free-claude-code/blob/main/src/free_claude_code/config/settings.py): `src/free_claude_code/config/settings.py`
- [Admin APIs](https://github.com/premable/free-claude-code/blob/main/src/free_claude_code/api/admin_routes.py): `src/free_claude_code/api/admin_routes.py`
- [Application Runtime](https://github.com/premable/free-claude-code/blob/main/src/free_claude_code/runtime/application.py): `src/free_claude_code/runtime/application.py`

### Sessions And Messaging

- [Browser Code Sessions](https://github.com/premable/free-claude-code/blob/main/src/free_claude_code/application/code_sessions/service.py): `src/free_claude_code/application/code_sessions/service.py`
- [Code Session API](https://github.com/premable/free-claude-code/blob/main/src/free_claude_code/api/code_sessions_routes.py): `src/free_claude_code/api/code_sessions_routes.py`
- [Phone Messaging](https://github.com/premable/free-claude-code/blob/main/src/free_claude_code/messaging/workflow.py): `src/free_claude_code/messaging/workflow.py`

### Client Integrations

- [Coding Harnesses](https://github.com/premable/free-claude-code/tree/main/src/free_claude_code/harnesses): `src/free_claude_code/harnesses`
- [Launch Commands](https://github.com/premable/free-claude-code/blob/main/src/free_claude_code/cli/launchers/runner.py): `src/free_claude_code/cli/launchers/runner.py`
- [Desktop App](https://github.com/premable/free-claude-code/blob/main/src/free_claude_code/cli/desktop.py): `src/free_claude_code/cli/desktop.py`

### Other components

- **User**
- **Model Providers**

## Connections

- User → Coding Harnesses: uses (evidence: `README.md`)
- Coding Harnesses → Launch Commands: launches through
- Launch Commands → Protocol API: sends requests
- Protocol API → Model Routing: resolves models (evidence: `src/free_claude_code/api/routes.py`)
- Protocol API → Protocol Adapters: adapts protocols (evidence: `src/free_claude_code/api/routes.py`)
- Model Routing → Model Settings: reads settings (evidence: `src/free_claude_code/application/routing.py`)
- Model Routing → Model References: parses model refs (evidence: `src/free_claude_code/application/routing.py`)
- Model Routing → Provider Catalog: consults catalog (evidence: `src/free_claude_code/application/routing.py`)
- Provider Runtime → Provider Adapters: discovers providers (evidence: `src/free_claude_code/runtime/provider_manager.py`)
- Provider Adapters → Model Providers: calls upstream
- User → Admin APIs: configures gateway (evidence: `README.md`)
- Admin APIs → Application Runtime: uses services (evidence: `src/free_claude_code/api/admin_routes.py`)
- User → Browser Code Sessions: uses browser sessions (evidence: `README.md`)
- Code Session API → Browser Code Sessions: serves sessions (evidence: `src/free_claude_code/api/code_sessions_routes.py`)
- User → Phone Messaging: messages via phone (evidence: `README.md`)
- User → Desktop App: uses desktop app (evidence: `README.md`)