# golapkamal/free-llm-api architecture

> Architecture diagram of the GitHub repository golapkamal/free-llm-api, 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/golapkamal/free-llm-api
- Repository: https://github.com/golapkamal/free-llm-api

## Overview

FreeLLMAPI combines a local dashboard and desktop shell with an OpenAI-compatible inference gateway. A client sends requests to the server’s API routes; the router selects a provider using model, quota, and scoring information, then proxies inference. Separate API branches handle embeddings, media, and synthesis, while management routes expose keys, catalog, analytics, and configuration. The README documents these product capabilities; sampled source and the SOURCE INDEX support only some internal links, so unsampled relationships are omitted rather than inferred.

Main entry points: [`server/src/app.ts`](https://github.com/golapkamal/free-llm-api/blob/main/server/src/app.ts) (HTTP application), [`server/src/services/router.ts`](https://github.com/golapkamal/free-llm-api/blob/main/server/src/services/router.ts) (Model router), [`server/src/services/embeddings.ts`](https://github.com/golapkamal/free-llm-api/blob/main/server/src/services/embeddings.ts) (Embedding routing), [`server/src/routes/proxy.ts`](https://github.com/golapkamal/free-llm-api/blob/main/server/src/routes/proxy.ts) (Chat and proxy APIs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_dashboard["Dashboard"]
  node_dashboard_ui["Dashboard UI<br/>[App.tsx]"]
  node_dashboard_keys["Key management UI<br/>[provider-list.tsx]"]
  node_dashboard_models["Model and playground UI<br/>[PlaygroundPage.tsx]"]
end

subgraph group_gateway["API gateway"]
  node_server["HTTP application<br/>[app.ts]"]
  node_chat_api["Chat and proxy APIs<br/>[proxy.ts]"]
  node_responses_api["Responses API<br/>[responses.ts]"]
  node_anthropic_api["Anthropic API<br/>[anthropic.ts]"]
  node_keys_api["Keys API<br/>[keys.ts]"]
  node_embeddings_api["Embeddings API<br/>[embeddings.ts]"]
  node_media_api["Media API<br/>[media.ts]"]
  node_fusion_api["Fusion API<br/>[fusion.ts]"]
end

subgraph group_inference["Inference"]
  node_router["Model router<br/>[router.ts]"]
  node_providers["Provider adapters"]
  node_proxy_transport["Provider transport<br/>[proxy.ts]"]
  node_embedding_service["Embedding routing<br/>[embeddings.ts]"]
end

subgraph group_state["State and management"]
  node_catalog["Catalog synchronization<br/>[catalog-sync.ts]"]
  node_rate_limits["Quota and rate limits<br/>[ratelimit.ts]"]
  node_database[("SQLite database<br/>[index.ts]")]
  node_crypto["Key encryption<br/>[crypto.ts]"]
  node_analytics["Usage analytics<br/>[analytics.ts]"]
end

subgraph group_desktop["Desktop app"]
  node_desktop_main["Desktop controller<br/>[main.ts]"]
  node_desktop_window["Dashboard window<br/>[window.ts]"]
  node_desktop_tray["System tray<br/>[tray.ts]"]
end

node_client(("API client"))

node_client -->|"sends requests"| node_chat_api
node_client -->|"sends requests"| node_responses_api
node_client -->|"sends requests"| node_anthropic_api
node_server -->|"mounts route"| node_chat_api
node_server -->|"mounts route"| node_responses_api
node_server -->|"mounts route"| node_anthropic_api
node_server -->|"mounts route"| node_keys_api
node_server -->|"mounts route"| node_embeddings_api
node_server -->|"mounts route"| node_media_api
node_chat_api -->|"routes inference"| node_router
node_responses_api -->|"uses same router"| node_router
node_anthropic_api -->|"uses same router"| node_router
node_router -->|"resolves provider"| node_providers
node_router -->|"reads routing state"| node_database
node_router -->|"checks quotas"| node_rate_limits
node_embeddings_api -->|"invokes service"| node_embedding_service
node_embedding_service -->|"reads keys and models"| node_database
node_embedding_service -->|"decrypts keys"| node_crypto
node_embedding_service -->|"sends embedding request"| node_proxy_transport
node_keys_api -->|"encrypts keys"| node_crypto
node_server -->|"initializes store"| node_database
node_server -->|"starts synchronization"| node_catalog
node_dashboard_ui -.->|"manages keys"| node_keys_api
node_desktop_main -->|"builds tray"| node_desktop_tray
node_desktop_tray -->|"opens window"| node_desktop_window

click node_dashboard_ui "https://github.com/golapkamal/free-llm-api/blob/main/client/src/App.tsx"
click node_dashboard_keys "https://github.com/golapkamal/free-llm-api/blob/main/client/src/components/keys/provider-list.tsx"
click node_dashboard_models "https://github.com/golapkamal/free-llm-api/blob/main/client/src/pages/PlaygroundPage.tsx"
click node_server "https://github.com/golapkamal/free-llm-api/blob/main/server/src/app.ts"
click node_chat_api "https://github.com/golapkamal/free-llm-api/blob/main/server/src/routes/proxy.ts"
click node_responses_api "https://github.com/golapkamal/free-llm-api/blob/main/server/src/routes/responses.ts"
click node_anthropic_api "https://github.com/golapkamal/free-llm-api/blob/main/server/src/routes/anthropic.ts"
click node_keys_api "https://github.com/golapkamal/free-llm-api/blob/main/server/src/routes/keys.ts"
click node_embeddings_api "https://github.com/golapkamal/free-llm-api/blob/main/server/src/routes/embeddings.ts"
click node_media_api "https://github.com/golapkamal/free-llm-api/blob/main/server/src/routes/media.ts"
click node_fusion_api "https://github.com/golapkamal/free-llm-api/blob/main/server/src/services/fusion.ts"
click node_router "https://github.com/golapkamal/free-llm-api/blob/main/server/src/services/router.ts"
click node_providers "https://github.com/golapkamal/free-llm-api/tree/main/server/src/providers"
click node_proxy_transport "https://github.com/golapkamal/free-llm-api/blob/main/server/src/lib/proxy.ts"
click node_embedding_service "https://github.com/golapkamal/free-llm-api/blob/main/server/src/services/embeddings.ts"
click node_catalog "https://github.com/golapkamal/free-llm-api/blob/main/server/src/services/catalog-sync.ts"
click node_rate_limits "https://github.com/golapkamal/free-llm-api/blob/main/server/src/services/ratelimit.ts"
click node_database "https://github.com/golapkamal/free-llm-api/blob/main/server/src/db/index.ts"
click node_crypto "https://github.com/golapkamal/free-llm-api/blob/main/server/src/lib/crypto.ts"
click node_analytics "https://github.com/golapkamal/free-llm-api/blob/main/server/src/routes/analytics.ts"
click node_desktop_main "https://github.com/golapkamal/free-llm-api/blob/main/desktop/src/main.ts"
click node_desktop_window "https://github.com/golapkamal/free-llm-api/blob/main/desktop/src/window.ts"
click node_desktop_tray "https://github.com/golapkamal/free-llm-api/blob/main/desktop/src/tray.ts"

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_dashboard_ui,node_dashboard_keys,node_dashboard_models,node_client toneBlue
class node_server,node_chat_api,node_responses_api,node_anthropic_api,node_keys_api,node_embeddings_api,node_media_api,node_fusion_api toneAmber
class node_router,node_providers,node_proxy_transport,node_embedding_service toneMint
class node_catalog,node_rate_limits,node_database,node_crypto,node_analytics toneRose
class node_desktop_main,node_desktop_window,node_desktop_tray toneIndigo
```

## Components

### Dashboard

- [Dashboard UI](https://github.com/golapkamal/free-llm-api/blob/main/client/src/App.tsx): `client/src/App.tsx`
- [Key management UI](https://github.com/golapkamal/free-llm-api/blob/main/client/src/components/keys/provider-list.tsx): `client/src/components/keys/provider-list.tsx`
- [Model and playground UI](https://github.com/golapkamal/free-llm-api/blob/main/client/src/pages/PlaygroundPage.tsx): `client/src/pages/PlaygroundPage.tsx`

### API gateway

- [HTTP application](https://github.com/golapkamal/free-llm-api/blob/main/server/src/app.ts): `server/src/app.ts`
- [Chat and proxy APIs](https://github.com/golapkamal/free-llm-api/blob/main/server/src/routes/proxy.ts): `server/src/routes/proxy.ts`
- [Responses API](https://github.com/golapkamal/free-llm-api/blob/main/server/src/routes/responses.ts): `server/src/routes/responses.ts`
- [Anthropic API](https://github.com/golapkamal/free-llm-api/blob/main/server/src/routes/anthropic.ts): `server/src/routes/anthropic.ts`
- [Keys API](https://github.com/golapkamal/free-llm-api/blob/main/server/src/routes/keys.ts): `server/src/routes/keys.ts`
- [Embeddings API](https://github.com/golapkamal/free-llm-api/blob/main/server/src/routes/embeddings.ts): `server/src/routes/embeddings.ts`
- [Media API](https://github.com/golapkamal/free-llm-api/blob/main/server/src/routes/media.ts): `server/src/routes/media.ts`
- [Fusion API](https://github.com/golapkamal/free-llm-api/blob/main/server/src/services/fusion.ts): `server/src/services/fusion.ts`

### Inference

- [Model router](https://github.com/golapkamal/free-llm-api/blob/main/server/src/services/router.ts): `server/src/services/router.ts`
- [Provider adapters](https://github.com/golapkamal/free-llm-api/tree/main/server/src/providers): `server/src/providers`
- [Provider transport](https://github.com/golapkamal/free-llm-api/blob/main/server/src/lib/proxy.ts): `server/src/lib/proxy.ts`
- [Embedding routing](https://github.com/golapkamal/free-llm-api/blob/main/server/src/services/embeddings.ts): `server/src/services/embeddings.ts`

### State and management

- [Catalog synchronization](https://github.com/golapkamal/free-llm-api/blob/main/server/src/services/catalog-sync.ts): `server/src/services/catalog-sync.ts`
- [Quota and rate limits](https://github.com/golapkamal/free-llm-api/blob/main/server/src/services/ratelimit.ts): `server/src/services/ratelimit.ts`
- [SQLite database](https://github.com/golapkamal/free-llm-api/blob/main/server/src/db/index.ts): `server/src/db/index.ts`
- [Key encryption](https://github.com/golapkamal/free-llm-api/blob/main/server/src/lib/crypto.ts): `server/src/lib/crypto.ts`
- [Usage analytics](https://github.com/golapkamal/free-llm-api/blob/main/server/src/routes/analytics.ts): `server/src/routes/analytics.ts`

### Desktop app

- [Desktop controller](https://github.com/golapkamal/free-llm-api/blob/main/desktop/src/main.ts): `desktop/src/main.ts`
- [Dashboard window](https://github.com/golapkamal/free-llm-api/blob/main/desktop/src/window.ts): `desktop/src/window.ts`
- [System tray](https://github.com/golapkamal/free-llm-api/blob/main/desktop/src/tray.ts): `desktop/src/tray.ts`

### Other components

- **API client**

## Connections

- API client → Chat and proxy APIs: sends requests
- API client → Responses API: sends requests
- API client → Anthropic API: sends requests
- HTTP application → Chat and proxy APIs: mounts route (evidence: `server/src/app.ts`)
- HTTP application → Responses API: mounts route (evidence: `server/src/app.ts`)
- HTTP application → Anthropic API: mounts route (evidence: `server/src/app.ts`)
- HTTP application → Keys API: mounts route (evidence: `server/src/app.ts`)
- HTTP application → Embeddings API: mounts route (evidence: `server/src/app.ts`)
- HTTP application → Media API: mounts route (evidence: `server/src/app.ts`)
- Chat and proxy APIs → Model router: routes inference
- Responses API → Model router: uses same router
- Anthropic API → Model router: uses same router
- Model router → Provider adapters: resolves provider (evidence: `server/src/services/router.ts`)
- Model router → SQLite database: reads routing state (evidence: `server/src/services/router.ts`)
- Model router → Quota and rate limits: checks quotas (evidence: `server/src/services/router.ts`)
- Embeddings API → Embedding routing: invokes service (evidence: `server/src/routes/embeddings.ts`)
- Embedding routing → SQLite database: reads keys and models (evidence: `server/src/services/embeddings.ts`)
- Embedding routing → Key encryption: decrypts keys (evidence: `server/src/services/embeddings.ts`)
- Embedding routing → Provider transport: sends embedding request (evidence: `server/src/services/embeddings.ts`)
- Keys API → Key encryption: encrypts keys
- HTTP application → SQLite database: initializes store (evidence: `server/src/index.ts`)
- HTTP application → Catalog synchronization: starts synchronization (evidence: `server/src/index.ts`)
- Dashboard UI → Keys API: manages keys
- Desktop controller → System tray: builds tray (evidence: `desktop/src/main.ts`)
- System tray → Dashboard window: opens window (evidence: `desktop/src/tray.ts`)