# zexadev/gemini-web2api-go architecture

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

- Interactive diagram: https://gitdiagram.com/zexadev/gemini-web2api-go
- Repository: https://github.com/zexadev/gemini-web2api-go

## Overview

gemini-web2api-go is a self-hosted proxy that translates OpenAI-compatible requests into Gemini web-protocol calls, with an optional MCP search endpoint and admin dashboard. The main workflow is an API client sending a chat or response request, the HTTP handlers preparing a Gemini generation, and the service returning a compatible response; video and media generation are additional product branches. Cookie and proxy pools, request persistence, and admin operations support the runtime. Some capability links come from the README because their handler implementations were not sampled.

Main entry points: [`internal/app/server.go`](https://github.com/zexadev/gemini-web2api-go/blob/main/internal/app/server.go) (HTTP handlers), [`internal/app/gemini.go`](https://github.com/zexadev/gemini-web2api-go/blob/main/internal/app/gemini.go) (Gemini protocol), [`internal/app/app.go`](https://github.com/zexadev/gemini-web2api-go/blob/main/internal/app/app.go) (Runtime bootstrap), [`internal/app/db.go`](https://github.com/zexadev/gemini-web2api-go/blob/main/internal/app/db.go) (Request database)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and MCP"]
  node_server["HTTP handlers<br/>[server.go]"]
  node_messages["Prompt and tools<br/>[messages.go]"]
  node_mcp["MCP search<br/>[mcp.go]"]
end

subgraph group_generation["Gemini generation"]
  node_gemini["Gemini protocol<br/>[gemini.go]"]
  node_clienttransport["TLS transport<br/>[client.go]"]
  node_search["Search citations<br/>[search.go]"]
  node_media["Media generation<br/>[media.go]"]
  node_vision["Image understanding<br/>[vision.go]"]
  node_uploads["File uploads<br/>[upload.go]"]
  node_contextfile["Long context<br/>[context_file.go]"]
  node_videos["Video jobs<br/>[videos.go]"]
end

subgraph group_operations["Accounts and routing"]
  node_runtime["Runtime bootstrap<br/>[app.go]"]
  node_cookies[("Cookie pool<br/>[cookie_pool.go]")]
  node_proxies[("Proxy pool<br/>[proxy.go]")]
  node_limits["Rate limits<br/>[ratelimit.go]"]
  node_scheduler["Pool scheduling<br/>[scheduler.go]"]
  node_database[("Request database<br/>[db.go]")]
  node_dialect["SQL dialects<br/>[dbdialect.go]"]
end

subgraph group_admin["Administration"]
  node_adminui["Admin dashboard<br/>[admin_ui.go]"]
  node_admin["Admin API<br/>[admin.go]"]
  node_admincookies["Cookie management<br/>[admin_cookies.go]"]
  node_apikey["API key auth<br/>[apikey.go]"]
end

node_client(("API client"))
node_google(("Gemini web app"))

node_client -->|"sends requests"| node_server
node_server -->|"generates replies"| node_gemini
node_gemini -->|"calls web protocol"| node_google
node_gemini -.->|"uses transport"| node_clienttransport
node_gemini -->|"selects account"| node_cookies
node_gemini -->|"selects egress"| node_proxies
node_gemini -->|"prepares long context"| node_contextfile
node_contextfile -->|"uploads attachment"| node_uploads
node_server -.->|"formats messages"| node_messages
node_server -.->|"extracts sources"| node_search
node_server -->|"routes MCP"| node_mcp
node_mcp -->|"searches web"| node_google
node_server -->|"serves video jobs"| node_videos
node_server -.->|"supports media"| node_media
node_server -.->|"supports vision"| node_vision
node_runtime -->|"initializes store"| node_database
node_runtime -->|"loads pool"| node_proxies
node_gemini -.->|"acquires slots"| node_limits
node_scheduler -.->|"rotates accounts"| node_cookies
node_scheduler -.->|"schedules egress"| node_proxies
node_server -.->|"records requests"| node_database
node_database -.->|"selects backend"| node_dialect
node_runtime -->|"registers dashboard"| node_adminui
node_runtime -->|"registers admin APIs"| node_admin
node_admin -->|"reads statistics"| node_database
node_admin -.->|"manages proxies"| node_proxies
node_admincookies -.->|"manages accounts"| node_cookies
node_runtime -.->|"protects API routes"| node_apikey

click node_server "https://github.com/zexadev/gemini-web2api-go/blob/main/internal/app/server.go"
click node_messages "https://github.com/zexadev/gemini-web2api-go/blob/main/internal/app/messages.go"
click node_mcp "https://github.com/zexadev/gemini-web2api-go/blob/main/internal/app/mcp.go"
click node_runtime "https://github.com/zexadev/gemini-web2api-go/blob/main/internal/app/app.go"
click node_gemini "https://github.com/zexadev/gemini-web2api-go/blob/main/internal/app/gemini.go"
click node_clienttransport "https://github.com/zexadev/gemini-web2api-go/blob/main/internal/app/client.go"
click node_search "https://github.com/zexadev/gemini-web2api-go/blob/main/internal/app/search.go"
click node_media "https://github.com/zexadev/gemini-web2api-go/blob/main/internal/app/media.go"
click node_vision "https://github.com/zexadev/gemini-web2api-go/blob/main/internal/app/vision.go"
click node_uploads "https://github.com/zexadev/gemini-web2api-go/blob/main/internal/app/upload.go"
click node_contextfile "https://github.com/zexadev/gemini-web2api-go/blob/main/internal/app/context_file.go"
click node_videos "https://github.com/zexadev/gemini-web2api-go/blob/main/internal/app/videos.go"
click node_cookies "https://github.com/zexadev/gemini-web2api-go/blob/main/internal/app/cookie_pool.go"
click node_proxies "https://github.com/zexadev/gemini-web2api-go/blob/main/internal/app/proxy.go"
click node_limits "https://github.com/zexadev/gemini-web2api-go/blob/main/internal/app/ratelimit.go"
click node_scheduler "https://github.com/zexadev/gemini-web2api-go/blob/main/internal/app/scheduler.go"
click node_database "https://github.com/zexadev/gemini-web2api-go/blob/main/internal/app/db.go"
click node_dialect "https://github.com/zexadev/gemini-web2api-go/blob/main/internal/app/dbdialect.go"
click node_adminui "https://github.com/zexadev/gemini-web2api-go/blob/main/internal/app/admin_ui.go"
click node_admin "https://github.com/zexadev/gemini-web2api-go/blob/main/internal/app/admin.go"
click node_admincookies "https://github.com/zexadev/gemini-web2api-go/blob/main/internal/app/admin_cookies.go"
click node_apikey "https://github.com/zexadev/gemini-web2api-go/blob/main/internal/app/apikey.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_server,node_messages,node_mcp,node_client toneBlue
class node_gemini,node_clienttransport,node_search,node_media,node_vision,node_uploads,node_contextfile,node_videos toneAmber
class node_runtime,node_cookies,node_proxies,node_limits,node_scheduler,node_database,node_dialect toneMint
class node_adminui,node_admin,node_admincookies,node_apikey toneRose
class node_google toneIndigo
```

## Components

### API and MCP

- [HTTP handlers](https://github.com/zexadev/gemini-web2api-go/blob/main/internal/app/server.go): `internal/app/server.go`
- [Prompt and tools](https://github.com/zexadev/gemini-web2api-go/blob/main/internal/app/messages.go): `internal/app/messages.go`
- [MCP search](https://github.com/zexadev/gemini-web2api-go/blob/main/internal/app/mcp.go): `internal/app/mcp.go`

### Gemini generation

- [Gemini protocol](https://github.com/zexadev/gemini-web2api-go/blob/main/internal/app/gemini.go): `internal/app/gemini.go`
- [TLS transport](https://github.com/zexadev/gemini-web2api-go/blob/main/internal/app/client.go): `internal/app/client.go`
- [Search citations](https://github.com/zexadev/gemini-web2api-go/blob/main/internal/app/search.go): `internal/app/search.go`
- [Media generation](https://github.com/zexadev/gemini-web2api-go/blob/main/internal/app/media.go): `internal/app/media.go`
- [Image understanding](https://github.com/zexadev/gemini-web2api-go/blob/main/internal/app/vision.go): `internal/app/vision.go`
- [File uploads](https://github.com/zexadev/gemini-web2api-go/blob/main/internal/app/upload.go): `internal/app/upload.go`
- [Long context](https://github.com/zexadev/gemini-web2api-go/blob/main/internal/app/context_file.go): `internal/app/context_file.go`
- [Video jobs](https://github.com/zexadev/gemini-web2api-go/blob/main/internal/app/videos.go): `internal/app/videos.go`

### Accounts and routing

- [Runtime bootstrap](https://github.com/zexadev/gemini-web2api-go/blob/main/internal/app/app.go): `internal/app/app.go`
- [Cookie pool](https://github.com/zexadev/gemini-web2api-go/blob/main/internal/app/cookie_pool.go): `internal/app/cookie_pool.go`
- [Proxy pool](https://github.com/zexadev/gemini-web2api-go/blob/main/internal/app/proxy.go): `internal/app/proxy.go`
- [Rate limits](https://github.com/zexadev/gemini-web2api-go/blob/main/internal/app/ratelimit.go): `internal/app/ratelimit.go`
- [Pool scheduling](https://github.com/zexadev/gemini-web2api-go/blob/main/internal/app/scheduler.go): `internal/app/scheduler.go`
- [Request database](https://github.com/zexadev/gemini-web2api-go/blob/main/internal/app/db.go): `internal/app/db.go`
- [SQL dialects](https://github.com/zexadev/gemini-web2api-go/blob/main/internal/app/dbdialect.go): `internal/app/dbdialect.go`

### Administration

- [Admin dashboard](https://github.com/zexadev/gemini-web2api-go/blob/main/internal/app/admin_ui.go): `internal/app/admin_ui.go`
- [Admin API](https://github.com/zexadev/gemini-web2api-go/blob/main/internal/app/admin.go): `internal/app/admin.go`
- [Cookie management](https://github.com/zexadev/gemini-web2api-go/blob/main/internal/app/admin_cookies.go): `internal/app/admin_cookies.go`
- [API key auth](https://github.com/zexadev/gemini-web2api-go/blob/main/internal/app/apikey.go): `internal/app/apikey.go`

### Other components

- **API client**
- **Gemini web app**

## Connections

- API client → HTTP handlers: sends requests (evidence: `README.md`)
- HTTP handlers → Gemini protocol: generates replies (evidence: `internal/app/server.go`)
- Gemini protocol → Gemini web app: calls web protocol (evidence: `README.md`)
- Gemini protocol → TLS transport: uses transport
- Gemini protocol → Cookie pool: selects account (evidence: `internal/app/gemini.go`)
- Gemini protocol → Proxy pool: selects egress (evidence: `internal/app/gemini.go`)
- Gemini protocol → Long context: prepares long context (evidence: `internal/app/gemini.go`)
- Long context → File uploads: uploads attachment (evidence: `internal/app/context_file.go`)
- HTTP handlers → Prompt and tools: formats messages
- HTTP handlers → Search citations: extracts sources
- HTTP handlers → MCP search: routes MCP
- MCP search → Gemini web app: searches web (evidence: `README.md`)
- HTTP handlers → Video jobs: serves video jobs (evidence: `README.md`)
- HTTP handlers → Media generation: supports media
- HTTP handlers → Image understanding: supports vision
- Runtime bootstrap → Request database: initializes store (evidence: `internal/app/app.go`)
- Runtime bootstrap → Proxy pool: loads pool (evidence: `internal/app/app.go`)
- Gemini protocol → Rate limits: acquires slots
- Pool scheduling → Cookie pool: rotates accounts
- Pool scheduling → Proxy pool: schedules egress
- HTTP handlers → Request database: records requests
- Request database → SQL dialects: selects backend
- Runtime bootstrap → Admin dashboard: registers dashboard (evidence: `internal/app/app.go`)
- Runtime bootstrap → Admin API: registers admin APIs (evidence: `internal/app/app.go`)
- Admin API → Request database: reads statistics (evidence: `internal/app/admin.go`)
- Admin API → Proxy pool: manages proxies
- Cookie management → Cookie pool: manages accounts
- Runtime bootstrap → API key auth: protects API routes
