# saifulhaqueniloy/supremeai architecture

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

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

## Overview

SupremeAI is a governed, model-agnostic task-execution platform. Its documented user journey is to understand a goal, discover and compose capabilities, apply policy, execute, verify or repair, deliver, and retain reusable experience. The graph combines that workflow with sampled task, context, LLM, governance, and learning components, plus README-documented capability areas. Some source-index modules are not present in the supplied tree; their paths come from the index. Unsampled subsystem links are omitted or marked unverified.

Main entry points: [`backend/adaptive_engine/task_engine.py`](https://github.com/saifulhaqueniloy/supremeai/blob/main/backend/adaptive_engine/task_engine.py) (Task State Machine), [`backend/core/llm/llm_gateway`](https://github.com/saifulhaqueniloy/supremeai/tree/main/backend/core/llm/llm_gateway) (LLM Gateway), [`backend/context/engine.py`](https://github.com/saifulhaqueniloy/supremeai/blob/main/backend/context/engine.py) (Context Assembly), [`backend/core/autonoguard_engine.py`](https://github.com/saifulhaqueniloy/supremeai/blob/main/backend/core/autonoguard_engine.py) (AutonoGuard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Task Experience"]
  node_frontend["Frontend"]
end

subgraph group_execution["Planning &amp; Execution"]
  node_task["Task State Machine<br/>[task_engine.py]"]
  node_capabilities["Capability Surface"]
  node_planrecipes["Pipeline Recipes"]
  node_debate["Agent Debate<br/>[debate_engine.py]"]
  node_video["Video-to-Code"]
end

subgraph group_intelligence["Models &amp; Context"]
  node_context["Context Assembly<br/>[engine.py]"]
  node_contextitems["Context Items<br/>[items.py]"]
  node_contextbudget["Context Budget<br/>[budget.py]"]
  node_modelrouter["Model Router<br/>[model_router.py]"]
  node_gateway["LLM Gateway"]
  node_completion["Completions<br/>[completion.py]"]
  node_tokenbudget["Token Budget<br/>[token_budget.py]"]
  node_rag["RAG Pipeline<br/>[rag_pipeline.py]"]
end

subgraph group_governance["Governance &amp; Learning"]
  node_policy["External Policy<br/>[policy_engine.py]"]
  node_guard["AutonoGuard"]
  node_learning["Learning Pipeline"]
  node_hypotheses["Hypothesis Learning"]
end

subgraph group_platform["API &amp; State"]
  node_api["FastAPI<br/>[main.py]"]
  node_routes["Mission API<br/>[missions.py]"]
  node_memory["Memory Service<br/>[memory_service.py]"]
  node_store[("Adaptive Store<br/>[_store.py]")]
  node_redis[("Redis Cache<br/>[redis_manager.py]")]
  node_events["Event Bus<br/>[event_bus.py]"]
  node_settings["Configuration<br/>[config.py]"]
  node_free_tier["Free-Tier Tracking"]
end

node_user(("User"))
node_external{{"External Capabilities"}}

node_user -.->|"submits goal"| node_frontend
node_frontend -.->|"requests tasks"| node_api
node_api -.->|"routes requests"| node_routes
node_routes -.->|"starts task"| node_task
node_task -.->|"checks capabilities"| node_capabilities
node_task -.->|"composes plan"| node_planrecipes
node_task -.->|"applies policy"| node_policy
node_task -.->|"assembles context"| node_context
node_context -->|"packs items"| node_contextbudget
node_context -->|"filters items"| node_contextitems
node_task -.->|"executes plan"| node_modelrouter
node_modelrouter -->|"routes models"| node_gateway
node_gateway -->|"calls completion"| node_completion
node_gateway -.->|"uses budget"| node_tokenbudget
node_task -.->|"verifies proposals"| node_debate
node_task -.->|"governs execution"| node_guard
node_task -.->|"delegates capability"| node_external
node_task -->|"persists tasks"| node_store
node_planrecipes -->|"injects recipes"| node_memory
node_rag -->|"queries models"| node_gateway
node_learning -.->|"detects patterns"| node_hypotheses
node_guard -->|"stores state"| node_redis
node_guard -->|"publishes events"| node_events
node_gateway -->|"loads settings"| node_settings
node_api -.->|"configures service"| node_settings
node_video -->|"analyzes frames"| node_modelrouter
node_gateway -->|"reports status"| node_free_tier

click node_frontend "https://github.com/saifulhaqueniloy/supremeai/tree/main/frontend"
click node_api "https://github.com/saifulhaqueniloy/supremeai/blob/main/backend/main.py"
click node_routes "https://github.com/saifulhaqueniloy/supremeai/blob/main/backend/api/routes/missions.py"
click node_task "https://github.com/saifulhaqueniloy/supremeai/blob/main/backend/adaptive_engine/task_engine.py"
click node_capabilities "https://github.com/saifulhaqueniloy/supremeai/tree/main/backend/adaptive_engine"
click node_planrecipes "https://github.com/saifulhaqueniloy/supremeai/blob/main/tools/pipeline_recipe_compiler.py"
click node_context "https://github.com/saifulhaqueniloy/supremeai/blob/main/backend/context/engine.py"
click node_contextitems "https://github.com/saifulhaqueniloy/supremeai/blob/main/backend/context/items.py"
click node_contextbudget "https://github.com/saifulhaqueniloy/supremeai/blob/main/backend/context/budget.py"
click node_modelrouter "https://github.com/saifulhaqueniloy/supremeai/blob/main/backend/brain/model_router.py"
click node_gateway "https://github.com/saifulhaqueniloy/supremeai/tree/main/backend/core/llm/llm_gateway"
click node_completion "https://github.com/saifulhaqueniloy/supremeai/blob/main/backend/core/llm/llm_gateway/completion.py"
click node_tokenbudget "https://github.com/saifulhaqueniloy/supremeai/blob/main/backend/core/llm/token_budget.py"
click node_debate "https://github.com/saifulhaqueniloy/supremeai/blob/main/backend/engine/debate_engine.py"
click node_policy "https://github.com/saifulhaqueniloy/supremeai/blob/main/backend/external_agents/control/policy_engine.py"
click node_guard "https://github.com/saifulhaqueniloy/supremeai/blob/main/backend/core/autonoguard_engine.py"
click node_learning "https://github.com/saifulhaqueniloy/supremeai/blob/main/backend/evolution/learning_pipeline.py"
click node_hypotheses "https://github.com/saifulhaqueniloy/supremeai/blob/main/backend/learning/hypothesis_engine.py"
click node_rag "https://github.com/saifulhaqueniloy/supremeai/blob/main/backend/memory/rag_pipeline.py"
click node_memory "https://github.com/saifulhaqueniloy/supremeai/blob/main/backend/services/memory_service.py"
click node_store "https://github.com/saifulhaqueniloy/supremeai/blob/main/backend/adaptive_engine/_store.py"
click node_redis "https://github.com/saifulhaqueniloy/supremeai/blob/main/backend/core/cache/redis_manager.py"
click node_events "https://github.com/saifulhaqueniloy/supremeai/blob/main/backend/core/messaging/event_bus.py"
click node_settings "https://github.com/saifulhaqueniloy/supremeai/blob/main/backend/core/config.py"
click node_free_tier "https://github.com/saifulhaqueniloy/supremeai/blob/main/backend/core/llm/free_tier_tracker.py"
click node_video "https://github.com/saifulhaqueniloy/supremeai/blob/main/backend/services/video_to_code_pipeline.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_frontend,node_user toneBlue
class node_task,node_capabilities,node_planrecipes,node_debate,node_video toneAmber
class node_context,node_contextitems,node_contextbudget,node_modelrouter,node_gateway,node_completion,node_tokenbudget,node_rag toneMint
class node_policy,node_guard,node_learning,node_hypotheses toneRose
class node_api,node_routes,node_memory,node_store,node_redis,node_events,node_settings,node_free_tier,node_external toneIndigo
```

## Components

### Task Experience

- [Frontend](https://github.com/saifulhaqueniloy/supremeai/tree/main/frontend): `frontend`

### Planning & Execution

- [Task State Machine](https://github.com/saifulhaqueniloy/supremeai/blob/main/backend/adaptive_engine/task_engine.py): `backend/adaptive_engine/task_engine.py`
- [Capability Surface](https://github.com/saifulhaqueniloy/supremeai/tree/main/backend/adaptive_engine): `backend/adaptive_engine`
- [Pipeline Recipes](https://github.com/saifulhaqueniloy/supremeai/blob/main/tools/pipeline_recipe_compiler.py): `tools/pipeline_recipe_compiler.py`
- [Agent Debate](https://github.com/saifulhaqueniloy/supremeai/blob/main/backend/engine/debate_engine.py): `backend/engine/debate_engine.py`
- [Video-to-Code](https://github.com/saifulhaqueniloy/supremeai/blob/main/backend/services/video_to_code_pipeline.py): `backend/services/video_to_code_pipeline.py`

### Models & Context

- [Context Assembly](https://github.com/saifulhaqueniloy/supremeai/blob/main/backend/context/engine.py): `backend/context/engine.py`
- [Context Items](https://github.com/saifulhaqueniloy/supremeai/blob/main/backend/context/items.py): `backend/context/items.py`
- [Context Budget](https://github.com/saifulhaqueniloy/supremeai/blob/main/backend/context/budget.py): `backend/context/budget.py`
- [Model Router](https://github.com/saifulhaqueniloy/supremeai/blob/main/backend/brain/model_router.py): `backend/brain/model_router.py`
- [LLM Gateway](https://github.com/saifulhaqueniloy/supremeai/tree/main/backend/core/llm/llm_gateway): `backend/core/llm/llm_gateway`
- [Completions](https://github.com/saifulhaqueniloy/supremeai/blob/main/backend/core/llm/llm_gateway/completion.py): `backend/core/llm/llm_gateway/completion.py`
- [Token Budget](https://github.com/saifulhaqueniloy/supremeai/blob/main/backend/core/llm/token_budget.py): `backend/core/llm/token_budget.py`
- [RAG Pipeline](https://github.com/saifulhaqueniloy/supremeai/blob/main/backend/memory/rag_pipeline.py): `backend/memory/rag_pipeline.py`

### Governance & Learning

- [External Policy](https://github.com/saifulhaqueniloy/supremeai/blob/main/backend/external_agents/control/policy_engine.py): `backend/external_agents/control/policy_engine.py`
- [AutonoGuard](https://github.com/saifulhaqueniloy/supremeai/blob/main/backend/core/autonoguard_engine.py): `backend/core/autonoguard_engine.py`
- [Learning Pipeline](https://github.com/saifulhaqueniloy/supremeai/blob/main/backend/evolution/learning_pipeline.py): `backend/evolution/learning_pipeline.py`
- [Hypothesis Learning](https://github.com/saifulhaqueniloy/supremeai/blob/main/backend/learning/hypothesis_engine.py): `backend/learning/hypothesis_engine.py`

### API & State

- [FastAPI](https://github.com/saifulhaqueniloy/supremeai/blob/main/backend/main.py): `backend/main.py`
- [Mission API](https://github.com/saifulhaqueniloy/supremeai/blob/main/backend/api/routes/missions.py): `backend/api/routes/missions.py`
- [Memory Service](https://github.com/saifulhaqueniloy/supremeai/blob/main/backend/services/memory_service.py): `backend/services/memory_service.py`
- [Adaptive Store](https://github.com/saifulhaqueniloy/supremeai/blob/main/backend/adaptive_engine/_store.py): `backend/adaptive_engine/_store.py`
- [Redis Cache](https://github.com/saifulhaqueniloy/supremeai/blob/main/backend/core/cache/redis_manager.py): `backend/core/cache/redis_manager.py`
- [Event Bus](https://github.com/saifulhaqueniloy/supremeai/blob/main/backend/core/messaging/event_bus.py): `backend/core/messaging/event_bus.py`
- [Configuration](https://github.com/saifulhaqueniloy/supremeai/blob/main/backend/core/config.py): `backend/core/config.py`
- [Free-Tier Tracking](https://github.com/saifulhaqueniloy/supremeai/blob/main/backend/core/llm/free_tier_tracker.py): `backend/core/llm/free_tier_tracker.py`

### Other components

- **User**
- **External Capabilities**

## Connections

- User → Frontend: submits goal (evidence: `README.md`)
- Frontend → FastAPI: requests tasks (evidence: `README.md`)
- FastAPI → Mission API: routes requests (evidence: `README.md`)
- Mission API → Task State Machine: starts task (evidence: `README.md`)
- Task State Machine → Capability Surface: checks capabilities (evidence: `README.md`)
- Task State Machine → Pipeline Recipes: composes plan (evidence: `README.md`)
- Task State Machine → External Policy: applies policy (evidence: `README.md`)
- Task State Machine → Context Assembly: assembles context (evidence: `README.md`)
- Context Assembly → Context Budget: packs items (evidence: `backend/context/engine.py`)
- Context Assembly → Context Items: filters items (evidence: `backend/context/engine.py`)
- Task State Machine → Model Router: executes plan (evidence: `README.md`)
- Model Router → LLM Gateway: routes models (evidence: `backend/brain/model_router.py`)
- LLM Gateway → Completions: calls completion (evidence: `backend/core/llm/llm_gateway/__init__.py`)
- LLM Gateway → Token Budget: uses budget
- Task State Machine → Agent Debate: verifies proposals (evidence: `README.md`)
- Task State Machine → AutonoGuard: governs execution (evidence: `README.md`)
- Task State Machine → External Capabilities: delegates capability (evidence: `README.md`)
- Task State Machine → Adaptive Store: persists tasks (evidence: `backend/adaptive_engine/task_engine.py`)
- Pipeline Recipes → Memory Service: injects recipes (evidence: `tools/pipeline_recipe_compiler.py`)
- RAG Pipeline → LLM Gateway: queries models (evidence: `backend/memory/rag_pipeline.py`)
- Learning Pipeline → Hypothesis Learning: detects patterns
- AutonoGuard → Redis Cache: stores state (evidence: `backend/core/autonoguard_engine.py`)
- AutonoGuard → Event Bus: publishes events (evidence: `backend/core/autonoguard_engine.py`)
- LLM Gateway → Configuration: loads settings (evidence: `backend/core/llm/llm_gateway/__init__.py`)
- FastAPI → Configuration: configures service
- Video-to-Code → Model Router: analyzes frames (evidence: `backend/services/video_to_code_pipeline.py`)
- LLM Gateway → Free-Tier Tracking: reports status (evidence: `backend/api/routes/llm_gateway_routes.py`)
