# supremeai-bd/supremeai architecture

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

- Interactive diagram: https://gitdiagram.com/supremeai-bd/supremeai
- Repository: https://github.com/supremeai-bd/supremeai

## Overview

SupremeAI is a multi-service AI platform: consumers reach an OpenAI-compatible Gateway, while Core, Browser relay, and MCP Control Plane are separately owned active services. The main user-to-result path is documented at the Gateway boundary; the source index shows model routing and gateway implementation, but does not establish all runtime service wiring. The graph preserves documented service capabilities and substantial indexed Core modules without inferring calls between services where evidence is absent.

Main entry points: [`core/llm/llm_gateway/__init__.py`](https://github.com/supremeai-bd/supremeai/blob/main/core/llm/llm_gateway/__init__.py) (LLM gateway), [`core/api/routes/llm_gateway_routes.py`](https://github.com/supremeai-bd/supremeai/blob/main/core/api/routes/llm_gateway_routes.py) (Gateway management routes), [`api-schemas/gateway.openapi.yaml`](https://github.com/supremeai-bd/supremeai/blob/main/api-schemas/gateway.openapi.yaml) (Gateway API), [`gateway/dynamic_llm_router.py`](https://github.com/supremeai-bd/supremeai/blob/main/gateway/dynamic_llm_router.py) (Dynamic LLM router)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Consumer entry"]
  node_gateway_api["Gateway API"]
  node_gateway_router["Dynamic LLM router"]
  node_gateway_routes["Gateway management routes"]
end

subgraph group_ai["AI runtime"]
  node_model_router["Model router<br/>[model_router.py]"]
  node_llm_gateway["LLM gateway<br/>[__init__.py]"]
  node_completion["Completion handling<br/>[completion.py]"]
  node_providers["Model providers<br/>[__init__.py]"]
  node_free_tier["Free-tier tracking"]
end

subgraph group_platform["Core platform"]
  node_config["Runtime configuration<br/>[config.py]"]
  node_redis[("Redis cache<br/>[redis_manager.py]")]
  node_supabase[("Supabase persistence<br/>[supabase_client.py]")]
  node_error_bus["Error event pipeline<br/>[error_bus.py]"]
  node_error_remediation["Error remediation"]
  node_event_bus["Event bus<br/>[event_bus.py]"]
  node_evolution["Evolution engine"]
  node_learning["Learning pipeline"]
  node_memory["Memory service<br/>[memory_service.py]"]
end

subgraph group_relay["Browser relay"]
  node_browser["Browser relay<br/>[server.py]"]
  node_browser_runtime["Browser runtime<br/>[session_manager.py]"]
  node_browser_auth["Browser login<br/>[auto_login.py]"]
end

subgraph group_control["MCP control plane"]
  node_mcp["MCP Control Plane<br/>[engine.ts]"]
end

node_consumer(("API consumer"))

node_consumer -->|"requests"| node_gateway_api
node_gateway_api -.->|"routes requests"| node_gateway_router
node_gateway_router -.->|"selects models"| node_model_router
node_model_router -->|"invokes gateway"| node_llm_gateway
node_llm_gateway -->|"uses completion"| node_completion
node_llm_gateway -->|"loads providers"| node_providers
node_gateway_routes -->|"gets gateway"| node_llm_gateway
node_gateway_routes -->|"reads status"| node_free_tier
node_gateway_routes -.->|"auth dependency"| node_config
node_error_bus -->|"emits errors"| node_event_bus
node_error_remediation -->|"reports errors"| node_error_bus
node_learning -->|"uses memory"| node_memory
node_browser -.->|"uses sessions"| node_browser_runtime
node_browser_auth -.->|"supports login"| node_browser

click node_gateway_api "https://github.com/supremeai-bd/supremeai/blob/main/api-schemas/gateway.openapi.yaml"
click node_gateway_router "https://github.com/supremeai-bd/supremeai/blob/main/gateway/dynamic_llm_router.py"
click node_model_router "https://github.com/supremeai-bd/supremeai/blob/main/core/brain/model_router.py"
click node_llm_gateway "https://github.com/supremeai-bd/supremeai/blob/main/core/llm/llm_gateway/__init__.py"
click node_completion "https://github.com/supremeai-bd/supremeai/blob/main/core/llm/llm_gateway/completion.py"
click node_providers "https://github.com/supremeai-bd/supremeai/blob/main/core/llm/providers/__init__.py"
click node_free_tier "https://github.com/supremeai-bd/supremeai/blob/main/core/llm/free_tier_tracker.py"
click node_gateway_routes "https://github.com/supremeai-bd/supremeai/blob/main/core/api/routes/llm_gateway_routes.py"
click node_config "https://github.com/supremeai-bd/supremeai/blob/main/core/config.py"
click node_redis "https://github.com/supremeai-bd/supremeai/blob/main/core/cache/redis_manager.py"
click node_supabase "https://github.com/supremeai-bd/supremeai/blob/main/core/database/supabase_client.py"
click node_error_bus "https://github.com/supremeai-bd/supremeai/blob/main/core/errors/error_bus.py"
click node_error_remediation "https://github.com/supremeai-bd/supremeai/blob/main/core/errors/error_remediation.py"
click node_event_bus "https://github.com/supremeai-bd/supremeai/blob/main/core/messaging/event_bus.py"
click node_evolution "https://github.com/supremeai-bd/supremeai/blob/main/core/self_evolution/evolution_engine.py"
click node_learning "https://github.com/supremeai-bd/supremeai/blob/main/core/evolution/learning_pipeline.py"
click node_memory "https://github.com/supremeai-bd/supremeai/blob/main/core/services/memory_service.py"
click node_browser "https://github.com/supremeai-bd/supremeai/blob/main/browser/server.py"
click node_browser_runtime "https://github.com/supremeai-bd/supremeai/blob/main/browser/runtime/session_manager.py"
click node_browser_auth "https://github.com/supremeai-bd/supremeai/blob/main/browser/ghost_tower/auto_login.py"
click node_mcp "https://github.com/supremeai-bd/supremeai/blob/main/infrastructure/mcp-control-plane/src/guardian/engine.ts"

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_api,node_gateway_router,node_gateway_routes toneBlue
class node_model_router,node_llm_gateway,node_completion,node_providers,node_free_tier toneAmber
class node_config,node_redis,node_supabase,node_error_bus,node_error_remediation,node_event_bus,node_evolution,node_learning,node_memory,node_consumer toneMint
class node_browser,node_browser_runtime,node_browser_auth toneRose
class node_mcp toneIndigo
```

## Components

### Consumer entry

- [Gateway API](https://github.com/supremeai-bd/supremeai/blob/main/api-schemas/gateway.openapi.yaml): `api-schemas/gateway.openapi.yaml`
- [Dynamic LLM router](https://github.com/supremeai-bd/supremeai/blob/main/gateway/dynamic_llm_router.py): `gateway/dynamic_llm_router.py`
- [Gateway management routes](https://github.com/supremeai-bd/supremeai/blob/main/core/api/routes/llm_gateway_routes.py): `core/api/routes/llm_gateway_routes.py`

### AI runtime

- [Model router](https://github.com/supremeai-bd/supremeai/blob/main/core/brain/model_router.py): `core/brain/model_router.py`
- [LLM gateway](https://github.com/supremeai-bd/supremeai/blob/main/core/llm/llm_gateway/__init__.py): `core/llm/llm_gateway/__init__.py`
- [Completion handling](https://github.com/supremeai-bd/supremeai/blob/main/core/llm/llm_gateway/completion.py): `core/llm/llm_gateway/completion.py`
- [Model providers](https://github.com/supremeai-bd/supremeai/blob/main/core/llm/providers/__init__.py): `core/llm/providers/__init__.py`
- [Free-tier tracking](https://github.com/supremeai-bd/supremeai/blob/main/core/llm/free_tier_tracker.py): `core/llm/free_tier_tracker.py`

### Core platform

- [Runtime configuration](https://github.com/supremeai-bd/supremeai/blob/main/core/config.py): `core/config.py`
- [Redis cache](https://github.com/supremeai-bd/supremeai/blob/main/core/cache/redis_manager.py): `core/cache/redis_manager.py`
- [Supabase persistence](https://github.com/supremeai-bd/supremeai/blob/main/core/database/supabase_client.py): `core/database/supabase_client.py`
- [Error event pipeline](https://github.com/supremeai-bd/supremeai/blob/main/core/errors/error_bus.py): `core/errors/error_bus.py`
- [Error remediation](https://github.com/supremeai-bd/supremeai/blob/main/core/errors/error_remediation.py): `core/errors/error_remediation.py`
- [Event bus](https://github.com/supremeai-bd/supremeai/blob/main/core/messaging/event_bus.py): `core/messaging/event_bus.py`
- [Evolution engine](https://github.com/supremeai-bd/supremeai/blob/main/core/self_evolution/evolution_engine.py): `core/self_evolution/evolution_engine.py`
- [Learning pipeline](https://github.com/supremeai-bd/supremeai/blob/main/core/evolution/learning_pipeline.py): `core/evolution/learning_pipeline.py`
- [Memory service](https://github.com/supremeai-bd/supremeai/blob/main/core/services/memory_service.py): `core/services/memory_service.py`

### Browser relay

- [Browser relay](https://github.com/supremeai-bd/supremeai/blob/main/browser/server.py): `browser/server.py`
- [Browser runtime](https://github.com/supremeai-bd/supremeai/blob/main/browser/runtime/session_manager.py): `browser/runtime/session_manager.py`
- [Browser login](https://github.com/supremeai-bd/supremeai/blob/main/browser/ghost_tower/auto_login.py): `browser/ghost_tower/auto_login.py`

### MCP control plane

- [MCP Control Plane](https://github.com/supremeai-bd/supremeai/blob/main/infrastructure/mcp-control-plane/src/guardian/engine.ts): `infrastructure/mcp-control-plane/src/guardian/engine.ts`

### Other components

- **API consumer**

## Connections

- API consumer → Gateway API: requests (evidence: `README.md`)
- Gateway API → Dynamic LLM router: routes requests
- Dynamic LLM router → Model router: selects models
- Model router → LLM gateway: invokes gateway (evidence: `core/brain/model_router.py`)
- LLM gateway → Completion handling: uses completion (evidence: `core/llm/llm_gateway/__init__.py`)
- LLM gateway → Model providers: loads providers (evidence: `core/llm/llm_gateway/__init__.py`)
- Gateway management routes → LLM gateway: gets gateway (evidence: `core/api/routes/llm_gateway_routes.py`)
- Gateway management routes → Free-tier tracking: reads status (evidence: `core/api/routes/llm_gateway_routes.py`)
- Gateway management routes → Runtime configuration: auth dependency
- Error event pipeline → Event bus: emits errors (evidence: `core/errors/error_bus.py`)
- Error remediation → Error event pipeline: reports errors (evidence: `core/errors/error_remediation.py`)
- Learning pipeline → Memory service: uses memory (evidence: `core/evolution/learning_pipeline.py`)
- Browser relay → Browser runtime: uses sessions
- Browser login → Browser relay: supports login
