# pragatheeswaran-sv/llm_gateway architecture

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

- Interactive diagram: https://gitdiagram.com/pragatheeswaran-sv/llm_gateway
- Repository: https://github.com/pragatheeswaran-sv/llm_gateway

## Overview

LLM Gateway is a FastAPI service that registers client applications, issues access tokens, and generates or updates database schemas as DBML. The main workflow validates a bearer token, builds a prompt from the user's query and existing DBML, calls an LLM directly or through configured fallback models, and returns DBML, an explanation, and optionally a summary; request outcomes are logged. Registration and token issuance form a separate onboarding workflow. Some service and fallback source is excerpted only partially, so uncertain internal call details are omitted.

Main entry points: [`src/conversation/service.py`](https://github.com/pragatheeswaran-sv/llm_gateway/blob/main/src/conversation/service.py) (Generation orchestration), [`src/main.py`](https://github.com/pragatheeswaran-sv/llm_gateway/blob/main/src/main.py) (FastAPI app), [`src/conversation/api.py`](https://github.com/pragatheeswaran-sv/llm_gateway/blob/main/src/conversation/api.py) (Generation API), [`src/database.py`](https://github.com/pragatheeswaran-sv/llm_gateway/blob/main/src/database.py) (Database engine and sessions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["API entry"]
  node_app["FastAPI app<br/>[main.py]"]
  node_conversation_api["Generation API<br/>[api.py]"]
end

subgraph group_onboarding["Application onboarding"]
  node_registration_api["Registration API<br/>[api.py]"]
  node_registration_service["Registration service<br/>[service.py]"]
  node_application_record["Application record<br/>[models.py]"]
  node_token_helpers["Credential and token helpers<br/>[helper.py]"]
end

subgraph group_generation["DBML generation"]
  node_generation_service["Generation orchestration<br/>[service.py]"]
  node_request_schema["Request and response schemas<br/>[schemas.py]"]
  node_fallback_logic["Fallback selection and provider calls<br/>[fallback.py]"]
end

subgraph group_state["Persistence and configuration"]
  node_conversation_records["Conversation and fallback records<br/>[models.py]"]
  node_request_logs["Request logs<br/>[models.py]"]
  node_database[("Database engine and sessions<br/>[database.py]")]
  node_settings["Runtime settings<br/>[config.py]"]
end

node_client(("API client"))
node_llm_provider{{"LLM provider"}}

node_client -->|"sends requests"| node_app
node_app -->|"routes requests"| node_registration_api
node_app -->|"routes requests"| node_conversation_api
node_registration_api -->|"calls"| node_registration_service
node_registration_service -->|"reads and writes"| node_application_record
node_registration_service -->|"uses credentials"| node_token_helpers
node_registration_api -->|"returns credentials or token"| node_client
node_conversation_api -->|"validates and shapes"| node_request_schema
node_conversation_api -->|"calls"| node_generation_service
node_generation_service -->|"validates token"| node_token_helpers
node_generation_service -->|"calls provider logic"| node_fallback_logic
node_fallback_logic -->|"sends completion request"| node_llm_provider
node_generation_service -->|"reads fallback state"| node_conversation_records
node_generation_service -->|"records attempts"| node_request_logs
node_conversation_api -->|"starts and finishes logs"| node_request_logs
node_application_record -->|"uses ORM base"| node_database
node_conversation_records -->|"uses ORM base"| node_database
node_app -->|"creates tables at startup"| node_database
node_database -->|"reads database URL"| node_settings
node_token_helpers -->|"reads token settings"| node_settings
node_generation_service -->|"reads generation settings"| node_settings

click node_app "https://github.com/pragatheeswaran-sv/llm_gateway/blob/main/src/main.py"
click node_registration_api "https://github.com/pragatheeswaran-sv/llm_gateway/blob/main/src/register_application/api.py"
click node_registration_service "https://github.com/pragatheeswaran-sv/llm_gateway/blob/main/src/register_application/service.py"
click node_application_record "https://github.com/pragatheeswaran-sv/llm_gateway/blob/main/src/register_application/models.py"
click node_token_helpers "https://github.com/pragatheeswaran-sv/llm_gateway/blob/main/src/utils/helper.py"
click node_conversation_api "https://github.com/pragatheeswaran-sv/llm_gateway/blob/main/src/conversation/api.py"
click node_generation_service "https://github.com/pragatheeswaran-sv/llm_gateway/blob/main/src/conversation/service.py"
click node_request_schema "https://github.com/pragatheeswaran-sv/llm_gateway/blob/main/src/conversation/schemas.py"
click node_fallback_logic "https://github.com/pragatheeswaran-sv/llm_gateway/blob/main/src/conversation/fallback.py"
click node_conversation_records "https://github.com/pragatheeswaran-sv/llm_gateway/blob/main/src/conversation/models.py"
click node_request_logs "https://github.com/pragatheeswaran-sv/llm_gateway/blob/main/src/conversation/models.py"
click node_database "https://github.com/pragatheeswaran-sv/llm_gateway/blob/main/src/database.py"
click node_settings "https://github.com/pragatheeswaran-sv/llm_gateway/blob/main/src/config.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_app,node_conversation_api,node_client toneBlue
class node_registration_api,node_registration_service,node_application_record,node_token_helpers toneAmber
class node_generation_service,node_request_schema,node_fallback_logic toneMint
class node_conversation_records,node_request_logs,node_database,node_settings toneRose
class node_llm_provider toneIndigo
```

## Components

### API entry

- [FastAPI app](https://github.com/pragatheeswaran-sv/llm_gateway/blob/main/src/main.py): `src/main.py`
- [Generation API](https://github.com/pragatheeswaran-sv/llm_gateway/blob/main/src/conversation/api.py): `src/conversation/api.py`

### Application onboarding

- [Registration API](https://github.com/pragatheeswaran-sv/llm_gateway/blob/main/src/register_application/api.py): `src/register_application/api.py`
- [Registration service](https://github.com/pragatheeswaran-sv/llm_gateway/blob/main/src/register_application/service.py): `src/register_application/service.py`
- [Application record](https://github.com/pragatheeswaran-sv/llm_gateway/blob/main/src/register_application/models.py): `src/register_application/models.py`
- [Credential and token helpers](https://github.com/pragatheeswaran-sv/llm_gateway/blob/main/src/utils/helper.py): `src/utils/helper.py`

### DBML generation

- [Generation orchestration](https://github.com/pragatheeswaran-sv/llm_gateway/blob/main/src/conversation/service.py): `src/conversation/service.py`
- [Request and response schemas](https://github.com/pragatheeswaran-sv/llm_gateway/blob/main/src/conversation/schemas.py): `src/conversation/schemas.py`
- [Fallback selection and provider calls](https://github.com/pragatheeswaran-sv/llm_gateway/blob/main/src/conversation/fallback.py): `src/conversation/fallback.py`

### Persistence and configuration

- [Conversation and fallback records](https://github.com/pragatheeswaran-sv/llm_gateway/blob/main/src/conversation/models.py): `src/conversation/models.py`
- [Request logs](https://github.com/pragatheeswaran-sv/llm_gateway/blob/main/src/conversation/models.py): `src/conversation/models.py`
- [Database engine and sessions](https://github.com/pragatheeswaran-sv/llm_gateway/blob/main/src/database.py): `src/database.py`
- [Runtime settings](https://github.com/pragatheeswaran-sv/llm_gateway/blob/main/src/config.py): `src/config.py`

### Other components

- **API client**
- **LLM provider**

## Connections

- API client → FastAPI app: sends requests (evidence: `src/main.py`)
- FastAPI app → Registration API: routes requests (evidence: `src/main.py`)
- FastAPI app → Generation API: routes requests (evidence: `src/main.py`)
- Registration API → Registration service: calls (evidence: `src/register_application/api.py`)
- Registration service → Application record: reads and writes (evidence: `src/register_application/service.py`)
- Registration service → Credential and token helpers: uses credentials (evidence: `src/register_application/service.py`)
- Registration API → API client: returns credentials or token (evidence: `src/register_application/api.py`)
- Generation API → Request and response schemas: validates and shapes (evidence: `src/conversation/api.py`)
- Generation API → Generation orchestration: calls (evidence: `src/conversation/api.py`)
- Generation orchestration → Credential and token helpers: validates token (evidence: `src/conversation/service.py`)
- Generation orchestration → Fallback selection and provider calls: calls provider logic (evidence: `src/conversation/service.py`)
- Fallback selection and provider calls → LLM provider: sends completion request (evidence: `src/conversation/fallback.py`)
- Generation orchestration → Conversation and fallback records: reads fallback state (evidence: `src/conversation/service.py`)
- Generation orchestration → Request logs: records attempts (evidence: `src/conversation/service.py`)
- Generation API → Request logs: starts and finishes logs (evidence: `src/conversation/api.py`)
- Application record → Database engine and sessions: uses ORM base (evidence: `src/register_application/models.py`)
- Conversation and fallback records → Database engine and sessions: uses ORM base (evidence: `src/conversation/models.py`)
- FastAPI app → Database engine and sessions: creates tables at startup (evidence: `src/main.py`)
- Database engine and sessions → Runtime settings: reads database URL (evidence: `src/database.py`)
- Credential and token helpers → Runtime settings: reads token settings (evidence: `src/utils/helper.py`)
- Generation orchestration → Runtime settings: reads generation settings (evidence: `src/conversation/service.py`)
