# fruitbars/simple-one-api architecture

> Architecture diagram of the GitHub repository fruitbars/simple-one-api, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/fruitbars/simple-one-api
- Repository: https://github.com/fruitbars/simple-one-api

## Overview

simple-one-api is a multi-provider LLM gateway with OpenAI Chat Completions, OpenAI Responses, and Anthropic Messages interfaces, plus a web chat/configuration console and Wails desktop app. The main user path is client or web chat → gateway protocol handling → provider-specific upstream → streamed/result response. Administrators initialize or edit configuration, test providers, and inspect capacity, logs, and usage statistics. README statements establish several backend capabilities; sampled frontend excerpts show chat and admin API calls. Backend routing details and most provider implementations were not sampled, so those links are documented at subsystem level.

Main entry points: [`pkg/apis`](https://github.com/fruitbars/simple-one-api/tree/main/pkg/apis) (Admin APIs), [`web/src/App.tsx`](https://github.com/fruitbars/simple-one-api/blob/main/web/src/App.tsx) (Web application), [`pkg/appserver/router.go`](https://github.com/fruitbars/simple-one-api/blob/main/pkg/appserver/router.go) (HTTP gateway server), [`pkg/handler`](https://github.com/fruitbars/simple-one-api/tree/main/pkg/handler) (Provider handlers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_gateway["Gateway"]
  node_protocol_api["Client protocols"]
  node_models_api["Models and embeddings"]
  node_provider_handler["Provider handlers"]
  node_limits["Key scheduling and limits<br/>[limiter.go]"]
  node_gateway_server["HTTP gateway server<br/>[router.go]"]
end

subgraph group_providers["Provider integrations"]
  node_upstreams["LLM providers"]
  node_provider_protocols["Provider protocols"]
end

subgraph group_operations["Configuration and operations"]
  node_admin_api["Admin APIs"]
  node_config_runtime["Runtime configuration<br/>[runtime.go]"]
  node_config_store[("SQLite configuration<br/>[store.go]")]
  node_statistics["Usage statistics"]
  node_logs_capacity["Logs and capacity"]
end

subgraph group_web["Web experience"]
  node_web_app["Web application<br/>[App.tsx]"]
  node_chat_api["Chat API client<br/>[client.ts]"]
  node_conversation_store[("Local conversations")]
  node_markdown_view["Markdown rendering"]
  node_admin_workspace["Configuration console<br/>[AdminWorkspace.tsx]"]
  node_setup_wizard["Setup wizard<br/>[SetupWizard.tsx]"]
  node_statistics_panel["Statistics panel"]
end

subgraph group_desktop["Desktop runtime"]
  node_desktop_app["Wails desktop app<br/>[main.go]"]
end

node_client(("API client"))
node_chat_user(("Chat user"))

node_client -->|"sends requests"| node_gateway_server
node_gateway_server -.->|"routes protocols"| node_protocol_api
node_gateway_server -->|"serves models"| node_models_api
node_protocol_api -.->|"dispatches requests"| node_provider_handler
node_provider_handler -->|"schedules keys"| node_limits
node_provider_handler -->|"calls provider"| node_upstreams
node_upstreams -.->|"uses protocols"| node_provider_protocols
node_admin_api -->|"persists configuration"| node_config_store
node_admin_api -->|"publishes configuration"| node_config_runtime
node_admin_api -->|"queries usage"| node_statistics
node_admin_api -->|"reports status"| node_logs_capacity
node_chat_user -->|"uses chat"| node_web_app
node_web_app -->|"requests models and chat"| node_chat_api
node_chat_api -->|"calls gateway"| node_gateway_server
node_web_app -->|"loads and saves"| node_conversation_store
node_web_app -->|"renders messages"| node_markdown_view
node_web_app -->|"opens console"| node_admin_workspace
node_web_app -->|"opens setup"| node_setup_wizard
node_admin_workspace -->|"calls admin endpoints"| node_admin_api
node_setup_wizard -->|"tests and publishes"| node_admin_api
node_admin_workspace -->|"shows statistics"| node_statistics_panel
node_statistics_panel -.->|"requests statistics"| node_admin_api
node_desktop_app -->|"starts gateway"| node_gateway_server

click node_protocol_api "https://github.com/fruitbars/simple-one-api/tree/main/pkg/handler"
click node_models_api "https://github.com/fruitbars/simple-one-api/blob/main/pkg/embedding/embeddings_handler.go"
click node_provider_handler "https://github.com/fruitbars/simple-one-api/tree/main/pkg/handler"
click node_limits "https://github.com/fruitbars/simple-one-api/blob/main/pkg/mylimiter/limiter.go"
click node_upstreams "https://github.com/fruitbars/simple-one-api/tree/main/pkg/adapter"
click node_provider_protocols "https://github.com/fruitbars/simple-one-api/tree/main/pkg/llm"
click node_admin_api "https://github.com/fruitbars/simple-one-api/tree/main/pkg/apis"
click node_config_runtime "https://github.com/fruitbars/simple-one-api/blob/main/pkg/config/runtime.go"
click node_config_store "https://github.com/fruitbars/simple-one-api/blob/main/pkg/configstore/store.go"
click node_statistics "https://github.com/fruitbars/simple-one-api/tree/main/pkg/statistics"
click node_logs_capacity "https://github.com/fruitbars/simple-one-api/blob/main/pkg/apis/admin_capacity_handler.go"
click node_web_app "https://github.com/fruitbars/simple-one-api/blob/main/web/src/App.tsx"
click node_chat_api "https://github.com/fruitbars/simple-one-api/blob/main/web/src/api/client.ts"
click node_conversation_store "https://github.com/fruitbars/simple-one-api/blob/main/web/src/conversationStore.ts"
click node_markdown_view "https://github.com/fruitbars/simple-one-api/blob/main/web/src/MarkdownMessage.tsx"
click node_admin_workspace "https://github.com/fruitbars/simple-one-api/blob/main/web/src/AdminWorkspace.tsx"
click node_setup_wizard "https://github.com/fruitbars/simple-one-api/blob/main/web/src/SetupWizard.tsx"
click node_statistics_panel "https://github.com/fruitbars/simple-one-api/blob/main/web/src/StatisticsPanel.tsx"
click node_desktop_app "https://github.com/fruitbars/simple-one-api/blob/main/cmd/desktop/main.go"
click node_gateway_server "https://github.com/fruitbars/simple-one-api/blob/main/pkg/appserver/router.go"

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_protocol_api,node_models_api,node_provider_handler,node_limits,node_gateway_server,node_client,node_chat_user toneBlue
class node_upstreams,node_provider_protocols toneAmber
class node_admin_api,node_config_runtime,node_config_store,node_statistics,node_logs_capacity toneMint
class node_web_app,node_chat_api,node_conversation_store,node_markdown_view,node_admin_workspace,node_setup_wizard,node_statistics_panel toneRose
class node_desktop_app toneIndigo
```

## Components

### Gateway

- [Client protocols](https://github.com/fruitbars/simple-one-api/tree/main/pkg/handler): `pkg/handler`
- [Models and embeddings](https://github.com/fruitbars/simple-one-api/blob/main/pkg/embedding/embeddings_handler.go): `pkg/embedding/embeddings_handler.go`
- [Provider handlers](https://github.com/fruitbars/simple-one-api/tree/main/pkg/handler): `pkg/handler`
- [Key scheduling and limits](https://github.com/fruitbars/simple-one-api/blob/main/pkg/mylimiter/limiter.go): `pkg/mylimiter/limiter.go`
- [HTTP gateway server](https://github.com/fruitbars/simple-one-api/blob/main/pkg/appserver/router.go): `pkg/appserver/router.go`

### Provider integrations

- [LLM providers](https://github.com/fruitbars/simple-one-api/tree/main/pkg/adapter): `pkg/adapter`
- [Provider protocols](https://github.com/fruitbars/simple-one-api/tree/main/pkg/llm): `pkg/llm`

### Configuration and operations

- [Admin APIs](https://github.com/fruitbars/simple-one-api/tree/main/pkg/apis): `pkg/apis`
- [Runtime configuration](https://github.com/fruitbars/simple-one-api/blob/main/pkg/config/runtime.go): `pkg/config/runtime.go`
- [SQLite configuration](https://github.com/fruitbars/simple-one-api/blob/main/pkg/configstore/store.go): `pkg/configstore/store.go`
- [Usage statistics](https://github.com/fruitbars/simple-one-api/tree/main/pkg/statistics): `pkg/statistics`
- [Logs and capacity](https://github.com/fruitbars/simple-one-api/blob/main/pkg/apis/admin_capacity_handler.go): `pkg/apis/admin_capacity_handler.go`

### Web experience

- [Web application](https://github.com/fruitbars/simple-one-api/blob/main/web/src/App.tsx): `web/src/App.tsx`
- [Chat API client](https://github.com/fruitbars/simple-one-api/blob/main/web/src/api/client.ts): `web/src/api/client.ts`
- [Local conversations](https://github.com/fruitbars/simple-one-api/blob/main/web/src/conversationStore.ts): `web/src/conversationStore.ts`
- [Markdown rendering](https://github.com/fruitbars/simple-one-api/blob/main/web/src/MarkdownMessage.tsx): `web/src/MarkdownMessage.tsx`
- [Configuration console](https://github.com/fruitbars/simple-one-api/blob/main/web/src/AdminWorkspace.tsx): `web/src/AdminWorkspace.tsx`
- [Setup wizard](https://github.com/fruitbars/simple-one-api/blob/main/web/src/SetupWizard.tsx): `web/src/SetupWizard.tsx`
- [Statistics panel](https://github.com/fruitbars/simple-one-api/blob/main/web/src/StatisticsPanel.tsx): `web/src/StatisticsPanel.tsx`

### Desktop runtime

- [Wails desktop app](https://github.com/fruitbars/simple-one-api/blob/main/cmd/desktop/main.go): `cmd/desktop/main.go`

### Other components

- **API client**
- **Chat user**

## Connections

- API client → HTTP gateway server: sends requests (evidence: `README.md`)
- HTTP gateway server → Client protocols: routes protocols
- HTTP gateway server → Models and embeddings: serves models (evidence: `README.md`)
- Client protocols → Provider handlers: dispatches requests
- Provider handlers → Key scheduling and limits: schedules keys (evidence: `README.md`)
- Provider handlers → LLM providers: calls provider (evidence: `README.md`)
- LLM providers → Provider protocols: uses protocols
- Admin APIs → SQLite configuration: persists configuration (evidence: `README.md`)
- Admin APIs → Runtime configuration: publishes configuration (evidence: `README.md`)
- Admin APIs → Usage statistics: queries usage (evidence: `README.md`)
- Admin APIs → Logs and capacity: reports status (evidence: `README.md`)
- Chat user → Web application: uses chat (evidence: `README.md`)
- Web application → Chat API client: requests models and chat (evidence: `web/src/App.tsx`)
- Chat API client → HTTP gateway server: calls gateway (evidence: `web/src/api/client.ts`)
- Web application → Local conversations: loads and saves (evidence: `web/src/App.tsx`)
- Web application → Markdown rendering: renders messages (evidence: `web/src/App.tsx`)
- Web application → Configuration console: opens console (evidence: `web/src/App.tsx`)
- Web application → Setup wizard: opens setup (evidence: `web/src/App.tsx`)
- Configuration console → Admin APIs: calls admin endpoints (evidence: `web/src/AdminWorkspace.tsx`)
- Setup wizard → Admin APIs: tests and publishes (evidence: `web/src/SetupWizard.tsx`)
- Configuration console → Statistics panel: shows statistics (evidence: `web/src/AdminWorkspace.tsx`)
- Statistics panel → Admin APIs: requests statistics
- Wails desktop app → HTTP gateway server: starts gateway (evidence: `README.md`)