# aws-samples/sample-kolya-br-proxy architecture

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

- Interactive diagram: https://gitdiagram.com/aws-samples/sample-kolya-br-proxy
- Repository: https://github.com/aws-samples/sample-kolya-br-proxy

## Overview

Kolya BR Proxy is a multi-provider AI gateway with OpenAI-compatible and Anthropic Messages interfaces, plus an administrative web console. A client request enters a compatible API endpoint, is authenticated and quota-checked, routed to a provider-specific adapter, and returned in the requested format; usage and pricing support billing and administration. The README documents those routing capabilities, while sampled source confirms the app entry point, API routers, provider clients, database and frontend routes. Some internal call wiring is unsampled, so links below reflect documented behavior rather than asserted implementation details.

Main entry points: [`backend/app/api/v1/router.py`](https://github.com/aws-samples/sample-kolya-br-proxy/blob/main/backend/app/api/v1/router.py) (OpenAI API), [`backend/app/api/anthropic/router.py`](https://github.com/aws-samples/sample-kolya-br-proxy/blob/main/backend/app/api/anthropic/router.py) (Anthropic API), [`backend/app/core/database.py`](https://github.com/aws-samples/sample-kolya-br-proxy/blob/main/backend/app/core/database.py) (PostgreSQL), [`backend/app/services/translator.py`](https://github.com/aws-samples/sample-kolya-br-proxy/blob/main/backend/app/services/translator.py) (Format translation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_gateway["API gateway"]
  node_backend["FastAPI application<br/>[main.py]"]
  node_openai_api["OpenAI API<br/>[router.py]"]
  node_anthropic_api["Anthropic API<br/>[router.py]"]
  node_auth_quota["Token and quota<br/>[auth.py]"]
  node_translator["Format translation<br/>[translator.py]"]
  node_anthropic_translation["Anthropic translation"]
  node_usage["Usage tracking<br/>[usage_stats.py]"]
end

subgraph group_providers["Model providers"]
  node_bedrock["Bedrock client<br/>[bedrock.py]"]
  node_gemini["Gemini client<br/>[gemini_client.py]"]
  node_mantle["Mantle client<br/>[mantle_client.py]"]
end

subgraph group_operations["Admin and operations"]
  node_frontend["Admin console<br/>[App.vue]"]
  node_admin_api["Admin endpoints<br/>[router.py]"]
  node_oauth["OAuth services<br/>[oauth.py]"]
  node_pricing["Pricing updates<br/>[pricing_updater.py]"]
  node_scheduler["Pricing scheduler<br/>[pricing_tasks.py]"]
end

subgraph group_state["Persistence and shared services"]
  node_database[("PostgreSQL<br/>[database.py]")]
  node_redis[("Redis configuration<br/>[redis.py]")]
  node_models["Domain records"]
end

node_client(("API client"))
node_bedrock_service{{"AWS Bedrock"}}
node_gemini_service{{"Google Gemini"}}
node_mantle_service{{"AWS mantle"}}

node_client -->|"sends OpenAI requests"| node_openai_api
node_client -->|"sends Messages requests"| node_anthropic_api
node_openai_api -->|"handled by app"| node_backend
node_anthropic_api -->|"handled by app"| node_backend
node_openai_api -->|"validates token"| node_auth_quota
node_anthropic_api -->|"validates token"| node_auth_quota
node_openai_api -->|"translates formats"| node_translator
node_anthropic_api -->|"translates formats"| node_anthropic_translation
node_translator -->|"routes other models"| node_bedrock
node_translator -->|"routes Gemini models"| node_gemini
node_translator -->|"routes OpenAI models"| node_mantle
node_anthropic_translation -->|"routes other models"| node_bedrock
node_anthropic_translation -->|"routes Gemini models"| node_gemini
node_anthropic_translation -->|"routes OpenAI models"| node_mantle
node_bedrock -->|"invokes models"| node_bedrock_service
node_gemini -->|"calls generateContent"| node_gemini_service
node_mantle -->|"calls Responses API"| node_mantle_service
node_openai_api -->|"records usage"| node_usage
node_anthropic_api -->|"records usage"| node_usage
node_frontend -->|"uses admin API"| node_admin_api
node_admin_api -->|"handles sign-in"| node_oauth
node_admin_api -->|"manages pricing"| node_pricing
node_scheduler -->|"runs refresh"| node_pricing
node_backend -->|"initializes database"| node_database
node_usage -->|"records usage"| node_database
node_pricing -->|"stores pricing"| node_database
node_admin_api -->|"reads and writes"| node_database
node_backend -->|"subscribes configuration"| node_redis
node_database -->|"stores records"| node_models

click node_backend "https://github.com/aws-samples/sample-kolya-br-proxy/blob/main/backend/main.py"
click node_openai_api "https://github.com/aws-samples/sample-kolya-br-proxy/blob/main/backend/app/api/v1/router.py"
click node_anthropic_api "https://github.com/aws-samples/sample-kolya-br-proxy/blob/main/backend/app/api/anthropic/router.py"
click node_auth_quota "https://github.com/aws-samples/sample-kolya-br-proxy/blob/main/backend/app/services/auth.py"
click node_translator "https://github.com/aws-samples/sample-kolya-br-proxy/blob/main/backend/app/services/translator.py"
click node_anthropic_translation "https://github.com/aws-samples/sample-kolya-br-proxy/blob/main/backend/app/services/anthropic_translator.py"
click node_usage "https://github.com/aws-samples/sample-kolya-br-proxy/blob/main/backend/app/services/usage_stats.py"
click node_bedrock "https://github.com/aws-samples/sample-kolya-br-proxy/blob/main/backend/app/services/bedrock.py"
click node_gemini "https://github.com/aws-samples/sample-kolya-br-proxy/blob/main/backend/app/services/gemini_client.py"
click node_mantle "https://github.com/aws-samples/sample-kolya-br-proxy/blob/main/backend/app/services/mantle_client.py"
click node_frontend "https://github.com/aws-samples/sample-kolya-br-proxy/blob/main/frontend/src/App.vue"
click node_admin_api "https://github.com/aws-samples/sample-kolya-br-proxy/blob/main/backend/app/api/admin/router.py"
click node_oauth "https://github.com/aws-samples/sample-kolya-br-proxy/blob/main/backend/app/services/oauth.py"
click node_pricing "https://github.com/aws-samples/sample-kolya-br-proxy/blob/main/backend/app/services/pricing_updater.py"
click node_scheduler "https://github.com/aws-samples/sample-kolya-br-proxy/blob/main/backend/app/tasks/pricing_tasks.py"
click node_database "https://github.com/aws-samples/sample-kolya-br-proxy/blob/main/backend/app/core/database.py"
click node_redis "https://github.com/aws-samples/sample-kolya-br-proxy/blob/main/backend/app/core/redis.py"
click node_models "https://github.com/aws-samples/sample-kolya-br-proxy/tree/main/backend/app/models"

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_backend,node_openai_api,node_anthropic_api,node_auth_quota,node_translator,node_anthropic_translation,node_usage,node_client toneBlue
class node_bedrock,node_gemini,node_mantle toneAmber
class node_frontend,node_admin_api,node_oauth,node_pricing,node_scheduler toneMint
class node_database,node_redis,node_models toneRose
class node_bedrock_service,node_gemini_service,node_mantle_service toneIndigo
```

## Components

### API gateway

- [FastAPI application](https://github.com/aws-samples/sample-kolya-br-proxy/blob/main/backend/main.py): `backend/main.py`
- [OpenAI API](https://github.com/aws-samples/sample-kolya-br-proxy/blob/main/backend/app/api/v1/router.py): `backend/app/api/v1/router.py`
- [Anthropic API](https://github.com/aws-samples/sample-kolya-br-proxy/blob/main/backend/app/api/anthropic/router.py): `backend/app/api/anthropic/router.py`
- [Token and quota](https://github.com/aws-samples/sample-kolya-br-proxy/blob/main/backend/app/services/auth.py): `backend/app/services/auth.py`
- [Format translation](https://github.com/aws-samples/sample-kolya-br-proxy/blob/main/backend/app/services/translator.py): `backend/app/services/translator.py`
- [Anthropic translation](https://github.com/aws-samples/sample-kolya-br-proxy/blob/main/backend/app/services/anthropic_translator.py): `backend/app/services/anthropic_translator.py`
- [Usage tracking](https://github.com/aws-samples/sample-kolya-br-proxy/blob/main/backend/app/services/usage_stats.py): `backend/app/services/usage_stats.py`

### Model providers

- [Bedrock client](https://github.com/aws-samples/sample-kolya-br-proxy/blob/main/backend/app/services/bedrock.py): `backend/app/services/bedrock.py`
- [Gemini client](https://github.com/aws-samples/sample-kolya-br-proxy/blob/main/backend/app/services/gemini_client.py): `backend/app/services/gemini_client.py`
- [Mantle client](https://github.com/aws-samples/sample-kolya-br-proxy/blob/main/backend/app/services/mantle_client.py): `backend/app/services/mantle_client.py`

### Admin and operations

- [Admin console](https://github.com/aws-samples/sample-kolya-br-proxy/blob/main/frontend/src/App.vue): `frontend/src/App.vue`
- [Admin endpoints](https://github.com/aws-samples/sample-kolya-br-proxy/blob/main/backend/app/api/admin/router.py): `backend/app/api/admin/router.py`
- [OAuth services](https://github.com/aws-samples/sample-kolya-br-proxy/blob/main/backend/app/services/oauth.py): `backend/app/services/oauth.py`
- [Pricing updates](https://github.com/aws-samples/sample-kolya-br-proxy/blob/main/backend/app/services/pricing_updater.py): `backend/app/services/pricing_updater.py`
- [Pricing scheduler](https://github.com/aws-samples/sample-kolya-br-proxy/blob/main/backend/app/tasks/pricing_tasks.py): `backend/app/tasks/pricing_tasks.py`

### Persistence and shared services

- [PostgreSQL](https://github.com/aws-samples/sample-kolya-br-proxy/blob/main/backend/app/core/database.py): `backend/app/core/database.py`
- [Redis configuration](https://github.com/aws-samples/sample-kolya-br-proxy/blob/main/backend/app/core/redis.py): `backend/app/core/redis.py`
- [Domain records](https://github.com/aws-samples/sample-kolya-br-proxy/tree/main/backend/app/models): `backend/app/models`

### Other components

- **API client**
- **AWS Bedrock**
- **Google Gemini**
- **AWS mantle**

## Connections

- API client → OpenAI API: sends OpenAI requests
- API client → Anthropic API: sends Messages requests
- OpenAI API → FastAPI application: handled by app
- Anthropic API → FastAPI application: handled by app
- OpenAI API → Token and quota: validates token
- Anthropic API → Token and quota: validates token
- OpenAI API → Format translation: translates formats
- Anthropic API → Anthropic translation: translates formats
- Format translation → Bedrock client: routes other models
- Format translation → Gemini client: routes Gemini models
- Format translation → Mantle client: routes OpenAI models
- Anthropic translation → Bedrock client: routes other models
- Anthropic translation → Gemini client: routes Gemini models
- Anthropic translation → Mantle client: routes OpenAI models
- Bedrock client → AWS Bedrock: invokes models
- Gemini client → Google Gemini: calls generateContent
- Mantle client → AWS mantle: calls Responses API
- OpenAI API → Usage tracking: records usage
- Anthropic API → Usage tracking: records usage
- Admin console → Admin endpoints: uses admin API
- Admin endpoints → OAuth services: handles sign-in
- Admin endpoints → Pricing updates: manages pricing
- Pricing scheduler → Pricing updates: runs refresh
- FastAPI application → PostgreSQL: initializes database
- Usage tracking → PostgreSQL: records usage
- Pricing updates → PostgreSQL: stores pricing
- Admin endpoints → PostgreSQL: reads and writes
- FastAPI application → Redis configuration: subscribes configuration
- PostgreSQL → Domain records: stores records