# jwadow/kiro-gateway architecture

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

- Interactive diagram: https://gitdiagram.com/jwadow/kiro-gateway
- Repository: https://github.com/jwadow/kiro-gateway

## Overview

Kiro Gateway is a FastAPI proxy that lets OpenAI- and Anthropic-compatible clients use Kiro models. Requests enter through the server and protocol-specific routes, which prepare provider requests and return converted or streamed responses; account selection and authentication support the upstream call. The README also documents model discovery, web search, token counting, retries, multi-account failover, and VPN/proxy access. Edges are limited to relationships visible in excerpts, the source index, or README; unsampled subsystems are represented without asserting unverified internal calls.

Main entry points: [`kiro/routes_openai.py`](https://github.com/jwadow/kiro-gateway/blob/main/kiro/routes_openai.py) (OpenAI Routes), [`kiro/routes_anthropic.py`](https://github.com/jwadow/kiro-gateway/blob/main/kiro/routes_anthropic.py) (Anthropic Routes), [`main.py`](https://github.com/jwadow/kiro-gateway/blob/main/main.py) (Server Lifecycle), [`kiro/http_client.py`](https://github.com/jwadow/kiro-gateway/blob/main/kiro/http_client.py) (Kiro HTTP Client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Gateway API"]
  node_server["Server Lifecycle<br/>[main.py]"]
  node_openai["OpenAI Routes<br/>[routes_openai.py]"]
  node_anthropic["Anthropic Routes"]
end

subgraph group_accounts["Accounts and Models"]
  node_account_mgr["Account Manager<br/>[account_manager.py]"]
  node_auth["Kiro Authentication<br/>[auth.py]"]
  node_models["Model Resolution<br/>[model_resolver.py]"]
  node_model_cache[("Model Metadata Cache<br/>[cache.py]")]
end

subgraph group_protocol["Protocol Handling"]
  node_openai_convert["OpenAI Conversion"]
  node_anthropic_convert["Anthropic Conversion"]
  node_core_convert["Shared Conversion<br/>[converters_core.py]"]
  node_openai_stream["OpenAI Streaming"]
  node_anthropic_stream["Anthropic Streaming"]
  node_stream_core["Stream Processing<br/>[streaming_core.py]"]
  node_parsers["Event Parsing<br/>[parsers.py]"]
end

subgraph group_runtime["Upstream Runtime"]
  node_kiro_http["Kiro HTTP Client<br/>[http_client.py]"]
  node_mcp["Web Search Tools<br/>[mcp_tools.py]"]
  node_truncation["Truncation Recovery"]
  node_trunc_state[("Truncation State")]
end

subgraph group_support["Gateway Services"]
  node_config["Gateway Configuration<br/>[config.py]"]
  node_debug["Debug Logging<br/>[debug_logger.py]"]
end

node_clients(("API Clients"))
node_kiro_api{{"Kiro API"}}
node_mcp_api{{"Kiro MCP API"}}
node_vpn{{"VPN or Proxy"}}

node_clients -->|"send requests"| node_server
node_server -->|"registers routes"| node_openai
node_server -->|"registers routes"| node_anthropic
node_server -->|"initializes"| node_account_mgr
node_server -->|"loads settings"| node_config
node_server -->|"installs middleware"| node_debug
node_openai -->|"converts requests"| node_openai_convert
node_openai -->|"streams responses"| node_openai_stream
node_anthropic -->|"converts requests"| node_anthropic_convert
node_anthropic -->|"streams responses"| node_anthropic_stream
node_openai_convert -->|"uses shared conversion"| node_core_convert
node_anthropic_convert -->|"uses shared conversion"| node_core_convert
node_openai_stream -->|"uses stream helpers"| node_stream_core
node_anthropic_stream -->|"uses stream helpers"| node_stream_core
node_openai_stream -->|"parses events"| node_parsers
node_anthropic_stream -->|"parses events"| node_parsers
node_openai -->|"resolves model"| node_models
node_models -->|"checks metadata"| node_model_cache
node_account_mgr -->|"manages authentication"| node_auth
node_openai -->|"sends upstream requests"| node_kiro_http
node_anthropic -->|"sends upstream requests"| node_kiro_http
node_kiro_http -->|"gets access tokens"| node_auth
node_kiro_http -->|"calls Kiro"| node_kiro_api
node_anthropic_stream -->|"intercepts search calls"| node_mcp
node_mcp -->|"calls search API"| node_mcp_api
node_openai -->|"reads and updates"| node_trunc_state
node_anthropic -->|"reads and updates"| node_trunc_state
node_openai -->|"uses recovery"| node_truncation
node_anthropic -->|"uses recovery"| node_truncation
node_kiro_http -.->|"routes through proxy"| node_vpn
node_openai -->|"records request activity"| node_debug
node_anthropic -->|"records request activity"| node_debug

click node_server "https://github.com/jwadow/kiro-gateway/blob/main/main.py"
click node_openai "https://github.com/jwadow/kiro-gateway/blob/main/kiro/routes_openai.py"
click node_anthropic "https://github.com/jwadow/kiro-gateway/blob/main/kiro/routes_anthropic.py"
click node_account_mgr "https://github.com/jwadow/kiro-gateway/blob/main/kiro/account_manager.py"
click node_auth "https://github.com/jwadow/kiro-gateway/blob/main/kiro/auth.py"
click node_models "https://github.com/jwadow/kiro-gateway/blob/main/kiro/model_resolver.py"
click node_model_cache "https://github.com/jwadow/kiro-gateway/blob/main/kiro/cache.py"
click node_config "https://github.com/jwadow/kiro-gateway/blob/main/kiro/config.py"
click node_openai_convert "https://github.com/jwadow/kiro-gateway/blob/main/kiro/converters_openai.py"
click node_anthropic_convert "https://github.com/jwadow/kiro-gateway/blob/main/kiro/converters_anthropic.py"
click node_core_convert "https://github.com/jwadow/kiro-gateway/blob/main/kiro/converters_core.py"
click node_openai_stream "https://github.com/jwadow/kiro-gateway/blob/main/kiro/streaming_openai.py"
click node_anthropic_stream "https://github.com/jwadow/kiro-gateway/blob/main/kiro/streaming_anthropic.py"
click node_stream_core "https://github.com/jwadow/kiro-gateway/blob/main/kiro/streaming_core.py"
click node_parsers "https://github.com/jwadow/kiro-gateway/blob/main/kiro/parsers.py"
click node_kiro_http "https://github.com/jwadow/kiro-gateway/blob/main/kiro/http_client.py"
click node_mcp "https://github.com/jwadow/kiro-gateway/blob/main/kiro/mcp_tools.py"
click node_truncation "https://github.com/jwadow/kiro-gateway/blob/main/kiro/truncation_recovery.py"
click node_trunc_state "https://github.com/jwadow/kiro-gateway/blob/main/kiro/truncation_state.py"
click node_debug "https://github.com/jwadow/kiro-gateway/blob/main/kiro/debug_logger.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_server,node_openai,node_anthropic,node_clients toneBlue
class node_account_mgr,node_auth,node_models,node_model_cache toneAmber
class node_openai_convert,node_anthropic_convert,node_core_convert,node_openai_stream,node_anthropic_stream,node_stream_core,node_parsers,node_kiro_api,node_mcp_api toneMint
class node_kiro_http,node_mcp,node_truncation,node_trunc_state toneRose
class node_config,node_debug,node_vpn toneIndigo
```

## Components

### Gateway API

- [Server Lifecycle](https://github.com/jwadow/kiro-gateway/blob/main/main.py): `main.py`
- [OpenAI Routes](https://github.com/jwadow/kiro-gateway/blob/main/kiro/routes_openai.py): `kiro/routes_openai.py`
- [Anthropic Routes](https://github.com/jwadow/kiro-gateway/blob/main/kiro/routes_anthropic.py): `kiro/routes_anthropic.py`

### Accounts and Models

- [Account Manager](https://github.com/jwadow/kiro-gateway/blob/main/kiro/account_manager.py): `kiro/account_manager.py`
- [Kiro Authentication](https://github.com/jwadow/kiro-gateway/blob/main/kiro/auth.py): `kiro/auth.py`
- [Model Resolution](https://github.com/jwadow/kiro-gateway/blob/main/kiro/model_resolver.py): `kiro/model_resolver.py`
- [Model Metadata Cache](https://github.com/jwadow/kiro-gateway/blob/main/kiro/cache.py): `kiro/cache.py`

### Protocol Handling

- [OpenAI Conversion](https://github.com/jwadow/kiro-gateway/blob/main/kiro/converters_openai.py): `kiro/converters_openai.py`
- [Anthropic Conversion](https://github.com/jwadow/kiro-gateway/blob/main/kiro/converters_anthropic.py): `kiro/converters_anthropic.py`
- [Shared Conversion](https://github.com/jwadow/kiro-gateway/blob/main/kiro/converters_core.py): `kiro/converters_core.py`
- [OpenAI Streaming](https://github.com/jwadow/kiro-gateway/blob/main/kiro/streaming_openai.py): `kiro/streaming_openai.py`
- [Anthropic Streaming](https://github.com/jwadow/kiro-gateway/blob/main/kiro/streaming_anthropic.py): `kiro/streaming_anthropic.py`
- [Stream Processing](https://github.com/jwadow/kiro-gateway/blob/main/kiro/streaming_core.py): `kiro/streaming_core.py`
- [Event Parsing](https://github.com/jwadow/kiro-gateway/blob/main/kiro/parsers.py): `kiro/parsers.py`

### Upstream Runtime

- [Kiro HTTP Client](https://github.com/jwadow/kiro-gateway/blob/main/kiro/http_client.py): `kiro/http_client.py`
- [Web Search Tools](https://github.com/jwadow/kiro-gateway/blob/main/kiro/mcp_tools.py): `kiro/mcp_tools.py`
- [Truncation Recovery](https://github.com/jwadow/kiro-gateway/blob/main/kiro/truncation_recovery.py): `kiro/truncation_recovery.py`
- [Truncation State](https://github.com/jwadow/kiro-gateway/blob/main/kiro/truncation_state.py): `kiro/truncation_state.py`

### Gateway Services

- [Gateway Configuration](https://github.com/jwadow/kiro-gateway/blob/main/kiro/config.py): `kiro/config.py`
- [Debug Logging](https://github.com/jwadow/kiro-gateway/blob/main/kiro/debug_logger.py): `kiro/debug_logger.py`

### Other components

- **API Clients**
- **Kiro API**
- **Kiro MCP API**
- **VPN or Proxy**

## Connections

- API Clients → Server Lifecycle: send requests (evidence: `README.md`)
- Server Lifecycle → OpenAI Routes: registers routes (evidence: `main.py`)
- Server Lifecycle → Anthropic Routes: registers routes (evidence: `main.py`)
- Server Lifecycle → Account Manager: initializes (evidence: `main.py`)
- Server Lifecycle → Gateway Configuration: loads settings (evidence: `main.py`)
- Server Lifecycle → Debug Logging: installs middleware (evidence: `main.py`)
- OpenAI Routes → OpenAI Conversion: converts requests (evidence: `kiro/routes_openai.py`)
- OpenAI Routes → OpenAI Streaming: streams responses (evidence: `kiro/routes_openai.py`)
- Anthropic Routes → Anthropic Conversion: converts requests (evidence: `kiro/routes_anthropic.py`)
- Anthropic Routes → Anthropic Streaming: streams responses (evidence: `kiro/routes_anthropic.py`)
- OpenAI Conversion → Shared Conversion: uses shared conversion (evidence: `kiro/converters_openai.py`)
- Anthropic Conversion → Shared Conversion: uses shared conversion (evidence: `kiro/converters_anthropic.py`)
- OpenAI Streaming → Stream Processing: uses stream helpers (evidence: `kiro/streaming_openai.py`)
- Anthropic Streaming → Stream Processing: uses stream helpers (evidence: `kiro/streaming_anthropic.py`)
- OpenAI Streaming → Event Parsing: parses events (evidence: `kiro/streaming_openai.py`)
- Anthropic Streaming → Event Parsing: parses events (evidence: `kiro/streaming_anthropic.py`)
- OpenAI Routes → Model Resolution: resolves model (evidence: `kiro/routes_openai.py`)
- Model Resolution → Model Metadata Cache: checks metadata (evidence: `kiro/model_resolver.py`)
- Account Manager → Kiro Authentication: manages authentication (evidence: `kiro/account_manager.py`)
- OpenAI Routes → Kiro HTTP Client: sends upstream requests (evidence: `kiro/routes_openai.py`)
- Anthropic Routes → Kiro HTTP Client: sends upstream requests (evidence: `kiro/routes_anthropic.py`)
- Kiro HTTP Client → Kiro Authentication: gets access tokens (evidence: `kiro/http_client.py`)
- Kiro HTTP Client → Kiro API: calls Kiro (evidence: `README.md`)
- Anthropic Streaming → Web Search Tools: intercepts search calls (evidence: `kiro/streaming_anthropic.py`)
- Web Search Tools → Kiro MCP API: calls search API (evidence: `kiro/mcp_tools.py`)
- OpenAI Routes → Truncation State: reads and updates (evidence: `kiro/routes_openai.py`)
- Anthropic Routes → Truncation State: reads and updates (evidence: `kiro/routes_anthropic.py`)
- OpenAI Routes → Truncation Recovery: uses recovery (evidence: `kiro/routes_openai.py`)
- Anthropic Routes → Truncation Recovery: uses recovery (evidence: `kiro/routes_anthropic.py`)
- Kiro HTTP Client → VPN or Proxy: routes through proxy (evidence: `README.md`)
- OpenAI Routes → Debug Logging: records request activity (evidence: `kiro/routes_openai.py`)
- Anthropic Routes → Debug Logging: records request activity (evidence: `kiro/routes_anthropic.py`)
