# hemanth2607-cyber/superflow architecture

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

- Interactive diagram: https://gitdiagram.com/hemanth2607-cyber/superflow
- Repository: https://github.com/hemanth2607-cyber/superflow

## Overview

SuperFlow is a multi-model agent runtime: a user submits a goal, the workflow/router can organize it into steps, and the agent loop asks a model for tool calls, gates execution through permissions, and returns results. Its major capability branches include computer use, deployment and rollback, SEO, live preview, MCP access, and model training. The graph follows explicit README and source-index relationships; secret-vault implementation files are absent from the supplied tree, so that subsystem is not mapped.

Main entry points: [`agent_engine/tools/registry.py`](https://github.com/hemanth2607-cyber/superflow/blob/main/agent_engine/tools/registry.py) (Tool Registry), [`agent_engine/engine.py`](https://github.com/hemanth2607-cyber/superflow/blob/main/agent_engine/engine.py) (Agent Loop), [`agent_engine/tools/deploy_tools.py`](https://github.com/hemanth2607-cyber/superflow/blob/main/agent_engine/tools/deploy_tools.py) (Deployment Tools), [`agent_engine/tools/seo_tools.py`](https://github.com/hemanth2607-cyber/superflow/blob/main/agent_engine/tools/seo_tools.py) (SEO Tools)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Agent Runtime"]
  node_workflow["Workflow Engine<br/>[workflow.py]"]
  node_router["Task Router<br/>[router.py]"]
  node_engine["Agent Loop<br/>[engine.py]"]
  node_tool_registry["Tool Registry<br/>[registry.py]"]
  node_permissions["Risk Gate<br/>[permissions.py]"]
  node_audit["Audit Log<br/>[audit.py]"]
end

subgraph group_models["Model Routing"]
  node_model_client["Ollama Client<br/>[model_client.py]"]
  node_model_registry["Provider Registry<br/>[registry.py]"]
  node_model_discovery["Model Discovery<br/>[auto_discovery.py]"]
end

subgraph group_tools["Tool Capabilities"]
  node_computer_tools["Computer Tools<br/>[computer_tools.py]"]
  node_computer_actions["Screen and Input<br/>[actions.py]"]
  node_session_recorder["Session Recorder"]
  node_deployment_tools["Deployment Tools<br/>[deploy_tools.py]"]
  node_deploy_spec[("Deploy and History<br/>[spec.py]")]
  node_vercel_adapter["Vercel Adapter<br/>[vercel.py]"]
  node_docker_adapter["Docker Adapter<br/>[docker_deploy.py]"]
  node_seo_tools["SEO Tools<br/>[seo_tools.py]"]
  node_seo_auditor["SEO Auditor<br/>[auditor.py]"]
  node_seo_metadata["Metadata Injector<br/>[meta_injector.py]"]
  node_seo_sitemap["Sitemap Generator"]
  node_preview_tools["Preview Tools<br/>[preview_tools.py]"]
  node_preview_server["Live Preview Server<br/>[live_server.py]"]
end

subgraph group_integrations["External Interfaces"]
  node_mcp["MCP Bridge<br/>[mcp_bridge.py]"]
end

subgraph group_training["Model Training"]
  node_dataset_curator["Dataset Curator<br/>[dataset_curator.py]"]
  node_training_pipeline["Colab Training Pipeline"]
end

node_user(("User"))
node_external_models(("Model Services"))
node_ide(("Claude and Cursor"))
node_colab(("Google Colab"))

node_user -->|"submits goal"| node_workflow
node_workflow -->|"runs steps"| node_engine
node_router -->|"builds workflow"| node_workflow
node_engine -->|"requests response"| node_model_client
node_engine -->|"dispatches calls"| node_tool_registry
node_engine -->|"passes authorization"| node_permissions
node_engine -->|"records events"| node_audit
node_model_client -->|"queries Ollama"| node_external_models
node_workflow -->|"selects providers"| node_model_registry
node_model_discovery -->|"registers providers"| node_model_registry
node_model_registry -.->|"supports hosted models"| node_external_models
node_tool_registry -->|"checks risk"| node_permissions
node_computer_tools -->|"registers tools"| node_tool_registry
node_computer_tools -->|"captures and acts"| node_computer_actions
node_computer_tools -->|"records actions"| node_session_recorder
node_session_recorder -->|"executes actions"| node_computer_actions
node_deployment_tools -->|"registers tools"| node_tool_registry
node_deployment_tools -->|"records deployments"| node_deploy_spec
node_deployment_tools -->|"dispatches deploy"| node_vercel_adapter
node_deployment_tools -->|"dispatches deploy"| node_docker_adapter
node_vercel_adapter -->|"uses spec"| node_deploy_spec
node_docker_adapter -->|"uses spec"| node_deploy_spec
node_seo_tools -->|"registers tools"| node_tool_registry
node_seo_tools -->|"runs audits"| node_seo_auditor
node_seo_tools -->|"injects metadata"| node_seo_metadata
node_seo_tools -->|"generates sitemap"| node_seo_sitemap
node_preview_tools -->|"registers tools"| node_tool_registry
node_preview_tools -->|"starts server"| node_preview_server
node_mcp -->|"exposes tools"| node_tool_registry
node_ide -->|"uses bridge"| node_mcp
node_colab -->|"runs training"| node_training_pipeline
node_user -->|"curates data"| node_dataset_curator
node_user -->|"generates script"| node_training_pipeline

click node_workflow "https://github.com/hemanth2607-cyber/superflow/blob/main/agent_engine/workflow.py"
click node_router "https://github.com/hemanth2607-cyber/superflow/blob/main/agent_engine/orchestrator/router.py"
click node_engine "https://github.com/hemanth2607-cyber/superflow/blob/main/agent_engine/engine.py"
click node_tool_registry "https://github.com/hemanth2607-cyber/superflow/blob/main/agent_engine/tools/registry.py"
click node_permissions "https://github.com/hemanth2607-cyber/superflow/blob/main/agent_engine/permissions.py"
click node_audit "https://github.com/hemanth2607-cyber/superflow/blob/main/agent_engine/audit.py"
click node_model_client "https://github.com/hemanth2607-cyber/superflow/blob/main/agent_engine/model_client.py"
click node_model_registry "https://github.com/hemanth2607-cyber/superflow/blob/main/agent_engine/models/registry.py"
click node_model_discovery "https://github.com/hemanth2607-cyber/superflow/blob/main/agent_engine/models/auto_discovery.py"
click node_computer_tools "https://github.com/hemanth2607-cyber/superflow/blob/main/agent_engine/tools/computer_tools.py"
click node_computer_actions "https://github.com/hemanth2607-cyber/superflow/blob/main/agent_engine/computer_use/actions.py"
click node_session_recorder "https://github.com/hemanth2607-cyber/superflow/blob/main/agent_engine/computer_use/session_recorder.py"
click node_deployment_tools "https://github.com/hemanth2607-cyber/superflow/blob/main/agent_engine/tools/deploy_tools.py"
click node_deploy_spec "https://github.com/hemanth2607-cyber/superflow/blob/main/agent_engine/deployment/spec.py"
click node_vercel_adapter "https://github.com/hemanth2607-cyber/superflow/blob/main/agent_engine/deployment/adapters/vercel.py"
click node_docker_adapter "https://github.com/hemanth2607-cyber/superflow/blob/main/agent_engine/deployment/adapters/docker_deploy.py"
click node_seo_tools "https://github.com/hemanth2607-cyber/superflow/blob/main/agent_engine/tools/seo_tools.py"
click node_seo_auditor "https://github.com/hemanth2607-cyber/superflow/blob/main/agent_engine/seo/auditor.py"
click node_seo_metadata "https://github.com/hemanth2607-cyber/superflow/blob/main/agent_engine/seo/meta_injector.py"
click node_seo_sitemap "https://github.com/hemanth2607-cyber/superflow/blob/main/agent_engine/seo/sitemap_generator.py"
click node_preview_tools "https://github.com/hemanth2607-cyber/superflow/blob/main/agent_engine/tools/preview_tools.py"
click node_preview_server "https://github.com/hemanth2607-cyber/superflow/blob/main/agent_engine/preview/live_server.py"
click node_mcp "https://github.com/hemanth2607-cyber/superflow/blob/main/agent_engine/orchestrator/mcp_bridge.py"
click node_dataset_curator "https://github.com/hemanth2607-cyber/superflow/blob/main/agent_engine/training/dataset_curator.py"
click node_training_pipeline "https://github.com/hemanth2607-cyber/superflow/blob/main/agent_engine/training/colab_train_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_workflow,node_router,node_engine,node_tool_registry,node_permissions,node_audit,node_user toneBlue
class node_model_client,node_model_registry,node_model_discovery toneAmber
class node_computer_tools,node_computer_actions,node_session_recorder,node_deployment_tools,node_deploy_spec,node_vercel_adapter,node_docker_adapter,node_seo_tools,node_seo_auditor,node_seo_metadata,node_seo_sitemap,node_preview_tools,node_preview_server toneMint
class node_mcp toneRose
class node_dataset_curator,node_training_pipeline,node_external_models,node_ide,node_colab toneIndigo
```

## Components

### Agent Runtime

- [Workflow Engine](https://github.com/hemanth2607-cyber/superflow/blob/main/agent_engine/workflow.py): `agent_engine/workflow.py`
- [Task Router](https://github.com/hemanth2607-cyber/superflow/blob/main/agent_engine/orchestrator/router.py): `agent_engine/orchestrator/router.py`
- [Agent Loop](https://github.com/hemanth2607-cyber/superflow/blob/main/agent_engine/engine.py): `agent_engine/engine.py`
- [Tool Registry](https://github.com/hemanth2607-cyber/superflow/blob/main/agent_engine/tools/registry.py): `agent_engine/tools/registry.py`
- [Risk Gate](https://github.com/hemanth2607-cyber/superflow/blob/main/agent_engine/permissions.py): `agent_engine/permissions.py`
- [Audit Log](https://github.com/hemanth2607-cyber/superflow/blob/main/agent_engine/audit.py): `agent_engine/audit.py`

### Model Routing

- [Ollama Client](https://github.com/hemanth2607-cyber/superflow/blob/main/agent_engine/model_client.py): `agent_engine/model_client.py`
- [Provider Registry](https://github.com/hemanth2607-cyber/superflow/blob/main/agent_engine/models/registry.py): `agent_engine/models/registry.py`
- [Model Discovery](https://github.com/hemanth2607-cyber/superflow/blob/main/agent_engine/models/auto_discovery.py): `agent_engine/models/auto_discovery.py`

### Tool Capabilities

- [Computer Tools](https://github.com/hemanth2607-cyber/superflow/blob/main/agent_engine/tools/computer_tools.py): `agent_engine/tools/computer_tools.py`
- [Screen and Input](https://github.com/hemanth2607-cyber/superflow/blob/main/agent_engine/computer_use/actions.py): `agent_engine/computer_use/actions.py`
- [Session Recorder](https://github.com/hemanth2607-cyber/superflow/blob/main/agent_engine/computer_use/session_recorder.py): `agent_engine/computer_use/session_recorder.py`
- [Deployment Tools](https://github.com/hemanth2607-cyber/superflow/blob/main/agent_engine/tools/deploy_tools.py): `agent_engine/tools/deploy_tools.py`
- [Deploy and History](https://github.com/hemanth2607-cyber/superflow/blob/main/agent_engine/deployment/spec.py): `agent_engine/deployment/spec.py`
- [Vercel Adapter](https://github.com/hemanth2607-cyber/superflow/blob/main/agent_engine/deployment/adapters/vercel.py): `agent_engine/deployment/adapters/vercel.py`
- [Docker Adapter](https://github.com/hemanth2607-cyber/superflow/blob/main/agent_engine/deployment/adapters/docker_deploy.py): `agent_engine/deployment/adapters/docker_deploy.py`
- [SEO Tools](https://github.com/hemanth2607-cyber/superflow/blob/main/agent_engine/tools/seo_tools.py): `agent_engine/tools/seo_tools.py`
- [SEO Auditor](https://github.com/hemanth2607-cyber/superflow/blob/main/agent_engine/seo/auditor.py): `agent_engine/seo/auditor.py`
- [Metadata Injector](https://github.com/hemanth2607-cyber/superflow/blob/main/agent_engine/seo/meta_injector.py): `agent_engine/seo/meta_injector.py`
- [Sitemap Generator](https://github.com/hemanth2607-cyber/superflow/blob/main/agent_engine/seo/sitemap_generator.py): `agent_engine/seo/sitemap_generator.py`
- [Preview Tools](https://github.com/hemanth2607-cyber/superflow/blob/main/agent_engine/tools/preview_tools.py): `agent_engine/tools/preview_tools.py`
- [Live Preview Server](https://github.com/hemanth2607-cyber/superflow/blob/main/agent_engine/preview/live_server.py): `agent_engine/preview/live_server.py`

### External Interfaces

- [MCP Bridge](https://github.com/hemanth2607-cyber/superflow/blob/main/agent_engine/orchestrator/mcp_bridge.py): `agent_engine/orchestrator/mcp_bridge.py`

### Model Training

- [Dataset Curator](https://github.com/hemanth2607-cyber/superflow/blob/main/agent_engine/training/dataset_curator.py): `agent_engine/training/dataset_curator.py`
- [Colab Training Pipeline](https://github.com/hemanth2607-cyber/superflow/blob/main/agent_engine/training/colab_train_pipeline.py): `agent_engine/training/colab_train_pipeline.py`

### Other components

- **User**
- **Model Services**
- **Claude and Cursor**
- **Google Colab**

## Connections

- User → Workflow Engine: submits goal
- Workflow Engine → Agent Loop: runs steps (evidence: `agent_engine/workflow.py`)
- Task Router → Workflow Engine: builds workflow (evidence: `agent_engine/orchestrator/router.py`)
- Agent Loop → Ollama Client: requests response (evidence: `agent_engine/engine.py`)
- Agent Loop → Tool Registry: dispatches calls (evidence: `agent_engine/engine.py`)
- Agent Loop → Risk Gate: passes authorization (evidence: `agent_engine/engine.py`)
- Agent Loop → Audit Log: records events (evidence: `agent_engine/engine.py`)
- Ollama Client → Model Services: queries Ollama (evidence: `agent_engine/model_client.py`)
- Workflow Engine → Provider Registry: selects providers (evidence: `agent_engine/workflow.py`)
- Model Discovery → Provider Registry: registers providers (evidence: `agent_engine/models/auto_discovery.py`)
- Provider Registry → Model Services: supports hosted models
- Tool Registry → Risk Gate: checks risk (evidence: `agent_engine/tools/registry.py`)
- Computer Tools → Tool Registry: registers tools (evidence: `agent_engine/tools/computer_tools.py`)
- Computer Tools → Screen and Input: captures and acts (evidence: `agent_engine/tools/computer_tools.py`)
- Computer Tools → Session Recorder: records actions (evidence: `agent_engine/tools/computer_tools.py`)
- Session Recorder → Screen and Input: executes actions (evidence: `agent_engine/computer_use/session_recorder.py`)
- Deployment Tools → Tool Registry: registers tools (evidence: `agent_engine/tools/deploy_tools.py`)
- Deployment Tools → Deploy and History: records deployments (evidence: `agent_engine/tools/deploy_tools.py`)
- Deployment Tools → Vercel Adapter: dispatches deploy (evidence: `agent_engine/tools/deploy_tools.py`)
- Deployment Tools → Docker Adapter: dispatches deploy (evidence: `agent_engine/tools/deploy_tools.py`)
- Vercel Adapter → Deploy and History: uses spec (evidence: `agent_engine/deployment/adapters/vercel.py`)
- Docker Adapter → Deploy and History: uses spec (evidence: `agent_engine/deployment/adapters/docker_deploy.py`)
- SEO Tools → Tool Registry: registers tools (evidence: `agent_engine/tools/seo_tools.py`)
- SEO Tools → SEO Auditor: runs audits (evidence: `agent_engine/tools/seo_tools.py`)
- SEO Tools → Metadata Injector: injects metadata (evidence: `agent_engine/tools/seo_tools.py`)
- SEO Tools → Sitemap Generator: generates sitemap (evidence: `agent_engine/tools/seo_tools.py`)
- Preview Tools → Tool Registry: registers tools (evidence: `agent_engine/tools/preview_tools.py`)
- Preview Tools → Live Preview Server: starts server (evidence: `agent_engine/tools/preview_tools.py`)
- MCP Bridge → Tool Registry: exposes tools (evidence: `agent_engine/orchestrator/mcp_bridge.py`)
- Claude and Cursor → MCP Bridge: uses bridge
- Google Colab → Colab Training Pipeline: runs training
- User → Dataset Curator: curates data
- User → Colab Training Pipeline: generates script
