# amit024/freellmapi architecture

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

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

## Overview

FreeLLMAPI aggregates free and custom model endpoints behind an OpenAI-compatible API. The main runtime path is a client request through the server’s mounted API routes, routing and quota checks, then a provider adapter and upstream service; the server also persists configuration and usage state. The README documents dashboard key management, catalog updates, multimodal endpoints, and prompt compression. Some subsystem links are documented capabilities rather than inspected call sites, so those are marked dashed or left out.

Main entry points: [`server/src/services/router.ts`](https://github.com/amit024/freellmapi/blob/main/server/src/services/router.ts) (Request router), [`server/src/app.ts`](https://github.com/amit024/freellmapi/blob/main/server/src/app.ts) (HTTP application), [`server/src/routes/proxy.ts`](https://github.com/amit024/freellmapi/blob/main/server/src/routes/proxy.ts) (Chat API routes), [`server/src/routes/keys.ts`](https://github.com/amit024/freellmapi/blob/main/server/src/routes/keys.ts) (Key management)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Client access"]
  node_dashboard["Management dashboard<br/>[App.tsx]"]
  node_api_client["API client library<br/>[api.ts]"]
end

subgraph group_api["API surfaces"]
  node_app["HTTP application<br/>[app.ts]"]
  node_chat_routes["Chat API routes<br/>[proxy.ts]"]
  node_anthropic_routes["Anthropic API<br/>[anthropic.ts]"]
  node_responses_routes["Responses API<br/>[responses.ts]"]
  node_keys_routes["Key management<br/>[keys.ts]"]
end

subgraph group_routing["Routing and providers"]
  node_router["Request router<br/>[router.ts]"]
  node_providers["Provider registry<br/>[index.ts]"]
  node_provider_adapter["Provider adapters<br/>[base.ts]"]
  node_quota["Provider quota<br/>[provider-quota.ts]"]
  node_rate_limit["Rate-limit state<br/>[ratelimit.ts]"]
end

subgraph group_state["Keys and state"]
  node_database[("SQLite state<br/>[index.ts]")]
  node_crypto["Key encryption<br/>[crypto.ts]"]
end

subgraph group_capabilities["Model capabilities"]
  node_catalog["Catalog sync<br/>[catalog-sync.ts]"]
  node_multimodal["Media and embeddings<br/>[media.ts]"]
  node_compression["Prompt compression<br/>[pipeline.ts]"]
end

node_client(("API client"))
node_upstreams(("Model providers"))
node_catalog_feed(("Signed catalog feed"))

node_client -->|"sends requests"| node_app
node_dashboard -.->|"uses API"| node_api_client
node_app -->|"mounts routes"| node_chat_routes
node_app -->|"mounts routes"| node_anthropic_routes
node_app -->|"mounts routes"| node_responses_routes
node_app -->|"mounts routes"| node_keys_routes
node_chat_routes -.->|"dispatches requests"| node_router
node_anthropic_routes -.->|"dispatches requests"| node_router
node_responses_routes -.->|"dispatches requests"| node_router
node_router -->|"resolves provider"| node_providers
node_router -->|"checks limits"| node_rate_limit
node_router -->|"checks quota"| node_quota
node_providers -.->|"selects adapter"| node_provider_adapter
node_provider_adapter -->|"forwards inference"| node_upstreams
node_provider_adapter -->|"updates quota"| node_quota
node_quota -->|"reads and writes"| node_database
node_rate_limit -->|"reads and writes"| node_database
node_keys_routes -.->|"manages keys"| node_database
node_keys_routes -.->|"encrypts keys"| node_crypto
node_catalog -->|"fetches updates"| node_catalog_feed
node_client -->|"requests media or embeddings"| node_multimodal
node_chat_routes -.->|"compresses prompts"| node_compression

click node_dashboard "https://github.com/amit024/freellmapi/blob/main/client/src/App.tsx"
click node_api_client "https://github.com/amit024/freellmapi/blob/main/client/src/lib/api.ts"
click node_app "https://github.com/amit024/freellmapi/blob/main/server/src/app.ts"
click node_chat_routes "https://github.com/amit024/freellmapi/blob/main/server/src/routes/proxy.ts"
click node_anthropic_routes "https://github.com/amit024/freellmapi/blob/main/server/src/routes/anthropic.ts"
click node_responses_routes "https://github.com/amit024/freellmapi/blob/main/server/src/routes/responses.ts"
click node_keys_routes "https://github.com/amit024/freellmapi/blob/main/server/src/routes/keys.ts"
click node_router "https://github.com/amit024/freellmapi/blob/main/server/src/services/router.ts"
click node_providers "https://github.com/amit024/freellmapi/blob/main/server/src/providers/index.ts"
click node_provider_adapter "https://github.com/amit024/freellmapi/blob/main/server/src/providers/base.ts"
click node_quota "https://github.com/amit024/freellmapi/blob/main/server/src/services/provider-quota.ts"
click node_rate_limit "https://github.com/amit024/freellmapi/blob/main/server/src/services/ratelimit.ts"
click node_database "https://github.com/amit024/freellmapi/blob/main/server/src/db/index.ts"
click node_crypto "https://github.com/amit024/freellmapi/blob/main/server/src/lib/crypto.ts"
click node_catalog "https://github.com/amit024/freellmapi/blob/main/server/src/services/catalog-sync.ts"
click node_multimodal "https://github.com/amit024/freellmapi/blob/main/server/src/services/media.ts"
click node_compression "https://github.com/amit024/freellmapi/blob/main/server/src/services/compression/pipeline.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,node_api_client,node_client toneBlue
class node_app,node_chat_routes,node_anthropic_routes,node_responses_routes,node_keys_routes toneAmber
class node_router,node_providers,node_provider_adapter,node_quota,node_rate_limit toneMint
class node_database,node_crypto toneRose
class node_catalog,node_multimodal,node_compression,node_upstreams,node_catalog_feed toneIndigo
```

## Components

### Client access

- [Management dashboard](https://github.com/amit024/freellmapi/blob/main/client/src/App.tsx): `client/src/App.tsx`
- [API client library](https://github.com/amit024/freellmapi/blob/main/client/src/lib/api.ts): `client/src/lib/api.ts`

### API surfaces

- [HTTP application](https://github.com/amit024/freellmapi/blob/main/server/src/app.ts): `server/src/app.ts`
- [Chat API routes](https://github.com/amit024/freellmapi/blob/main/server/src/routes/proxy.ts): `server/src/routes/proxy.ts`
- [Anthropic API](https://github.com/amit024/freellmapi/blob/main/server/src/routes/anthropic.ts): `server/src/routes/anthropic.ts`
- [Responses API](https://github.com/amit024/freellmapi/blob/main/server/src/routes/responses.ts): `server/src/routes/responses.ts`
- [Key management](https://github.com/amit024/freellmapi/blob/main/server/src/routes/keys.ts): `server/src/routes/keys.ts`

### Routing and providers

- [Request router](https://github.com/amit024/freellmapi/blob/main/server/src/services/router.ts): `server/src/services/router.ts`
- [Provider registry](https://github.com/amit024/freellmapi/blob/main/server/src/providers/index.ts): `server/src/providers/index.ts`
- [Provider adapters](https://github.com/amit024/freellmapi/blob/main/server/src/providers/base.ts): `server/src/providers/base.ts`
- [Provider quota](https://github.com/amit024/freellmapi/blob/main/server/src/services/provider-quota.ts): `server/src/services/provider-quota.ts`
- [Rate-limit state](https://github.com/amit024/freellmapi/blob/main/server/src/services/ratelimit.ts): `server/src/services/ratelimit.ts`

### Keys and state

- [SQLite state](https://github.com/amit024/freellmapi/blob/main/server/src/db/index.ts): `server/src/db/index.ts`
- [Key encryption](https://github.com/amit024/freellmapi/blob/main/server/src/lib/crypto.ts): `server/src/lib/crypto.ts`

### Model capabilities

- [Catalog sync](https://github.com/amit024/freellmapi/blob/main/server/src/services/catalog-sync.ts): `server/src/services/catalog-sync.ts`
- [Media and embeddings](https://github.com/amit024/freellmapi/blob/main/server/src/services/media.ts): `server/src/services/media.ts`
- [Prompt compression](https://github.com/amit024/freellmapi/blob/main/server/src/services/compression/pipeline.ts): `server/src/services/compression/pipeline.ts`

### Other components

- **API client**
- **Model providers**
- **Signed catalog feed**

## Connections

- API client → HTTP application: sends requests (evidence: `README.md`)
- Management dashboard → API client library: uses API
- HTTP application → Chat API routes: mounts routes (evidence: `server/src/app.ts`)
- HTTP application → Anthropic API: mounts routes (evidence: `server/src/app.ts`)
- HTTP application → Responses API: mounts routes (evidence: `server/src/app.ts`)
- HTTP application → Key management: mounts routes (evidence: `server/src/app.ts`)
- Chat API routes → Request router: dispatches requests
- Anthropic API → Request router: dispatches requests
- Responses API → Request router: dispatches requests
- Request router → Provider registry: resolves provider (evidence: `server/src/services/router.ts`)
- Request router → Rate-limit state: checks limits (evidence: `server/src/services/router.ts`)
- Request router → Provider quota: checks quota (evidence: `server/src/services/router.ts`)
- Provider registry → Provider adapters: selects adapter
- Provider adapters → Model providers: forwards inference (evidence: `README.md`)
- Provider adapters → Provider quota: updates quota (evidence: `server/src/providers/base.ts`)
- Provider quota → SQLite state: reads and writes (evidence: `server/src/services/provider-quota.ts`)
- Rate-limit state → SQLite state: reads and writes (evidence: `server/src/services/ratelimit.ts`)
- Key management → SQLite state: manages keys
- Key management → Key encryption: encrypts keys (evidence: `README.md`)
- Catalog sync → Signed catalog feed: fetches updates (evidence: `README.md`)
- API client → Media and embeddings: requests media or embeddings (evidence: `README.md`)
- Chat API routes → Prompt compression: compresses prompts
