# umairjavaid/flutterswarm architecture

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

- Interactive diagram: https://gitdiagram.com/umairjavaid/flutterswarm
- Repository: https://github.com/umairjavaid/flutterswarm

## Overview

##### Project type and purpose
- FlutterSwarm is a multi-agent orchestration system written in Python that uses LLMs (Anthropic Claude) to generate end-to-end Flutter applications. It’s neither a monolithic app nor a single CLI tool; it’s an AI-driven, agent-based platform with a core orchestrator, multiple specialized agents, shared state management, and integration with external services (LLM APIs, Flutter SDK).

##### File structure
- Top-level components:
- cli.py – command-line entry point
- create_*.py, demo_*.py – example/demo scripts
- agents/ – specialized agent implementations (orchestrator, implementation, testing, security, etc.)
- config/ – YAML configs and config manager for agent settings
- shared/ – shared state and communication primitives
- tools/ – low-level “tool” abstractions (git_tool, file_tool, flutter_tool, etc.) used by agents
- utils/ – high-level utilities (project_manager, task_manager, logging, exception handling)
- monitoring/ – runtime monitoring and logging components
- flutter_projects/ – output directory for generated Flutter apps (git-ignored)
- Patterns:
- Agent-based/microservices style (each Python module in agents/ is a separate actor)
- Shared state repository (shared/state.py) for inter-agent communication
- Tool manager pattern: agents request actions via tools/tool_manager.py
- LangGraph orchestration sits at the core of orchestrator_agent.py

##### README for additional insights
- Confirms 100% LLM-driven code generation, no hardcoded templates
- Describes each agent’s responsibility (architecture, implementation, testing, security, DevOps, documentation, performance)
- Mentions shared state and collaborative decision making via LangGraph
- Points to config/agent_config.yaml, main_config.yaml for orchestration, and .env for API keys
- Workflow: CLI → FlutterSwarm core → orchestrator_agent → agent swarm → tools → Flutter project output

a. Main components
- CLI Layer (cli.py)
- Core Orchestrator (flutter_swarm.py / orchestrator_agent.py + LangGraph)
- Agent Modules (architecture_agent, implementation_agent, testing_agent, etc.)
- Shared State Store (shared/state.py)
- Tool Manager & Tool Plugins (tools/tool_manager.py + individual tools)
- Config Manager (config/config_manager.py + YAML files)
- Monitoring Subsystem (monitoring/…)
- External Services: Anthropic API (LLM), Flutter SDK, Git, Package Manager, etc.
- Output: Generated Flutter Projects (flutter_projects/)

b. Relationships & Interactions
1. User invokes CLI → CLI Layer pulls settings from Config Manager
2. CLI hands control to Core Orchestrator (LangGraph workflow)
3. Core Orchestrator activates specialized agents based on pipeline (architecture → implementation → testing → security → DevOps → documentation → performance)
4. Agents communicate via Shared State Store (publish/subscribe or read/write operations)
5. When an agent needs an external action (e.g., write code files, run flutter commands, git commits, shell commands), it delegates to Tool Manager, which loads & executes the appropriate Tool plugin
6. Agents use LLM API (Anthropic) for text/code generation; responses feed back into Shared State
7. Monitoring subsystem listens to Agent Logger events and updates live progress display
8. Final Flutter app artifacts get written to flutter_projects/ and excluded via .gitignore

c. Architectural patterns & design principles
- Agent-based modularity: Each concern lives in its own agent module
- Orchestration pattern (LangGraph) driving workflow state transitions
- Shared in-memory store with concurrency control for agent coordination
- Plug-in tool architecture enabling easy extension (e.g., adding new tool or agent)
- Configuration-driven behavior (YAML + environment variables)

