# sivanesh-murugasamy/free-claude-code architecture

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

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

## Overview

Free Claude Code is a local model gateway and coding-agent launcher, with an Admin UI for provider setup and optional Discord/Telegram agent workflows. The main path is client or launcher → API → model routing → provider adapter → streamed Anthropic-compatible response. Runtime wiring and API routing are supported by the source index; additional capabilities such as desktop launch and messaging are documented in the README, but their detailed internal links are not inferred from unsampled code.

Main entry points: [`src/free_claude_code/api/routes.py`](https://github.com/sivanesh-murugasamy/free-claude-code/blob/main/src/free_claude_code/api/routes.py) (HTTP API routes), [`src/free_claude_code/runtime/application.py`](https://github.com/sivanesh-murugasamy/free-claude-code/blob/main/src/free_claude_code/runtime/application.py) (Application runtime), [`src/free_claude_code/providers/nvidia_nim/client.py`](https://github.com/sivanesh-murugasamy/free-claude-code/blob/main/src/free_claude_code/providers/nvidia_nim/client.py) (Provider adapters), [`src/free_claude_code/application/routing.py`](https://github.com/sivanesh-murugasamy/free-claude-code/blob/main/src/free_claude_code/application/routing.py) (Model routing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Client entrypoints"]
  node_launchers["Agent launchers<br/>[claude.py]"]
  node_desktop["Desktop controls<br/>[desktop.py]"]
end

subgraph group_admin["Configuration and runtime"]
  node_adminui["Admin UI<br/>[admin_routes.py]"]
  node_settings["Settings and catalog<br/>[settings.py]"]
  node_runtime["Application runtime<br/>[application.py]"]
  node_provider_catalog["Provider catalog"]
end

subgraph group_gateway["Gateway and protocols"]
  node_api["HTTP API routes<br/>[routes.py]"]
  node_message_handler["Messages handler<br/>[messages.py]"]
  node_responses_handler["Responses handler<br/>[responses.py]"]
  node_anthropic_protocol["Anthropic protocol<br/>[models.py]"]
  node_reasoning["Reasoning policy<br/>[reasoning.py]"]
  node_routing["Model routing<br/>[routing.py]"]
end

subgraph group_providers["Provider execution"]
  node_provider_manager["Provider manager"]
  node_provider_factory["Provider construction<br/>[factory.py]"]
  node_provider_runtime["Provider discovery<br/>[discovery.py]"]
  node_provider_interface["Provider interface<br/>[base.py]"]
  node_admission["Admission and retry<br/>[admission.py]"]
  node_provider_clients["Provider adapters<br/>[client.py]"]
end

subgraph group_messaging["Messaging agents"]
  node_messaging["Messaging workflow<br/>[workflow.py]"]
  node_platforms["Chat platforms<br/>[factory.py]"]
  node_trees["Conversation trees<br/>[manager.py]"]
end

node_client(("Coding agent"))
node_upstream(("Model services"))

node_client -.->|"launches"| node_launchers
node_launchers -.->|"uses settings"| node_runtime
node_desktop -.->|"controls"| node_runtime
node_client -.->|"sends requests"| node_api
node_api -->|"routes requests"| node_message_handler
node_api -->|"routes requests"| node_responses_handler
node_api -->|"uses model routing"| node_routing
node_message_handler -.->|"handles protocol"| node_anthropic_protocol
node_responses_handler -.->|"adapts protocol"| node_anthropic_protocol
node_routing -->|"resolves policy"| node_reasoning
node_routing -->|"resolves provider"| node_provider_catalog
node_runtime -->|"configures"| node_provider_manager
node_runtime -->|"loads configuration"| node_settings
node_provider_manager -->|"discovers models"| node_provider_runtime
node_provider_manager -->|"uses metadata"| node_provider_catalog
node_provider_runtime -.->|"builds providers"| node_provider_factory
node_provider_factory -.->|"constructs adapters"| node_provider_interface
node_provider_clients -->|"implements"| node_provider_interface
node_provider_clients -->|"coordinates attempts"| node_admission
node_provider_clients -.->|"calls model service"| node_upstream
node_adminui -->|"manages configuration"| node_settings
node_adminui -->|"browses providers"| node_provider_catalog
node_messaging -.->|"uses platform adapters"| node_platforms
node_messaging -.->|"coordinates conversations"| node_trees
node_client -.->|"uses optional bots"| node_messaging

click node_launchers "https://github.com/sivanesh-murugasamy/free-claude-code/blob/main/src/free_claude_code/cli/launchers/claude.py"
click node_desktop "https://github.com/sivanesh-murugasamy/free-claude-code/blob/main/src/free_claude_code/cli/desktop.py"
click node_adminui "https://github.com/sivanesh-murugasamy/free-claude-code/blob/main/src/free_claude_code/api/admin_routes.py"
click node_settings "https://github.com/sivanesh-murugasamy/free-claude-code/blob/main/src/free_claude_code/config/settings.py"
click node_runtime "https://github.com/sivanesh-murugasamy/free-claude-code/blob/main/src/free_claude_code/runtime/application.py"
click node_provider_manager "https://github.com/sivanesh-murugasamy/free-claude-code/blob/main/src/free_claude_code/runtime/provider_manager.py"
click node_api "https://github.com/sivanesh-murugasamy/free-claude-code/blob/main/src/free_claude_code/api/routes.py"
click node_message_handler "https://github.com/sivanesh-murugasamy/free-claude-code/blob/main/src/free_claude_code/api/handlers/messages.py"
click node_responses_handler "https://github.com/sivanesh-murugasamy/free-claude-code/blob/main/src/free_claude_code/api/handlers/responses.py"
click node_anthropic_protocol "https://github.com/sivanesh-murugasamy/free-claude-code/blob/main/src/free_claude_code/core/anthropic/models.py"
click node_reasoning "https://github.com/sivanesh-murugasamy/free-claude-code/blob/main/src/free_claude_code/core/reasoning.py"
click node_routing "https://github.com/sivanesh-murugasamy/free-claude-code/blob/main/src/free_claude_code/application/routing.py"
click node_provider_catalog "https://github.com/sivanesh-murugasamy/free-claude-code/blob/main/src/free_claude_code/config/provider_catalog.py"
click node_provider_factory "https://github.com/sivanesh-murugasamy/free-claude-code/blob/main/src/free_claude_code/providers/runtime/factory.py"
click node_provider_runtime "https://github.com/sivanesh-murugasamy/free-claude-code/blob/main/src/free_claude_code/providers/runtime/discovery.py"
click node_provider_interface "https://github.com/sivanesh-murugasamy/free-claude-code/blob/main/src/free_claude_code/providers/base.py"
click node_admission "https://github.com/sivanesh-murugasamy/free-claude-code/blob/main/src/free_claude_code/providers/admission.py"
click node_provider_clients "https://github.com/sivanesh-murugasamy/free-claude-code/blob/main/src/free_claude_code/providers/nvidia_nim/client.py"
click node_messaging "https://github.com/sivanesh-murugasamy/free-claude-code/blob/main/src/free_claude_code/messaging/workflow.py"
click node_platforms "https://github.com/sivanesh-murugasamy/free-claude-code/blob/main/src/free_claude_code/messaging/platforms/factory.py"
click node_trees "https://github.com/sivanesh-murugasamy/free-claude-code/blob/main/src/free_claude_code/messaging/trees/manager.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_launchers,node_desktop toneBlue
class node_adminui,node_settings,node_runtime,node_provider_catalog toneAmber
class node_api,node_message_handler,node_responses_handler,node_anthropic_protocol,node_reasoning,node_routing toneMint
class node_provider_manager,node_provider_factory,node_provider_runtime,node_provider_interface,node_admission,node_provider_clients toneRose
class node_messaging,node_platforms,node_trees,node_client,node_upstream toneIndigo
```

## Components

### Client entrypoints

- [Agent launchers](https://github.com/sivanesh-murugasamy/free-claude-code/blob/main/src/free_claude_code/cli/launchers/claude.py): `src/free_claude_code/cli/launchers/claude.py`
- [Desktop controls](https://github.com/sivanesh-murugasamy/free-claude-code/blob/main/src/free_claude_code/cli/desktop.py): `src/free_claude_code/cli/desktop.py`

### Configuration and runtime

- [Admin UI](https://github.com/sivanesh-murugasamy/free-claude-code/blob/main/src/free_claude_code/api/admin_routes.py): `src/free_claude_code/api/admin_routes.py`
- [Settings and catalog](https://github.com/sivanesh-murugasamy/free-claude-code/blob/main/src/free_claude_code/config/settings.py): `src/free_claude_code/config/settings.py`
- [Application runtime](https://github.com/sivanesh-murugasamy/free-claude-code/blob/main/src/free_claude_code/runtime/application.py): `src/free_claude_code/runtime/application.py`
- [Provider catalog](https://github.com/sivanesh-murugasamy/free-claude-code/blob/main/src/free_claude_code/config/provider_catalog.py): `src/free_claude_code/config/provider_catalog.py`

### Gateway and protocols

- [HTTP API routes](https://github.com/sivanesh-murugasamy/free-claude-code/blob/main/src/free_claude_code/api/routes.py): `src/free_claude_code/api/routes.py`
- [Messages handler](https://github.com/sivanesh-murugasamy/free-claude-code/blob/main/src/free_claude_code/api/handlers/messages.py): `src/free_claude_code/api/handlers/messages.py`
- [Responses handler](https://github.com/sivanesh-murugasamy/free-claude-code/blob/main/src/free_claude_code/api/handlers/responses.py): `src/free_claude_code/api/handlers/responses.py`
- [Anthropic protocol](https://github.com/sivanesh-murugasamy/free-claude-code/blob/main/src/free_claude_code/core/anthropic/models.py): `src/free_claude_code/core/anthropic/models.py`
- [Reasoning policy](https://github.com/sivanesh-murugasamy/free-claude-code/blob/main/src/free_claude_code/core/reasoning.py): `src/free_claude_code/core/reasoning.py`
- [Model routing](https://github.com/sivanesh-murugasamy/free-claude-code/blob/main/src/free_claude_code/application/routing.py): `src/free_claude_code/application/routing.py`

### Provider execution

- [Provider manager](https://github.com/sivanesh-murugasamy/free-claude-code/blob/main/src/free_claude_code/runtime/provider_manager.py): `src/free_claude_code/runtime/provider_manager.py`
- [Provider construction](https://github.com/sivanesh-murugasamy/free-claude-code/blob/main/src/free_claude_code/providers/runtime/factory.py): `src/free_claude_code/providers/runtime/factory.py`
- [Provider discovery](https://github.com/sivanesh-murugasamy/free-claude-code/blob/main/src/free_claude_code/providers/runtime/discovery.py): `src/free_claude_code/providers/runtime/discovery.py`
- [Provider interface](https://github.com/sivanesh-murugasamy/free-claude-code/blob/main/src/free_claude_code/providers/base.py): `src/free_claude_code/providers/base.py`
- [Admission and retry](https://github.com/sivanesh-murugasamy/free-claude-code/blob/main/src/free_claude_code/providers/admission.py): `src/free_claude_code/providers/admission.py`
- [Provider adapters](https://github.com/sivanesh-murugasamy/free-claude-code/blob/main/src/free_claude_code/providers/nvidia_nim/client.py): `src/free_claude_code/providers/nvidia_nim/client.py`

### Messaging agents

- [Messaging workflow](https://github.com/sivanesh-murugasamy/free-claude-code/blob/main/src/free_claude_code/messaging/workflow.py): `src/free_claude_code/messaging/workflow.py`
- [Chat platforms](https://github.com/sivanesh-murugasamy/free-claude-code/blob/main/src/free_claude_code/messaging/platforms/factory.py): `src/free_claude_code/messaging/platforms/factory.py`
- [Conversation trees](https://github.com/sivanesh-murugasamy/free-claude-code/blob/main/src/free_claude_code/messaging/trees/manager.py): `src/free_claude_code/messaging/trees/manager.py`

### Other components

- **Coding agent**
- **Model services**

## Connections

- Coding agent → Agent launchers: launches (evidence: `README.md`)
- Agent launchers → Application runtime: uses settings (evidence: `README.md`)
- Desktop controls → Application runtime: controls (evidence: `README.md`)
- Coding agent → HTTP API routes: sends requests (evidence: `README.md`)
- HTTP API routes → Messages handler: routes requests (evidence: `src/free_claude_code/api/routes.py`)
- HTTP API routes → Responses handler: routes requests (evidence: `src/free_claude_code/api/routes.py`)
- HTTP API routes → Model routing: uses model routing (evidence: `src/free_claude_code/api/routes.py`)
- Messages handler → Anthropic protocol: handles protocol
- Responses handler → Anthropic protocol: adapts protocol
- Model routing → Reasoning policy: resolves policy (evidence: `src/free_claude_code/application/routing.py`)
- Model routing → Provider catalog: resolves provider (evidence: `src/free_claude_code/application/routing.py`)
- Application runtime → Provider manager: configures (evidence: `src/free_claude_code/runtime/application.py`)
- Application runtime → Settings and catalog: loads configuration (evidence: `src/free_claude_code/runtime/application.py`)
- Provider manager → Provider discovery: discovers models (evidence: `src/free_claude_code/runtime/provider_manager.py`)
- Provider manager → Provider catalog: uses metadata (evidence: `src/free_claude_code/runtime/provider_manager.py`)
- Provider discovery → Provider construction: builds providers
- Provider construction → Provider interface: constructs adapters
- Provider adapters → Provider interface: implements (evidence: `src/free_claude_code/providers/nvidia_nim/client.py`)
- Provider adapters → Admission and retry: coordinates attempts (evidence: `src/free_claude_code/providers/nvidia_nim/client.py`)
- Provider adapters → Model services: calls model service
- Admin UI → Settings and catalog: manages configuration (evidence: `src/free_claude_code/api/admin_routes.py`)
- Admin UI → Provider catalog: browses providers (evidence: `src/free_claude_code/api/admin_routes.py`)
- Messaging workflow → Chat platforms: uses platform adapters
- Messaging workflow → Conversation trees: coordinates conversations
- Coding agent → Messaging workflow: uses optional bots (evidence: `README.md`)
