# miromindai/miroflow architecture

> Architecture diagram of the GitHub repository miromindai/miroflow, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/miromindai/miroflow
- Repository: https://github.com/miromindai/miroflow

## Overview

##### Project type and purpose
- MiroFlow is a modular AI‐agent framework designed to orchestrate complex, multi-tool tasks using large language models (LLMs).
- It provides:
- A core pipeline & orchestrator for multi‐turn conversations and error recovery
- A unified LLM client layer supporting multiple providers
- A tool‐manager that connects to lightweight microservices (“MCP servers”) for external capabilities (code execution, vision, search, audio, etc.)
- A suite of CLI applications for benchmarking, evaluation, and trace visualization
- Config management (Hydra/YAML), logging/tracing, and a simple web UI for visual debugging.

##### File structure
Top‐level directories:
- apps/ — four CLI/web apps:
– eval-agent: run evaluation pipelines programmatically
– prepare-benchmark: download/generate benchmark data
– run-agent: main entrypoint for executing tasks & benchmarks
- libs/miroflow-contrib — optional tracing & contrib modules
- libs/miroflow-tool — tool manager + MCP server implementations (FastMCP microservices)
- libs/miroflow — core framework: pipeline, orchestrator, LLM client, config, logging, utils
- data/ — raw or generated datasets
- docs/ — figures, Dockerfile, contribution docs

Patterns & deployment files:
- justfile, .github/workflows — CI/CD, lint/test automation
- REUSE.toml, LICENSES — licensing compliance
- Each app has a pyproject.toml & uv.lock for reproducible environments

##### Key README insights
- Describes five major stages: intent recognition, planning/orchestration, sub-agent delegation, tool access via MCP, result synthesis
- Enumerates core modules under libs/miroflow and libs/miroflow-tool

## Diagram (Mermaid)

