# fuzzinglabs/fuzzforge_ai architecture

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

- Interactive diagram: https://gitdiagram.com/fuzzinglabs/fuzzforge_ai
- Repository: https://github.com/fuzzinglabs/fuzzforge_ai

## Overview

##### Project Type and Purpose
- FuzzForge OSS is an open‐source, AI‐driven security research orchestration runtime.
- It implements a microservice‐style architecture in Python, coordinating containerized security modules via the Model Context Protocol (MCP).

##### File Structure
- Top‐level “services” and libraries:
- fuzzforge-cli – CLI/front-end
- fuzzforge-mcp – MCP server (API layer)
- fuzzforge-runner – Execution engine (business logic)
- fuzzforge-common – Shared abstractions (container engines, storage, queues, workflows)
- fuzzforge-types – Typed schemas for resources, modules, workflows
- fuzzforge-modules & fuzzforge-modules-sdk – Containerized tooling modules and SDK to build them
- Each security module lives under fuzzforge-modules as a Docker/Podman image.

##### README for Architecture Insights
AI Agent → MCP Server → Runner → Container Engine → Modules
- Highlights MCP RPC methods (list_modules, execute_module, start_continuous_module).

##### Main Components & Their Interactions
a. AI Agent (Copilot, Claude, etc.)
- Speaks MCP over STDIO or plugin interface
b. FuzzForge CLI
- Front‐end for human operators and MCP plugin installer
- Forwards commands to the MCP server
c. FuzzForge MCP Server
- Exposes MCP RPC endpoints
- Uses fuzzforge-common and fuzzforge-types
- Delegates execution requests to the Runner
d. FuzzForge Runner
- Core orchestrator & executor
- Uses container‐engine wrappers (Docker/Podman) from fuzzforge-common
- Manages sessions, long‐running continuous fuzzers, result collection
- Stores artifacts via fuzzforge-common’s storage (local FS or S3)
e. Container Engine (Docker / Podman)
- Actually runs each module in isolation
f. Modules (Module A, B, C, …)
- Self‐contained security tools (static analyzers, fuzzers, crash analyzers)
- Built with the Python SDK in fuzzforge-modules-sdk
g. Storage & Queues
- Optional temporal queues for asynchronous job dispatch

##### Architectural Patterns & Design Principles
- Microservice separation: CLI, API server (MCP), executor (Runner), modules as isolated containers
- Plugin/SDK extensibility: fuzzforge-modules-sdk for building new modules
- Typed contracts: MCP payloads described in fuzzforge-types
- Container orchestration abstraction: unified Docker/Podman engines in fuzzforge-common

##### Detail Without Overthinking
- How fuzzforge-common and fuzzforge-types underpin both the MCP server and the Runner.
- Don’t attempt to show every subpackage—focus on the high-level services, shared libraries, execution engine, container infra, and modules.

