# verdgard/intergate architecture

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

## Overview

InterGate is a self-hosted AI API relay and management console. Client requests enter the gateway, which authenticates and routes them through provider-specific upstream forwarding, applying Key selection, rate limits, caching, failover, and usage/quota accounting. Operators use the Web console to manage Keys, settings, models, and logs; scheduled synchronization refreshes model data, while SQLite preserves operational state. The README documents several capabilities whose implementation was not sampled; those branches are represented at their documented module paths, with uncertain internal wiring omitted.

Main entry points: [`gateway.py`](https://github.com/verdgard/intergate/blob/main/gateway.py) (API gateway), [`db/database.py`](https://github.com/verdgard/intergate/blob/main/db/database.py) (SQLite store), [`webapp.py`](https://github.com/verdgard/intergate/blob/main/webapp.py) (Web management API), [`main.py`](https://github.com/verdgard/intergate/blob/main/main.py) (Runtime coordinator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry points"]
  node_gateway["API gateway<br/>[gateway.py]"]
  node_webapp["Web management API<br/>[webapp.py]"]
  node_console["Web console<br/>[index.html]"]
  node_main["Runtime coordinator<br/>[main.py]"]
end

subgraph group_routing["Request routing"]
  node_registry["Provider routing<br/>[registry.py]"]
  node_upstream["Upstream forwarding<br/>[upstream.py]"]
  node_balancer["Key load balancing<br/>[load_balancer.py]"]
  node_cache["Response cache<br/>[cache.py]"]
  node_ratelimit["Rate limiting<br/>[rate_limiter.py]"]
end

subgraph group_management["Management"]
  node_keymgr["Key lifecycle<br/>[key_manager.py]"]
  node_crypto["Key encryption<br/>[aes.py]"]
  node_sync["Model synchronization<br/>[sync.py]"]
  node_models["Model records<br/>[database.py]"]
  node_settings["Runtime settings<br/>[settings.py]"]
end

subgraph group_state["Persistent state"]
  node_database[("SQLite store<br/>[database.py]")]
  node_logs["Request logs<br/>[request_log.py]"]
end

subgraph group_operations["Usage and operations"]
  node_quota["Quota monitoring<br/>[quota.py]"]
  node_usage["Usage accounting<br/>[usage.py]"]
  node_health["Health and metrics<br/>[health.py]"]
  node_webhook["Alert delivery<br/>[webhook.py]"]
end

node_client(("AI client"))
node_browser(("Operator browser"))
node_providers{{"AI providers"}}

node_client -->|"sends API requests"| node_gateway
node_browser -->|"opens console"| node_console
node_console -->|"calls management API"| node_webapp
node_main -->|"starts server"| node_gateway
node_main -->|"starts server"| node_webapp
node_main -->|"schedules sync"| node_sync
node_main -->|"prunes logs"| node_database
node_gateway -->|"identifies provider"| node_registry
node_gateway -->|"selects Key"| node_balancer
node_gateway -->|"loads Key state"| node_keymgr
node_gateway -->|"checks limits"| node_ratelimit
node_gateway -->|"checks response cache"| node_cache
node_gateway -->|"forwards request"| node_upstream
node_upstream -->|"sends API request"| node_providers
node_gateway -->|"records quota usage"| node_quota
node_gateway -->|"records usage"| node_usage
node_gateway -->|"writes request data"| node_database
node_webapp -->|"manages Keys"| node_keymgr
node_webapp -->|"updates settings"| node_settings
node_webapp -->|"reads management data"| node_database
node_keymgr -->|"encrypts and decrypts"| node_crypto
node_keymgr -->|"loads and saves Keys"| node_database
node_sync -->|"fetches model data"| node_upstream
node_sync -->|"stores model cache"| node_database
node_database -->|"stores model records"| node_models
node_database -->|"stores request records"| node_logs
node_quota -.->|"sends alerts"| node_webhook
node_health -->|"reads operational data"| node_database

click node_gateway "https://github.com/verdgard/intergate/blob/main/gateway.py"
click node_webapp "https://github.com/verdgard/intergate/blob/main/webapp.py"
click node_console "https://github.com/verdgard/intergate/blob/main/web/index.html"
click node_main "https://github.com/verdgard/intergate/blob/main/main.py"
click node_registry "https://github.com/verdgard/intergate/blob/main/providers/registry.py"
click node_upstream "https://github.com/verdgard/intergate/blob/main/providers/upstream.py"
click node_balancer "https://github.com/verdgard/intergate/blob/main/services/load_balancer.py"
click node_keymgr "https://github.com/verdgard/intergate/blob/main/services/key_manager.py"
click node_crypto "https://github.com/verdgard/intergate/blob/main/crypto/aes.py"
click node_sync "https://github.com/verdgard/intergate/blob/main/services/sync.py"
click node_models "https://github.com/verdgard/intergate/blob/main/db/database.py"
click node_settings "https://github.com/verdgard/intergate/blob/main/config/settings.py"
click node_cache "https://github.com/verdgard/intergate/blob/main/services/cache.py"
click node_ratelimit "https://github.com/verdgard/intergate/blob/main/services/rate_limiter.py"
click node_quota "https://github.com/verdgard/intergate/blob/main/services/quota.py"
click node_usage "https://github.com/verdgard/intergate/blob/main/services/usage.py"
click node_health "https://github.com/verdgard/intergate/blob/main/services/health.py"
click node_webhook "https://github.com/verdgard/intergate/blob/main/services/webhook.py"
click node_database "https://github.com/verdgard/intergate/blob/main/db/database.py"
click node_logs "https://github.com/verdgard/intergate/blob/main/models/request_log.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_gateway,node_webapp,node_console,node_main,node_client,node_browser toneBlue
class node_registry,node_upstream,node_balancer,node_cache,node_ratelimit toneAmber
class node_keymgr,node_crypto,node_sync,node_models,node_settings toneMint
class node_database,node_logs toneRose
class node_quota,node_usage,node_health,node_webhook,node_providers toneIndigo
```

## Components

### Entry points

- [API gateway](https://github.com/verdgard/intergate/blob/main/gateway.py): `gateway.py`
- [Web management API](https://github.com/verdgard/intergate/blob/main/webapp.py): `webapp.py`
- [Web console](https://github.com/verdgard/intergate/blob/main/web/index.html): `web/index.html`
- [Runtime coordinator](https://github.com/verdgard/intergate/blob/main/main.py): `main.py`

### Request routing

- [Provider routing](https://github.com/verdgard/intergate/blob/main/providers/registry.py): `providers/registry.py`
- [Upstream forwarding](https://github.com/verdgard/intergate/blob/main/providers/upstream.py): `providers/upstream.py`
- [Key load balancing](https://github.com/verdgard/intergate/blob/main/services/load_balancer.py): `services/load_balancer.py`
- [Response cache](https://github.com/verdgard/intergate/blob/main/services/cache.py): `services/cache.py`
- [Rate limiting](https://github.com/verdgard/intergate/blob/main/services/rate_limiter.py): `services/rate_limiter.py`

### Management

- [Key lifecycle](https://github.com/verdgard/intergate/blob/main/services/key_manager.py): `services/key_manager.py`
- [Key encryption](https://github.com/verdgard/intergate/blob/main/crypto/aes.py): `crypto/aes.py`
- [Model synchronization](https://github.com/verdgard/intergate/blob/main/services/sync.py): `services/sync.py`
- [Model records](https://github.com/verdgard/intergate/blob/main/db/database.py): `db/database.py`
- [Runtime settings](https://github.com/verdgard/intergate/blob/main/config/settings.py): `config/settings.py`

### Persistent state

- [SQLite store](https://github.com/verdgard/intergate/blob/main/db/database.py): `db/database.py`
- [Request logs](https://github.com/verdgard/intergate/blob/main/models/request_log.py): `models/request_log.py`

### Usage and operations

- [Quota monitoring](https://github.com/verdgard/intergate/blob/main/services/quota.py): `services/quota.py`
- [Usage accounting](https://github.com/verdgard/intergate/blob/main/services/usage.py): `services/usage.py`
- [Health and metrics](https://github.com/verdgard/intergate/blob/main/services/health.py): `services/health.py`
- [Alert delivery](https://github.com/verdgard/intergate/blob/main/services/webhook.py): `services/webhook.py`

### Other components

- **AI client**
- **Operator browser**
- **AI providers**

## Connections

- AI client → API gateway: sends API requests
- Operator browser → Web console: opens console
- Web console → Web management API: calls management API
- Runtime coordinator → API gateway: starts server
- Runtime coordinator → Web management API: starts server
- Runtime coordinator → Model synchronization: schedules sync
- Runtime coordinator → SQLite store: prunes logs
- API gateway → Provider routing: identifies provider
- API gateway → Key load balancing: selects Key
- API gateway → Key lifecycle: loads Key state
- API gateway → Rate limiting: checks limits
- API gateway → Response cache: checks response cache
- API gateway → Upstream forwarding: forwards request
- Upstream forwarding → AI providers: sends API request
- API gateway → Quota monitoring: records quota usage
- API gateway → Usage accounting: records usage
- API gateway → SQLite store: writes request data
- Web management API → Key lifecycle: manages Keys
- Web management API → Runtime settings: updates settings
- Web management API → SQLite store: reads management data
- Key lifecycle → Key encryption: encrypts and decrypts
- Key lifecycle → SQLite store: loads and saves Keys
- Model synchronization → Upstream forwarding: fetches model data
- Model synchronization → SQLite store: stores model cache
- SQLite store → Model records: stores model records
- SQLite store → Request logs: stores request records
- Quota monitoring → Alert delivery: sends alerts
- Health and metrics → SQLite store: reads operational data