```mermaid
graph TB
  %% Frontend Layer
  subgraph "CLI & Web Interfaces"
    runAgent["run-agent"]:::frontend
    prepareBench["prepare-benchmark"]:::frontend
    evalAgent["eval-agent"]:::frontend
    visualizeTrace["visualize-trace"]:::frontend
  end

  %% Core Framework Layer
  subgraph "Core Framework"
    pipeline["Pipeline"]:::core
    orchestrator["Orchestrator"]:::core
    llmClient["LLM Client"]:::core
    configSystem["Configuration (Hydra)"]:::core
    loggingTracing["Logging & Tracing"]:::core
    utilModules["Utility Modules"]:::core
  end

  %% Microservices Layer
  subgraph "Tool Manager & MCP Microservices"
    toolManager["Tool Manager"]:::micro
    subgraph "MCP Servers"
      audioMCP["Audio MCP Server"]:::micro
      visionMCP["Vision MCP Server"]:::micro
      codeMCP["Code Execution MCP"]:::micro
      browserMCP["Browser Session MCP"]:::micro
      readingMCP["Document Reading MCP"]:::micro
      reasoningMCP["Reasoning MCP"]:::micro
      searchMCP["Search MCP Server"]:::micro
      smartRequest["Smart Request Utils"]:::micro
    end
    toolLogger["Tool Logger"]:::micro
  end

  %% Optional Extensions
  subgraph "Optional Extensions"
    contribUtils["Contrib Utilities"]:::core
    contribTracing["Contrib Tracing"]:::core
  end

  %% External Services & Data
  subgraph "External Services & Data"
    llmAPIs["LLM APIs"]:::external
    sandbox["E2B Sandbox"]:::external
    dataDir(("Data Directory")):::data
    loggingBackend(("Logging Backend")):::external
  end

  %% Connections
  runAgent --> pipeline
  prepareBench --> pipeline
  evalAgent --> pipeline
  pipeline --> orchestrator
  configSystem --> pipeline
  configSystem --> orchestrator
  orchestrator -->|"prompt→response"| llmClient
  llmClient -->|"response"| orchestrator
  orchestrator --> toolManager
  utilModules --> pipeline
  utilModules --> orchestrator
  toolManager --> audioMCP
  toolManager --> visionMCP
  toolManager --> codeMCP
  toolManager --> browserMCP
  toolManager --> readingMCP
  toolManager --> reasoningMCP
  toolManager --> searchMCP
  toolManager --> smartRequest
  audioMCP -->|"calls"| sandbox
  visionMCP -->|"calls"| llmAPIs
  codeMCP -->|"exec in"| sandbox
  browserMCP -->|"HTTP"| sandbox
  readingMCP -->|"requests"| llmAPIs
  reasoningMCP -->|"requests"| llmAPIs
  searchMCP -->|"requests"| llmAPIs
  orchestrator -->|"emit logs/traces"| loggingTracing
  audioMCP --> loggingTracing
  visionMCP --> loggingTracing
  codeMCP --> loggingTracing
  browserMCP --> loggingTracing
  readingMCP --> loggingTracing
  reasoningMCP --> loggingTracing
  searchMCP --> loggingTracing
  smartRequest --> loggingTracing
  loggingTracing --> loggingBackend
  visualizeTrace --> loggingBackend
  contribUtils --> pipeline
  contribTracing --> loggingTracing
  dataDir --> pipeline

  %% Click Events
  click runAgent "https://github.com/miromindai/miroflow/tree/main/apps/run-agent/"
  click prepareBench "https://github.com/miromindai/miroflow/tree/main/apps/prepare-benchmark/"
  click evalAgent "https://github.com/miromindai/miroflow/tree/main/apps/eval-agent/"
  click visualizeTrace "https://github.com/miromindai/miroflow/tree/main/apps/visualize-trace/"
  click pipeline "https://github.com/miromindai/miroflow/blob/main/libs/miroflow/src/miroflow/prebuilt/pipeline.py"
  click orchestrator "https://github.com/miromindai/miroflow/blob/main/libs/miroflow/src/miroflow/prebuilt/orchestrator.py"
  click llmClient "https://github.com/miromindai/miroflow/blob/main/libs/miroflow/src/miroflow/llm/client.py"
  click configSystem "https://github.com/miromindai/miroflow/blob/main/libs/miroflow/src/miroflow/prebuilt/config/agent/_default.yaml"
  click loggingTracing "https://github.com/miromindai/miroflow/blob/main/libs/miroflow/src/miroflow/logging/logger.py"
  click toolManager "https://github.com/miromindai/miroflow/blob/main/libs/miroflow-tool/src/miroflow/tool/manager.py"
  click audioMCP "https://github.com/miromindai/miroflow/blob/main/libs/miroflow-tool/src/miroflow/tool/mcp_servers/audio_mcp_server.py"
  click visionMCP "https://github.com/miromindai/miroflow/blob/main/libs/miroflow-tool/src/miroflow/tool/mcp_servers/vision_mcp_server.py"
  click codeMCP "https://github.com/miromindai/miroflow/blob/main/libs/miroflow-tool/src/miroflow/tool/mcp_servers/python_server.py"
  click browserMCP "https://github.com/miromindai/miroflow/blob/main/libs/miroflow-tool/src/miroflow/tool/mcp_servers/browser_session.py"
  click readingMCP "https://github.com/miromindai/miroflow/blob/main/libs/miroflow-tool/src/miroflow/tool/mcp_servers/reading_mcp_server.py"
  click reasoningMCP "https://github.com/miromindai/miroflow/blob/main/libs/miroflow-tool/src/miroflow/tool/mcp_servers/reasoning_mcp_server.py"
  click searchMCP "https://github.com/miromindai/miroflow/blob/main/libs/miroflow-tool/src/miroflow/tool/mcp_servers/searching_mcp_server.py"
  click smartRequest "https://github.com/miromindai/miroflow/blob/main/libs/miroflow-tool/src/miroflow/tool/mcp_servers/utils/smart_request.py"
  click toolLogger "https://github.com/miromindai/miroflow/blob/main/libs/miroflow-tool/src/miroflow/tool/logger.py"
  click contribUtils "https://github.com/miromindai/miroflow/tree/main/libs/miroflow-contrib/src/miroflow/contrib/pocket/"
  click contribTracing "https://github.com/miromindai/miroflow/tree/main/libs/miroflow-contrib/src/miroflow/contrib/tracing/"
  click dataDir "https://github.com/miromindai/miroflow/tree/main/data/"

  %% Styles
  classDef frontend fill:#DDA0DD,stroke:#333,stroke-width:1px
  classDef core fill:#ADD8E6,stroke:#333,stroke-width:1px
  classDef micro fill:#90EE90,stroke:#333,stroke-width:1px
  classDef external fill:#FFA500,stroke:#333,stroke-width:1px
  classDef data fill:#F5DEB3,stroke:#333,stroke-width:1px
```