- Reflects the actual directory‐based microservice decomposition
- Mirrors the README’s architecture section
- Clearly communicates component responsibilities, data flows, and extensibility points
- Serves as a solid blueprint for onboarding new engineers or designing enhancements

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Agent
    AI_AGENT["AI Agent"]:::external

    %% Presentation Layer
    subgraph "Presentation Layer"
        CLI["FuzzForge CLI"]:::service
    end

    %% API Layer
    subgraph "API Layer"
        MCP["MCP Server"]:::service
        COMMON["fuzzforge-common"]:::library
        TYPES["fuzzforge-types"]:::library
    end

    %% Business Logic Layer
    subgraph "Business Logic Layer"
        RUNNER["Runner"]:::service
    end

    %% Shared Libraries
    subgraph "Shared Libraries"
        CE["Container Engines"]:::library
        STORAGE_LIB["Storage"]:::library
        QUEUES["Temporal Queues"]:::library
        WORKFLOWS["Workflows"]:::library
        MODULES_SDK["Modules SDK"]:::library
    end

    %% Container Infrastructure
    subgraph "Container Infrastructure"
        DOCKER["Docker Engine"]:::infra
        PODMAN["Podman Engine"]:::infra
    end

    %% Modules
    subgraph "Security Modules"
        MOD1["cargo-fuzzer"]:::module
        MOD2["crash-analyzer"]:::module
        MOD3["rust-analyzer"]:::module
        MOD4["harness-tester"]:::module
        MOD5["module-template"]:::module
    end

    %% Storage and Queues Infra
    subgraph "Storage & Queues"
        ARTIFACT_STORE["Artifact Store (S3/Local FS)"]:::infra
        QUEUE_INFRA["Temporal Queue Infra"]:::infra
    end

    %% Flows
    AI_AGENT -->|"MCP Plugin / STDIO"| CLI
    CLI -->|"RPC Calls"| MCP
    MCP -->|"delegates"| RUNNER
    RUNNER -->|"uses"| CE
    CE -->|"launch"| MOD1
    CE -->|"launch"| MOD2
    CE -->|"launch"| MOD3
    CE -->|"launch"| MOD4
    CE -->|"launch"| MOD5
    MOD1 -->|"writes artifacts"| ARTIFACT_STORE
    MOD2 -->|"writes artifacts"| ARTIFACT_STORE
    MOD3 -->|"writes artifacts"| ARTIFACT_STORE
    MOD4 -->|"writes artifacts"| ARTIFACT_STORE
    MOD5 -->|"writes artifacts"| ARTIFACT_STORE
    RUNNER -->|"reads results"| STORAGE_LIB
    RUNNER -->|"queues jobs"| QUEUES
    STORAGE_LIB -->|"backend"| ARTIFACT_STORE
    QUEUES -->|"infra"| QUEUE_INFRA

    %% Dependencies on Shared Libraries & Types
    MCP -->|imports| COMMON
    MCP -->|imports| TYPES
    RUNNER -->|imports| COMMON
    RUNNER -->|imports| TYPES
    RUNNER -->|imports| WORKFLOWS
    RUNNER -->|imports| STORAGE_LIB
    RUNNER -->|imports| CE
    COMMON -->|contains| CE
    COMMON -->|contains| STORAGE_LIB
    COMMON -->|contains| QUEUES
    COMMON -->|contains| WORKFLOWS
    MODULES_SDK -->|builds modules| MOD1
    MODULES_SDK -->|builds modules| MOD2
    MODULES_SDK -->|builds modules| MOD3
    MODULES_SDK -->|builds modules| MOD4
    MODULES_SDK -->|builds modules| MOD5

    %% Click Events
    click CLI "https://github.com/fuzzinglabs/fuzzforge_ai/tree/master/fuzzforge-cli/src/fuzzforge_cli"
    click MCP "https://github.com/fuzzinglabs/fuzzforge_ai/tree/master/fuzzforge-mcp/src/fuzzforge_mcp"
    click RUNNER "https://github.com/fuzzinglabs/fuzzforge_ai/tree/master/fuzzforge-runner/src/fuzzforge_runner"
    click COMMON "https://github.com/fuzzinglabs/fuzzforge_ai/tree/master/fuzzforge-common/src/fuzzforge_common"
    click CE "https://github.com/fuzzinglabs/fuzzforge_ai/tree/master/fuzzforge-common/src/fuzzforge_common/sandboxes/engines"
    click STORAGE_LIB "https://github.com/fuzzinglabs/fuzzforge_ai/tree/master/fuzzforge-common/src/fuzzforge_common/storage"
    click QUEUES "https://github.com/fuzzinglabs/fuzzforge_ai/blob/master/fuzzforge-common/src/fuzzforge_common/temporal/queues.py"
    click WORKFLOWS "https://github.com/fuzzinglabs/fuzzforge_ai/tree/master/fuzzforge-common/src/fuzzforge_common/workflows"
    click TYPES "https://github.com/fuzzinglabs/fuzzforge_ai/tree/master/fuzzforge-types/src/fuzzforge_types"
    click MODULES_SDK "https://github.com/fuzzinglabs/fuzzforge_ai/tree/master/fuzzforge-modules/fuzzforge-modules-sdk/src/fuzzforge_modules_sdk"
    click DOCKER "https://github.com/fuzzinglabs/fuzzforge_ai/blob/master/fuzzforge-common/src/fuzzforge_common/sandboxes/engines/docker/engine.py"
    click PODMAN "https://github.com/fuzzinglabs/fuzzforge_ai/blob/master/fuzzforge-common/src/fuzzforge_common/sandboxes/engines/podman/engine.py"
    click ARTIFACT_STORE "https://github.com/fuzzinglabs/fuzzforge_ai/blob/master/fuzzforge-common/src/fuzzforge_common/storage/s3.py"
    click ARTIFACT_STORE "https://github.com/fuzzinglabs/fuzzforge_ai/blob/master/fuzzforge-common/src/fuzzforge_common/storage/configuration.py"
    click MOD1 "https://github.com/fuzzinglabs/fuzzforge_ai/tree/master/fuzzforge-modules/cargo-fuzzer"
    click MOD2 "https://github.com/fuzzinglabs/fuzzforge_ai/tree/master/fuzzforge-modules/crash-analyzer"
    click MOD3 "https://github.com/fuzzinglabs/fuzzforge_ai/tree/master/fuzzforge-modules/rust-analyzer"
    click MOD4 "https://github.com/fuzzinglabs/fuzzforge_ai/tree/master/fuzzforge-modules/harness-tester"
    click MOD5 "https://github.com/fuzzinglabs/fuzzforge_ai/tree/master/fuzzforge-modules/fuzzforge-module-template"
    click MCP_RES1 "https://github.com/fuzzinglabs/fuzzforge_ai/blob/master/fuzzforge-mcp/src/fuzzforge_mcp/resources/modules.py"
    click MCP_RES2 "https://github.com/fuzzinglabs/fuzzforge_ai/blob/master/fuzzforge-mcp/src/fuzzforge_mcp/resources/executions.py"
    click MCP_RES3 "https://github.com/fuzzinglabs/fuzzforge_ai/blob/master/fuzzforge-mcp/src/fuzzforge_mcp/resources/workflows.py"
    click MCP_RES4 "https://github.com/fuzzinglabs/fuzzforge_ai/blob/master/fuzzforge-mcp/src/fuzzforge_mcp/resources/project.py"
    click RUN_CORE1 "https://github.com/fuzzinglabs/fuzzforge_ai/blob/master/fuzzforge-runner/src/fuzzforge_runner/executor.py"
    click RUN_CORE2 "https://github.com/fuzzinglabs/fuzzforge_ai/blob/master/fuzzforge-runner/src/fuzzforge_runner/orchestrator.py"
    click RUN_CORE3 "https://github.com/fuzzinglabs/fuzzforge_ai/blob/master/fuzzforge-runner/src/fuzzforge_runner/runner.py"
    click RUN_CORE4 "https://github.com/fuzzinglabs/fuzzforge_ai/blob/master/fuzzforge-runner/src/fuzzforge_runner/storage.py"

    %% Styles
    classDef service fill:#AED6F1,stroke:#1B4F72,stroke-width:2px
    classDef library fill:#A9DFBF,stroke:#145A32,stroke-width:2px
    classDef module fill:#F5CBA7,stroke:#7E5109,stroke-width:2px
    classDef infra fill:#D5DBDB,stroke:#424949,stroke-width:2px
    classDef external fill:#F0B27A,stroke:#873600,stroke-width:2px
```
