# lov0u/freellmapi architecture

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

- Interactive diagram: https://gitdiagram.com/lov0u/freellmapi
- Repository: https://github.com/lov0u/freellmapi

## Overview

FreeLLMAPI aggregates free and custom model providers behind a unified API, with a dashboard and desktop app for setup and administration. The main workflow is a client request entering the server, being routed to an available provider, and returning through a compatible API. The README also documents catalog updates, prompt compression, analytics, media and embedding endpoints, and CLI setup tools. The graph uses README and SOURCE INDEX evidence; several route and integration details are unsampled, so their links are limited to documented relationships.

Main entry points: [`server/src/services/router.ts`](https://github.com/lov0u/freellmapi/blob/main/server/src/services/router.ts) (Model router), [`server/src/app.ts`](https://github.com/lov0u/freellmapi/blob/main/server/src/app.ts) (HTTP application), [`desktop/src/main.ts`](https://github.com/lov0u/freellmapi/blob/main/desktop/src/main.ts) (Desktop app), [`server/src/providers/base.ts`](https://github.com/lov0u/freellmapi/blob/main/server/src/providers/base.ts) (Provider adapters)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_server["API and routing"]
  node_app["HTTP application<br/>[app.ts]"]
  node_proxy["Unified proxy<br/>[proxy.ts]"]
  node_responses["Responses API<br/>[responses.ts]"]
  node_anthropic["Anthropic API<br/>[anthropic.ts]"]
  node_router["Model router<br/>[router.ts]"]
  node_providers["Provider adapters<br/>[base.ts]"]
  node_google["Google adapter<br/>[google.ts]"]
  node_proxycore["Proxy transport<br/>[proxy.ts]"]
end

subgraph group_state["Keys and catalog"]
  node_keys["Key management<br/>[keys.ts]"]
  node_crypto["Key encryption<br/>[crypto.ts]"]
  node_database[("SQLite state<br/>[index.ts]")]
  node_catalog["Catalog sync<br/>[catalog-sync.ts]"]
  node_custom["Custom endpoints<br/>[custom-endpoint.ts]"]
  node_ratelimit["Quota tracking<br/>[ratelimit.ts]"]
end

subgraph group_capabilities["Product capabilities"]
  node_compression["Prompt compression<br/>[pipeline.ts]"]
  node_embeddings["Embeddings<br/>[embeddings.ts]"]
  node_analytics["Usage analytics<br/>[analytics.ts]"]
  node_errors["Error classification<br/>[error-classify.ts]"]
end

subgraph group_apps["User interfaces"]
  node_dashboard["Web dashboard<br/>[App.tsx]"]
  node_cli["Setup CLI<br/>[index.ts]"]
  node_desktop["Desktop app<br/>[main.ts]"]
  node_desktoptray["Tray popover<br/>[popover.ts]"]
  node_desktoplocale["Desktop localization<br/>[i18n.ts]"]
end

node_client(("API client"))

node_client -->|"sends requests"| node_app
node_app -->|"mounts route"| node_proxy
node_app -->|"mounts route"| node_responses
node_app -->|"mounts route"| node_anthropic
node_proxy -.->|"dispatches requests"| node_router
node_responses -.->|"dispatches requests"| node_router
node_anthropic -.->|"dispatches requests"| node_router
node_router -->|"resolves provider"| node_providers
node_router -->|"checks quota"| node_ratelimit
node_providers -->|"includes adapter"| node_google
node_providers -.->|"uses transport"| node_proxycore
node_keys -.->|"encrypts keys"| node_crypto
node_keys -.->|"stores key data"| node_database
node_router -->|"reads routing state"| node_database
node_catalog -.->|"updates catalog"| node_database
node_custom -->|"uses encryption"| node_crypto
node_embeddings -->|"resolves custom endpoint"| node_custom
node_compression -->|"compresses prompts"| node_client
node_analytics -->|"reports usage"| node_client
node_errors -.->|"classifies failures"| node_router
node_dashboard -.->|"administers service"| node_app
node_cli -->|"configures clients"| node_client
node_desktop -->|"hosts dashboard"| node_app
node_desktop -->|"opens popover"| node_desktoptray
node_desktop -->|"normalizes locale"| node_desktoplocale

click node_app "https://github.com/lov0u/freellmapi/blob/main/server/src/app.ts"
click node_proxy "https://github.com/lov0u/freellmapi/blob/main/server/src/routes/proxy.ts"
click node_responses "https://github.com/lov0u/freellmapi/blob/main/server/src/routes/responses.ts"
click node_anthropic "https://github.com/lov0u/freellmapi/blob/main/server/src/routes/anthropic.ts"
click node_router "https://github.com/lov0u/freellmapi/blob/main/server/src/services/router.ts"
click node_providers "https://github.com/lov0u/freellmapi/blob/main/server/src/providers/base.ts"
click node_google "https://github.com/lov0u/freellmapi/blob/main/server/src/providers/google.ts"
click node_proxycore "https://github.com/lov0u/freellmapi/blob/main/server/src/lib/proxy.ts"
click node_keys "https://github.com/lov0u/freellmapi/blob/main/server/src/routes/keys.ts"
click node_crypto "https://github.com/lov0u/freellmapi/blob/main/server/src/lib/crypto.ts"
click node_database "https://github.com/lov0u/freellmapi/blob/main/server/src/db/index.ts"
click node_catalog "https://github.com/lov0u/freellmapi/blob/main/server/src/services/catalog-sync.ts"
click node_custom "https://github.com/lov0u/freellmapi/blob/main/server/src/services/custom-endpoint.ts"
click node_ratelimit "https://github.com/lov0u/freellmapi/blob/main/server/src/services/ratelimit.ts"
click node_compression "https://github.com/lov0u/freellmapi/blob/main/server/src/services/compression/pipeline.ts"
click node_embeddings "https://github.com/lov0u/freellmapi/blob/main/server/src/routes/embeddings.ts"
click node_analytics "https://github.com/lov0u/freellmapi/blob/main/server/src/routes/analytics.ts"
click node_errors "https://github.com/lov0u/freellmapi/blob/main/server/src/lib/error-classify.ts"
click node_dashboard "https://github.com/lov0u/freellmapi/blob/main/client/src/App.tsx"
click node_cli "https://github.com/lov0u/freellmapi/blob/main/cli/src/index.ts"
click node_desktop "https://github.com/lov0u/freellmapi/blob/main/desktop/src/main.ts"
click node_desktoptray "https://github.com/lov0u/freellmapi/blob/main/desktop/src/popover.ts"
click node_desktoplocale "https://github.com/lov0u/freellmapi/blob/main/desktop/src/i18n.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_app,node_proxy,node_responses,node_anthropic,node_router,node_providers,node_google,node_proxycore,node_client toneBlue
class node_keys,node_crypto,node_database,node_catalog,node_custom,node_ratelimit toneAmber
class node_compression,node_embeddings,node_analytics,node_errors toneMint
class node_dashboard,node_cli,node_desktop,node_desktoptray,node_desktoplocale toneRose
```

## Components

### API and routing

- [HTTP application](https://github.com/lov0u/freellmapi/blob/main/server/src/app.ts): `server/src/app.ts`
- [Unified proxy](https://github.com/lov0u/freellmapi/blob/main/server/src/routes/proxy.ts): `server/src/routes/proxy.ts`
- [Responses API](https://github.com/lov0u/freellmapi/blob/main/server/src/routes/responses.ts): `server/src/routes/responses.ts`
- [Anthropic API](https://github.com/lov0u/freellmapi/blob/main/server/src/routes/anthropic.ts): `server/src/routes/anthropic.ts`
- [Model router](https://github.com/lov0u/freellmapi/blob/main/server/src/services/router.ts): `server/src/services/router.ts`
- [Provider adapters](https://github.com/lov0u/freellmapi/blob/main/server/src/providers/base.ts): `server/src/providers/base.ts`
- [Google adapter](https://github.com/lov0u/freellmapi/blob/main/server/src/providers/google.ts): `server/src/providers/google.ts`
- [Proxy transport](https://github.com/lov0u/freellmapi/blob/main/server/src/lib/proxy.ts): `server/src/lib/proxy.ts`

### Keys and catalog

- [Key management](https://github.com/lov0u/freellmapi/blob/main/server/src/routes/keys.ts): `server/src/routes/keys.ts`
- [Key encryption](https://github.com/lov0u/freellmapi/blob/main/server/src/lib/crypto.ts): `server/src/lib/crypto.ts`
- [SQLite state](https://github.com/lov0u/freellmapi/blob/main/server/src/db/index.ts): `server/src/db/index.ts`
- [Catalog sync](https://github.com/lov0u/freellmapi/blob/main/server/src/services/catalog-sync.ts): `server/src/services/catalog-sync.ts`
- [Custom endpoints](https://github.com/lov0u/freellmapi/blob/main/server/src/services/custom-endpoint.ts): `server/src/services/custom-endpoint.ts`
- [Quota tracking](https://github.com/lov0u/freellmapi/blob/main/server/src/services/ratelimit.ts): `server/src/services/ratelimit.ts`

### Product capabilities

- [Prompt compression](https://github.com/lov0u/freellmapi/blob/main/server/src/services/compression/pipeline.ts): `server/src/services/compression/pipeline.ts`
- [Embeddings](https://github.com/lov0u/freellmapi/blob/main/server/src/routes/embeddings.ts): `server/src/routes/embeddings.ts`
- [Usage analytics](https://github.com/lov0u/freellmapi/blob/main/server/src/routes/analytics.ts): `server/src/routes/analytics.ts`
- [Error classification](https://github.com/lov0u/freellmapi/blob/main/server/src/lib/error-classify.ts): `server/src/lib/error-classify.ts`

### User interfaces

- [Web dashboard](https://github.com/lov0u/freellmapi/blob/main/client/src/App.tsx): `client/src/App.tsx`
- [Setup CLI](https://github.com/lov0u/freellmapi/blob/main/cli/src/index.ts): `cli/src/index.ts`
- [Desktop app](https://github.com/lov0u/freellmapi/blob/main/desktop/src/main.ts): `desktop/src/main.ts`
- [Tray popover](https://github.com/lov0u/freellmapi/blob/main/desktop/src/popover.ts): `desktop/src/popover.ts`
- [Desktop localization](https://github.com/lov0u/freellmapi/blob/main/desktop/src/i18n.ts): `desktop/src/i18n.ts`

### Other components

- **API client**

## Connections

- API client → HTTP application: sends requests (evidence: `README.md`)
- HTTP application → Unified proxy: 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`)
- Unified proxy → Model router: dispatches requests
- Responses API → Model router: dispatches requests
- Anthropic API → Model router: dispatches requests
- Model router → Provider adapters: resolves provider (evidence: `server/src/services/router.ts`)
- Model router → Quota tracking: checks quota (evidence: `server/src/services/router.ts`)
- Provider adapters → Google adapter: includes adapter (evidence: `server/src/providers/index.ts`)
- Provider adapters → Proxy transport: uses transport
- Key management → Key encryption: encrypts keys
- Key management → SQLite state: stores key data
- Model router → SQLite state: reads routing state (evidence: `server/src/services/router.ts`)
- Catalog sync → SQLite state: updates catalog
- Custom endpoints → Key encryption: uses encryption (evidence: `server/src/services/custom-endpoint.ts`)
- Embeddings → Custom endpoints: resolves custom endpoint (evidence: `server/src/routes/embeddings.ts`)
- Prompt compression → API client: compresses prompts (evidence: `README.md`)
- Usage analytics → API client: reports usage (evidence: `README.md`)
- Error classification → Model router: classifies failures (evidence: `server/src/services/router.ts`)
- Web dashboard → HTTP application: administers service
- Setup CLI → API client: configures clients (evidence: `README.md`)
- Desktop app → HTTP application: hosts dashboard (evidence: `desktop/src/main.ts`)
- Desktop app → Tray popover: opens popover (evidence: `desktop/src/main.ts`)
- Desktop app → Desktop localization: normalizes locale (evidence: `desktop/src/main.ts`)