d. Key technologies, frameworks, libraries
- Python 3.8+
- Anthropic Claude API (LLM interactions)
- LangGraph orchestration engine
- Flutter SDK (dart/flutter CLI)
- PyYAML (config parsing)
- Built-in Python logging, asyncio

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Control Plane
    subgraph "Control Plane"
        CLI["CLI Layer (cli.py)"]:::core
        ConfigManager["Config Manager"]:::core
    end

    %% Core Orchestrator
    subgraph "Core Orchestrator"
        OrchestratorCore["Orchestrator (flutter_swarm.py\nlanggraph_swarm.py)"]:::core
        OrchestratorAgent["Orchestrator Agent"]:::core
    end

    %% Data Plane
    subgraph "Data Plane"
        subgraph "Agents"            
            ArchAgent["Architecture Agent"]:::agent
            ImplAgent["Implementation Agent"]:::agent
            TestAgent["Testing Agent"]:::agent
            E2EAgent["E2E Testing Agent"]:::agent
            QAAgent["Quality Assurance Agent"]:::agent
            SecAgent["Security Agent"]:::agent
            DevOpsAgent["DevOps Agent"]:::agent
            DocAgent["Documentation Agent"]:::agent
            PerfAgent["Performance Agent"]:::agent
            SuperAgent["Supervision Agent"]:::agent
        end
        SharedState["Shared State Store"]:::infra
        ToolManager["Tool Manager"]:::infra
    end

    %% Monitoring
    subgraph "Monitoring Subsystem"
        AgentLogger["Agent Logger"]:::infra
        BuildMonitor["Build Monitor"]:::infra
        LiveDisplay["Live Display"]:::infra
        ProgressTracker["Progress Tracker"]:::infra
    end

    %% External Services
    subgraph "External Services"
        LLMAPI["Anthropic Claude API"]:::external
        FlutterSDK["Flutter SDK"]:::external
        GitService["Git"]:::external
        PackageMgr["Package Manager"]:::external
    end

    %% Output
    Output["Generated Flutter Projects"]:::output

    %% Relationships
    CLI -->|"loads config"| ConfigManager
    CLI -->|"invoke"| OrchestratorCore
    ConfigManager -->|provides settings| OrchestratorCore

    OrchestratorCore -->|activates| OrchestratorAgent
    OrchestratorAgent -->|orchestrates pipeline| ArchAgent
    ArchAgent --> ImplAgent --> TestAgent --> E2EAgent --> QAAgent --> SecAgent --> DevOpsAgent --> DocAgent --> PerfAgent --> SuperAgent

    ArchAgent <-->|"read/write"| SharedState
    ImplAgent <--> SharedState
    TestAgent <--> SharedState
    E2EAgent <--> SharedState
    QAAgent <--> SharedState
    SecAgent <--> SharedState
    DevOpsAgent <--> SharedState
    DocAgent <--> SharedState
    PerfAgent <--> SharedState
    SuperAgent <--> SharedState

    ArchAgent -->|delegates action| ToolManager
    ImplAgent --> ToolManager
    TestAgent --> ToolManager
    E2EAgent --> ToolManager
    QAAgent --> ToolManager
    SecAgent --> ToolManager
    DevOpsAgent --> ToolManager
    DocAgent --> ToolManager
    PerfAgent --> ToolManager
    SuperAgent --> ToolManager

    ToolManager --> LLMAPI
    ToolManager --> FlutterSDK
    ToolManager --> GitService
    ToolManager --> PackageMgr

    ArchAgent -->|logs events| AgentLogger
    ImplAgent --> AgentLogger
    TestAgent --> AgentLogger
    E2EAgent --> AgentLogger
    QAAgent --> AgentLogger
    SecAgent --> AgentLogger
    DevOpsAgent --> AgentLogger
    DocAgent --> AgentLogger
    PerfAgent --> AgentLogger
    SuperAgent --> AgentLogger

    AgentLogger --> BuildMonitor --> LiveDisplay --> ProgressTracker

    SuperAgent -->|writes artifacts| Output

    %% Click Events
    click CLI "https://github.com/umairjavaid/flutterswarm/blob/main/cli.py"
    click ConfigManager "https://github.com/umairjavaid/flutterswarm/blob/main/config/config_manager.py"
    click ConfigManager "https://github.com/umairjavaid/flutterswarm/blob/main/config/agent_config.yaml"
    click ConfigManager "https://github.com/umairjavaid/flutterswarm/blob/main/config/main_config.yaml"
    click OrchestratorCore "https://github.com/umairjavaid/flutterswarm/blob/main/flutter_swarm.py"
    click OrchestratorCore "https://github.com/umairjavaid/flutterswarm/blob/main/langgraph_swarm.py"
    click OrchestratorAgent "https://github.com/umairjavaid/flutterswarm/blob/main/agents/orchestrator_agent.py"
    click ArchAgent "https://github.com/umairjavaid/flutterswarm/blob/main/agents/architecture_agent.py"
    click ImplAgent "https://github.com/umairjavaid/flutterswarm/blob/main/agents/implementation_agent.py"
    click TestAgent "https://github.com/umairjavaid/flutterswarm/blob/main/agents/testing_agent.py"
    click E2EAgent "https://github.com/umairjavaid/flutterswarm/blob/main/agents/e2e_testing_agent.py"
    click QAAgent "https://github.com/umairjavaid/flutterswarm/blob/main/agents/quality_assurance_agent.py"
    click SecAgent "https://github.com/umairjavaid/flutterswarm/blob/main/agents/security_agent.py"
    click DevOpsAgent "https://github.com/umairjavaid/flutterswarm/blob/main/agents/devops_agent.py"
    click DocAgent "https://github.com/umairjavaid/flutterswarm/blob/main/agents/documentation_agent.py"
    click PerfAgent "https://github.com/umairjavaid/flutterswarm/blob/main/agents/performance_agent.py"
    click SuperAgent "https://github.com/umairjavaid/flutterswarm/blob/main/agents/supervision_agent.py"
    click SharedState "https://github.com/umairjavaid/flutterswarm/blob/main/shared/state.py"
    click ToolManager "https://github.com/umairjavaid/flutterswarm/blob/main/tools/tool_manager.py"
    click ToolManager "https://github.com/umairjavaid/flutterswarm/blob/main/tools/base_tool.py"
    click ToolManager "https://github.com/umairjavaid/flutterswarm/blob/main/tools/git_tool.py"
    click ToolManager "https://github.com/umairjavaid/flutterswarm/blob/main/tools/file_tool.py"
    click ToolManager "https://github.com/umairjavaid/flutterswarm/blob/main/tools/flutter_tool.py"
    click ToolManager "https://github.com/umairjavaid/flutterswarm/blob/main/tools/package_manager_tool.py"
    click ToolManager "https://github.com/umairjavaid/flutterswarm/blob/main/tools/code_generation_tool.py"
    click ToolManager "https://github.com/umairjavaid/flutterswarm/blob/main/tools/testing_tool.py"
    click ToolManager "https://github.com/umairjavaid/flutterswarm/blob/main/tools/analysis_tool.py"
    click ToolManager "https://github.com/umairjavaid/flutterswarm/blob/main/tools/security_tool.py"
    click ToolManager "https://github.com/umairjavaid/flutterswarm/blob/main/tools/terminal_tool.py"
    click AgentLogger "https://github.com/umairjavaid/flutterswarm/blob/main/monitoring/agent_logger.py"
    click BuildMonitor "https://github.com/umairjavaid/flutterswarm/blob/main/monitoring/build_monitor.py"
    click LiveDisplay "https://github.com/umairjavaid/flutterswarm/blob/main/monitoring/live_display.py"
    click ProgressTracker "https://github.com/umairjavaid/flutterswarm/blob/main/monitoring/progress_tracker.py"
    click Output "https://github.com/umairjavaid/flutterswarm/tree/main/flutter_projects/"

    %% Styles
    classDef core fill:#cce5ff,stroke:#004085,color:#004085;
    classDef agent fill:#d4edda,stroke:#155724,color:#155724;
    classDef infra fill:#fff3cd,stroke:#856404,color:#856404;
    classDef external fill:#f8d7da,stroke:#721c24,color:#721c24;
    classDef output fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
```
