# thesmallhancat/flow2api architecture

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

- Interactive diagram: https://gitdiagram.com/thesmallhancat/flow2api
- Repository: https://github.com/thesmallhancat/flow2api

## Overview

Flow2API exposes Flow image/video generation through OpenAI- and Gemini-compatible APIs, with an admin interface for configuring accounts and service settings. The main request path accepts and normalizes a client request, selects an account, submits work to Flow, and returns generated media or streamed progress. Token refresh, concurrency limits, proxy configuration, and captcha support underpin this path; management and monitoring are separate product capabilities. Some wiring is inferred from documented behavior because excerpts are partial.

Main entry points: [`src/services/generation_handler.py`](https://github.com/thesmallhancat/flow2api/blob/main/src/services/generation_handler.py) (Generation handler), [`src/api/admin.py`](https://github.com/thesmallhancat/flow2api/blob/main/src/api/admin.py) (Admin API), [`src/main.py`](https://github.com/thesmallhancat/flow2api/blob/main/src/main.py) (Application setup), [`src/services/flow_client.py`](https://github.com/thesmallhancat/flow2api/blob/main/src/services/flow_client.py) (Flow client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and UI"]
  node_routes["API routes<br/>[routes.py]"]
  node_admin["Admin API<br/>[admin.py]"]
  node_webui["Admin and test UI"]
end

subgraph group_generation["Generation"]
  node_handler["Generation handler"]
  node_flow["Flow client<br/>[flow_client.py]"]
  node_cache["Media cache<br/>[file_cache.py]"]
end

subgraph group_accounts["Accounts and runtime"]
  node_tokenmgr["Token manager<br/>[token_manager.py]"]
  node_db[("SQLite database<br/>[database.py]")]
  node_login["Protocol login<br/>[protocol_login.py]"]
  node_balancer["Load balancer<br/>[load_balancer.py]"]
  node_concurrency["Concurrency manager"]
  node_proxy["Proxy manager<br/>[proxy_manager.py]"]
  node_captcha["Captcha services<br/>[browser_captcha.py]"]
  node_captcha_ext["Captcha extension<br/>[background.js]"]
end

subgraph group_operations["Management and monitoring"]
  node_auth["Authentication<br/>[auth.py]"]
  node_monitoring["Monitoring<br/>[monitoring.py]"]
  node_app["Application setup<br/>[main.py]"]
end

node_client(("API client"))
node_flowservice["Google Flow"]
node_captcha_provider["Captcha providers"]

node_client -->|"submits request"| node_routes
node_routes -->|"verifies key"| node_auth
node_routes -->|"dispatches generation"| node_handler
node_handler -->|"selects account"| node_balancer
node_handler -->|"checks limits"| node_concurrency
node_handler -->|"gets valid token"| node_tokenmgr
node_handler -->|"submits generation"| node_flow
node_flow -->|"sends Flow requests"| node_flowservice
node_flow -->|"gets proxy settings"| node_proxy
node_handler -->|"caches media"| node_cache
node_tokenmgr -->|"reads and updates tokens"| node_db
node_tokenmgr -->|"refreshes session"| node_login
node_login -->|"authenticates"| node_flowservice
node_admin -->|"checks admin credentials"| node_auth
node_admin -->|"manages settings"| node_db
node_admin -->|"manages tokens"| node_tokenmgr
node_webui -->|"uses management API"| node_admin
node_app -->|"registers routes"| node_routes
node_app -->|"registers routes"| node_admin
node_app -->|"initializes storage"| node_db
node_app -->|"exposes metrics"| node_monitoring
node_flow -.->|"requests captcha support"| node_captcha
node_captcha -.->|"submits challenge"| node_captcha_provider
node_captcha_ext -.->|"provides browser solving"| node_captcha

click node_routes "https://github.com/thesmallhancat/flow2api/blob/main/src/api/routes.py"
click node_admin "https://github.com/thesmallhancat/flow2api/blob/main/src/api/admin.py"
click node_webui "https://github.com/thesmallhancat/flow2api/tree/main/static"
click node_handler "https://github.com/thesmallhancat/flow2api/blob/main/src/services/generation_handler.py"
click node_flow "https://github.com/thesmallhancat/flow2api/blob/main/src/services/flow_client.py"
click node_cache "https://github.com/thesmallhancat/flow2api/blob/main/src/services/file_cache.py"
click node_tokenmgr "https://github.com/thesmallhancat/flow2api/blob/main/src/services/token_manager.py"
click node_db "https://github.com/thesmallhancat/flow2api/blob/main/src/core/database.py"
click node_login "https://github.com/thesmallhancat/flow2api/blob/main/src/services/protocol_login.py"
click node_balancer "https://github.com/thesmallhancat/flow2api/blob/main/src/services/load_balancer.py"
click node_concurrency "https://github.com/thesmallhancat/flow2api/blob/main/src/services/concurrency_manager.py"
click node_proxy "https://github.com/thesmallhancat/flow2api/blob/main/src/services/proxy_manager.py"
click node_captcha "https://github.com/thesmallhancat/flow2api/blob/main/src/services/browser_captcha.py"
click node_captcha_ext "https://github.com/thesmallhancat/flow2api/blob/main/extension/background.js"
click node_auth "https://github.com/thesmallhancat/flow2api/blob/main/src/core/auth.py"
click node_monitoring "https://github.com/thesmallhancat/flow2api/blob/main/src/core/monitoring.py"
click node_app "https://github.com/thesmallhancat/flow2api/blob/main/src/main.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_routes,node_admin,node_webui,node_client toneBlue
class node_handler,node_flow,node_cache toneAmber
class node_tokenmgr,node_db,node_login,node_balancer,node_concurrency,node_proxy,node_captcha,node_captcha_ext toneMint
class node_auth,node_monitoring,node_app toneRose
class node_flowservice,node_captcha_provider toneIndigo
```

## Components

### API and UI

- [API routes](https://github.com/thesmallhancat/flow2api/blob/main/src/api/routes.py): `src/api/routes.py`
- [Admin API](https://github.com/thesmallhancat/flow2api/blob/main/src/api/admin.py): `src/api/admin.py`
- [Admin and test UI](https://github.com/thesmallhancat/flow2api/tree/main/static): `static`

### Generation

- [Generation handler](https://github.com/thesmallhancat/flow2api/blob/main/src/services/generation_handler.py): `src/services/generation_handler.py`
- [Flow client](https://github.com/thesmallhancat/flow2api/blob/main/src/services/flow_client.py): `src/services/flow_client.py`
- [Media cache](https://github.com/thesmallhancat/flow2api/blob/main/src/services/file_cache.py): `src/services/file_cache.py`

### Accounts and runtime

- [Token manager](https://github.com/thesmallhancat/flow2api/blob/main/src/services/token_manager.py): `src/services/token_manager.py`
- [SQLite database](https://github.com/thesmallhancat/flow2api/blob/main/src/core/database.py): `src/core/database.py`
- [Protocol login](https://github.com/thesmallhancat/flow2api/blob/main/src/services/protocol_login.py): `src/services/protocol_login.py`
- [Load balancer](https://github.com/thesmallhancat/flow2api/blob/main/src/services/load_balancer.py): `src/services/load_balancer.py`
- [Concurrency manager](https://github.com/thesmallhancat/flow2api/blob/main/src/services/concurrency_manager.py): `src/services/concurrency_manager.py`
- [Proxy manager](https://github.com/thesmallhancat/flow2api/blob/main/src/services/proxy_manager.py): `src/services/proxy_manager.py`
- [Captcha services](https://github.com/thesmallhancat/flow2api/blob/main/src/services/browser_captcha.py): `src/services/browser_captcha.py`
- [Captcha extension](https://github.com/thesmallhancat/flow2api/blob/main/extension/background.js): `extension/background.js`

### Management and monitoring

- [Authentication](https://github.com/thesmallhancat/flow2api/blob/main/src/core/auth.py): `src/core/auth.py`
- [Monitoring](https://github.com/thesmallhancat/flow2api/blob/main/src/core/monitoring.py): `src/core/monitoring.py`
- [Application setup](https://github.com/thesmallhancat/flow2api/blob/main/src/main.py): `src/main.py`

### Other components

- **API client**
- **Google Flow**
- **Captcha providers**

## Connections

- API client → API routes: submits request
- API routes → Authentication: verifies key
- API routes → Generation handler: dispatches generation
- Generation handler → Load balancer: selects account
- Generation handler → Concurrency manager: checks limits
- Generation handler → Token manager: gets valid token
- Generation handler → Flow client: submits generation
- Flow client → Google Flow: sends Flow requests
- Flow client → Proxy manager: gets proxy settings
- Generation handler → Media cache: caches media
- Token manager → SQLite database: reads and updates tokens
- Token manager → Protocol login: refreshes session
- Protocol login → Google Flow: authenticates
- Admin API → Authentication: checks admin credentials
- Admin API → SQLite database: manages settings
- Admin API → Token manager: manages tokens
- Admin and test UI → Admin API: uses management API
- Application setup → API routes: registers routes
- Application setup → Admin API: registers routes
- Application setup → SQLite database: initializes storage
- Application setup → Monitoring: exposes metrics
- Flow client → Captcha services: requests captcha support
- Captcha services → Captcha providers: submits challenge
- Captcha extension → Captcha services: provides browser solving