# snailyp/gemini-balance architecture

> Architecture diagram of the GitHub repository snailyp/gemini-balance, 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/snailyp/gemini-balance
- Repository: https://github.com/snailyp/gemini-balance

## Overview

Gemini Balance is a FastAPI proxy and load balancer for Gemini, with Gemini and OpenAI-compatible interfaces. The main path is a client request through routing and authentication, key selection, chat/embedding/image services, and an upstream API call; administration and monitoring provide parallel workflows. README capability statements cover features whose route or implementation details were not sampled. Edges below are limited to relationships explicit in excerpts, the SOURCE INDEX, or README; unsampled subsystems have no speculative wiring.

Main entry points: [`app/router/openai_routes.py`](https://github.com/snailyp/gemini-balance/blob/main/app/router/openai_routes.py) (OpenAI endpoints), [`app/service/key/key_manager.py`](https://github.com/snailyp/gemini-balance/blob/main/app/service/key/key_manager.py) (Key rotation), [`app/router/gemini_routes.py`](https://github.com/snailyp/gemini-balance/blob/main/app/router/gemini_routes.py) (Gemini endpoints), [`app/router/routes.py`](https://github.com/snailyp/gemini-balance/blob/main/app/router/routes.py) (Route registration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime &amp; access"]
  node_app["Application lifecycle<br/>[application.py]"]
  node_routes["Route registration<br/>[routes.py]"]
  node_security["Token authentication<br/>[security.py]"]
  node_config["Runtime configuration<br/>[config.py]"]
end

subgraph group_api["API protocols"]
  node_gemini_routes["Gemini endpoints<br/>[gemini_routes.py]"]
  node_openai_routes["OpenAI endpoints<br/>[openai_routes.py]"]
  node_compat_routes["HF compatibility"]
  node_vertex_routes["Vertex Express API"]
end

subgraph group_services["Proxy services"]
  node_chat["Gemini chat"]
  node_openai_chat["OpenAI chat"]
  node_embeddings["Embeddings"]
  node_images["Image generation"]
  node_upstream["Gemini API client<br/>[api_client.py]"]
  node_keys["Key rotation<br/>[key_manager.py]"]
  node_files["File handling<br/>[files_service.py]"]
  node_upload["Image hosting<br/>[uploader.py]"]
end

subgraph group_ops["Administration &amp; monitoring"]
  node_admin["Configuration &amp; keys<br/>[config_routes.py]"]
  node_status["Key status<br/>[key_routes.py]"]
  node_model_sync["Model maintenance<br/>[model_service.py]"]
  node_scheduler["Scheduled tasks<br/>[scheduled_tasks.py]"]
  node_monitoring["Usage statistics<br/>[stats_service.py]"]
  node_error_logs["Error logs"]
end

subgraph group_persistence["Persistence &amp; logs"]
  node_db_services["Data access<br/>[services.py]"]
  node_db[("Application database<br/>[connection.py]")]
  node_retry["Retry handling<br/>[retry_handler.py]"]
end

node_client(("API client"))

node_client -->|"sends Gemini requests"| node_gemini_routes
node_client -->|"sends OpenAI requests"| node_openai_routes
node_client -->|"uses HF API"| node_compat_routes
node_app -->|"registers routes"| node_routes
node_app -->|"syncs settings"| node_config
node_app -->|"starts scheduler"| node_scheduler
node_routes -->|"registers"| node_gemini_routes
node_routes -->|"registers"| node_openai_routes
node_routes -->|"registers"| node_compat_routes
node_routes -->|"registers"| node_vertex_routes
node_gemini_routes -->|"authenticates"| node_security
node_openai_routes -->|"authenticates"| node_security
node_vertex_routes -->|"authenticates"| node_security
node_gemini_routes -->|"selects key"| node_keys
node_openai_routes -->|"selects key"| node_keys
node_vertex_routes -->|"selects key"| node_keys
node_gemini_routes -->|"dispatches chat"| node_chat
node_openai_routes -->|"dispatches chat"| node_openai_chat
node_openai_routes -->|"dispatches images"| node_images
node_openai_routes -->|"dispatches embeddings"| node_embeddings
node_gemini_routes -->|"decorates requests"| node_retry
node_openai_routes -->|"decorates requests"| node_retry
node_chat -->|"calls API"| node_upstream
node_openai_chat -->|"calls API"| node_upstream
node_embeddings -->|"calls API"| node_upstream
node_chat -->|"uses selected key"| node_keys
node_openai_chat -->|"uses selected key"| node_keys
node_embeddings -->|"uses selected key"| node_keys
node_images -->|"uploads output"| node_upload
node_files -->|"uses API client"| node_upstream
node_files -->|"uses keys"| node_keys
node_admin -.->|"updates configuration"| node_config
node_status -.->|"reports key status"| node_keys
node_scheduler -->|"checks keys"| node_keys
node_scheduler -.->|"maintains models"| node_model_sync
node_monitoring -->|"queries statistics"| node_db
node_error_logs -->|"records and reads logs"| node_db_services
node_db_services -->|"executes queries"| node_db
node_config -->|"syncs settings"| node_db

click node_app "https://github.com/snailyp/gemini-balance/blob/main/app/core/application.py"
click node_routes "https://github.com/snailyp/gemini-balance/blob/main/app/router/routes.py"
click node_security "https://github.com/snailyp/gemini-balance/blob/main/app/core/security.py"
click node_config "https://github.com/snailyp/gemini-balance/blob/main/app/config/config.py"
click node_gemini_routes "https://github.com/snailyp/gemini-balance/blob/main/app/router/gemini_routes.py"
click node_openai_routes "https://github.com/snailyp/gemini-balance/blob/main/app/router/openai_routes.py"
click node_compat_routes "https://github.com/snailyp/gemini-balance/blob/main/app/router/openai_compatiable_routes.py"
click node_vertex_routes "https://github.com/snailyp/gemini-balance/blob/main/app/router/vertex_express_routes.py"
click node_chat "https://github.com/snailyp/gemini-balance/blob/main/app/service/chat/gemini_chat_service.py"
click node_openai_chat "https://github.com/snailyp/gemini-balance/blob/main/app/service/chat/openai_chat_service.py"
click node_embeddings "https://github.com/snailyp/gemini-balance/blob/main/app/service/embedding/gemini_embedding_service.py"
click node_images "https://github.com/snailyp/gemini-balance/blob/main/app/service/image/image_create_service.py"
click node_upstream "https://github.com/snailyp/gemini-balance/blob/main/app/service/client/api_client.py"
click node_keys "https://github.com/snailyp/gemini-balance/blob/main/app/service/key/key_manager.py"
click node_files "https://github.com/snailyp/gemini-balance/blob/main/app/service/files/files_service.py"
click node_upload "https://github.com/snailyp/gemini-balance/blob/main/app/utils/uploader.py"
click node_admin "https://github.com/snailyp/gemini-balance/blob/main/app/router/config_routes.py"
click node_status "https://github.com/snailyp/gemini-balance/blob/main/app/router/key_routes.py"
click node_model_sync "https://github.com/snailyp/gemini-balance/blob/main/app/service/model/model_service.py"
click node_scheduler "https://github.com/snailyp/gemini-balance/blob/main/app/scheduler/scheduled_tasks.py"
click node_monitoring "https://github.com/snailyp/gemini-balance/blob/main/app/service/stats/stats_service.py"
click node_error_logs "https://github.com/snailyp/gemini-balance/blob/main/app/service/error_log/error_log_service.py"
click node_db_services "https://github.com/snailyp/gemini-balance/blob/main/app/database/services.py"
click node_db "https://github.com/snailyp/gemini-balance/blob/main/app/database/connection.py"
click node_retry "https://github.com/snailyp/gemini-balance/blob/main/app/handler/retry_handler.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_app,node_routes,node_security,node_config,node_client toneBlue
class node_gemini_routes,node_openai_routes,node_compat_routes,node_vertex_routes toneAmber
class node_chat,node_openai_chat,node_embeddings,node_images,node_upstream,node_keys,node_files,node_upload toneMint
class node_admin,node_status,node_model_sync,node_scheduler,node_monitoring,node_error_logs toneRose
class node_db_services,node_db,node_retry toneIndigo
```

## Components

### Runtime & access

- [Application lifecycle](https://github.com/snailyp/gemini-balance/blob/main/app/core/application.py): `app/core/application.py`
- [Route registration](https://github.com/snailyp/gemini-balance/blob/main/app/router/routes.py): `app/router/routes.py`
- [Token authentication](https://github.com/snailyp/gemini-balance/blob/main/app/core/security.py): `app/core/security.py`
- [Runtime configuration](https://github.com/snailyp/gemini-balance/blob/main/app/config/config.py): `app/config/config.py`

### API protocols

- [Gemini endpoints](https://github.com/snailyp/gemini-balance/blob/main/app/router/gemini_routes.py): `app/router/gemini_routes.py`
- [OpenAI endpoints](https://github.com/snailyp/gemini-balance/blob/main/app/router/openai_routes.py): `app/router/openai_routes.py`
- [HF compatibility](https://github.com/snailyp/gemini-balance/blob/main/app/router/openai_compatiable_routes.py): `app/router/openai_compatiable_routes.py`
- [Vertex Express API](https://github.com/snailyp/gemini-balance/blob/main/app/router/vertex_express_routes.py): `app/router/vertex_express_routes.py`

### Proxy services

- [Gemini chat](https://github.com/snailyp/gemini-balance/blob/main/app/service/chat/gemini_chat_service.py): `app/service/chat/gemini_chat_service.py`
- [OpenAI chat](https://github.com/snailyp/gemini-balance/blob/main/app/service/chat/openai_chat_service.py): `app/service/chat/openai_chat_service.py`
- [Embeddings](https://github.com/snailyp/gemini-balance/blob/main/app/service/embedding/gemini_embedding_service.py): `app/service/embedding/gemini_embedding_service.py`
- [Image generation](https://github.com/snailyp/gemini-balance/blob/main/app/service/image/image_create_service.py): `app/service/image/image_create_service.py`
- [Gemini API client](https://github.com/snailyp/gemini-balance/blob/main/app/service/client/api_client.py): `app/service/client/api_client.py`
- [Key rotation](https://github.com/snailyp/gemini-balance/blob/main/app/service/key/key_manager.py): `app/service/key/key_manager.py`
- [File handling](https://github.com/snailyp/gemini-balance/blob/main/app/service/files/files_service.py): `app/service/files/files_service.py`
- [Image hosting](https://github.com/snailyp/gemini-balance/blob/main/app/utils/uploader.py): `app/utils/uploader.py`

### Administration & monitoring

- [Configuration & keys](https://github.com/snailyp/gemini-balance/blob/main/app/router/config_routes.py): `app/router/config_routes.py`
- [Key status](https://github.com/snailyp/gemini-balance/blob/main/app/router/key_routes.py): `app/router/key_routes.py`
- [Model maintenance](https://github.com/snailyp/gemini-balance/blob/main/app/service/model/model_service.py): `app/service/model/model_service.py`
- [Scheduled tasks](https://github.com/snailyp/gemini-balance/blob/main/app/scheduler/scheduled_tasks.py): `app/scheduler/scheduled_tasks.py`
- [Usage statistics](https://github.com/snailyp/gemini-balance/blob/main/app/service/stats/stats_service.py): `app/service/stats/stats_service.py`
- [Error logs](https://github.com/snailyp/gemini-balance/blob/main/app/service/error_log/error_log_service.py): `app/service/error_log/error_log_service.py`

### Persistence & logs

- [Data access](https://github.com/snailyp/gemini-balance/blob/main/app/database/services.py): `app/database/services.py`
- [Application database](https://github.com/snailyp/gemini-balance/blob/main/app/database/connection.py): `app/database/connection.py`
- [Retry handling](https://github.com/snailyp/gemini-balance/blob/main/app/handler/retry_handler.py): `app/handler/retry_handler.py`

### Other components

- **API client**

## Connections

- API client → Gemini endpoints: sends Gemini requests (evidence: `README.md`)
- API client → OpenAI endpoints: sends OpenAI requests (evidence: `README.md`)
- API client → HF compatibility: uses HF API (evidence: `README.md`)
- Application lifecycle → Route registration: registers routes (evidence: `app/core/application.py`)
- Application lifecycle → Runtime configuration: syncs settings (evidence: `app/core/application.py`)
- Application lifecycle → Scheduled tasks: starts scheduler (evidence: `app/core/application.py`)
- Route registration → Gemini endpoints: registers (evidence: `app/router/routes.py`)
- Route registration → OpenAI endpoints: registers (evidence: `app/router/routes.py`)
- Route registration → HF compatibility: registers (evidence: `app/router/routes.py`)
- Route registration → Vertex Express API: registers (evidence: `app/router/routes.py`)
- Gemini endpoints → Token authentication: authenticates (evidence: `app/router/gemini_routes.py`)
- OpenAI endpoints → Token authentication: authenticates (evidence: `app/router/openai_routes.py`)
- Vertex Express API → Token authentication: authenticates (evidence: `app/router/vertex_express_routes.py`)
- Gemini endpoints → Key rotation: selects key (evidence: `app/router/gemini_routes.py`)
- OpenAI endpoints → Key rotation: selects key (evidence: `app/router/openai_routes.py`)
- Vertex Express API → Key rotation: selects key (evidence: `app/router/vertex_express_routes.py`)
- Gemini endpoints → Gemini chat: dispatches chat (evidence: `app/router/gemini_routes.py`)
- OpenAI endpoints → OpenAI chat: dispatches chat (evidence: `app/router/openai_routes.py`)
- OpenAI endpoints → Image generation: dispatches images (evidence: `app/router/openai_routes.py`)
- OpenAI endpoints → Embeddings: dispatches embeddings (evidence: `app/router/openai_routes.py`)
- Gemini endpoints → Retry handling: decorates requests (evidence: `app/router/gemini_routes.py`)
- OpenAI endpoints → Retry handling: decorates requests (evidence: `app/router/openai_routes.py`)
- Gemini chat → Gemini API client: calls API (evidence: `app/service/chat/gemini_chat_service.py`)
- OpenAI chat → Gemini API client: calls API (evidence: `app/service/chat/openai_chat_service.py`)
- Embeddings → Gemini API client: calls API (evidence: `app/service/embedding/gemini_embedding_service.py`)
- Gemini chat → Key rotation: uses selected key (evidence: `app/service/chat/gemini_chat_service.py`)
- OpenAI chat → Key rotation: uses selected key (evidence: `app/service/chat/openai_chat_service.py`)
- Embeddings → Key rotation: uses selected key (evidence: `app/service/embedding/gemini_embedding_service.py`)
- Image generation → Image hosting: uploads output (evidence: `app/service/image/image_create_service.py`)
- File handling → Gemini API client: uses API client (evidence: `app/service/files/files_service.py`)
- File handling → Key rotation: uses keys (evidence: `app/service/files/files_service.py`)
- Configuration & keys → Runtime configuration: updates configuration
- Key status → Key rotation: reports key status
- Scheduled tasks → Key rotation: checks keys (evidence: `app/scheduler/scheduled_tasks.py`)
- Scheduled tasks → Model maintenance: maintains models
- Usage statistics → Application database: queries statistics (evidence: `app/service/stats/stats_service.py`)
- Error logs → Data access: records and reads logs (evidence: `app/service/error_log/error_log_service.py`)
- Data access → Application database: executes queries (evidence: `app/database/services.py`)
- Runtime configuration → Application database: syncs settings (evidence: `app/config/config.py`)
