bzzz/docs/BZZZv2B-SYSTEM_ARCHITECTURE.md

Bzzz System Architecture & Flow

This document contains diagrams to visualize the architecture and data flows of the Bzzz distributed task coordination system.

---

✅ Fixed Component Architecture Diagram

graph TD
    subgraph External_Systems ["External Systems"]
        GitHub[(GitHub Repositories)] -- "Tasks (Issues/PRs)" --> BzzzAgent
        WHOOSHAPI[WHOOSH REST API] -- "Repo Lists & Status Updates" --> BzzzAgent
        N8N([N8N Webhooks])
        Ollama[Ollama API]
    end

    subgraph Bzzz_Agent_Node ["Bzzz Agent Node"]
        BzzzAgent[Bzzz Agent]
        BzzzAgent -- "Manages" --> P2P
        BzzzAgent -- "Uses" --> Integration
        BzzzAgent -- "Uses" --> Executor
        BzzzAgent -- "Uses" --> Logging

        P2P(P2P/PubSub Layer) -- "Discovers Peers" --> Discovery
        P2P -- "Communicates via" --> HMMM

        Integration(GitHub Integration) -- "Polls for Tasks" --> WHOOSHAPI
        Integration -- "Claims Tasks" --> GitHub

        Executor(Task Executor) -- "Runs Commands In" --> Sandbox
        Executor -- "Gets Next Command From" --> Reasoning

        Reasoning(Reasoning Module) -- "Sends Prompts To" --> Ollama

        Sandbox(Docker Sandbox) -->|Isolated| Executor

        Logging(Hypercore Logging) -->|Creates Audit Trail| BzzzAgent

        Discovery(mDNS Discovery)
    end

    BzzzAgent -- "P2P Comms" --> OtherAgent[Other Bzzz Agent]
    OtherAgent -- "P2P Comms" --> BzzzAgent
    Executor -- "Escalates To" --> N8N

    classDef internal fill:#D6EAF8,stroke:#2E86C1,stroke-width:2px;
    class BzzzAgent,P2P,Integration,Executor,Reasoning,Sandbox,Logging,Discovery internal

    classDef external fill:#E8DAEF,stroke:#8E44AD,stroke-width:2px;
    class GitHub,WHOOSHAPI,N8N,Ollama external

---

✅ Fixed Task Execution Flowchart

flowchart TD
    A[Start: Unassigned Task on GitHub] --> B{Bzzz Agent Polls WHOOSH API}
    B --> C{Discovers Active Repositories}
    C --> D{Polls Repos for Suitable Tasks}
    D --> E{Task Found?}
    E -- No --> B
    E -- Yes --> F[Agent Claims Task via GitHub API]
    F --> G[Report Claim to WHOOSH API]
    G --> H[Announce Claim on P2P PubSub]

    H --> I[Create Docker Sandbox]
    I --> J[Clone Repository]
    J --> K{Generate Next Command via Reasoning/Ollama}
    K --> L{Is Task Complete?}
    L -- No --> M[Execute Command in Sandbox]
    M --> N[Feed Output Back to Reasoning]
    N --> K
    L -- Yes --> O[Create Branch & Commit Changes]
    O --> P[Push Branch to GitHub]
    P --> Q[Create Pull Request]
    Q --> R[Report Completion to WHOOSH API]
    R --> S[Announce Completion on PubSub]
    S --> T[Destroy Docker Sandbox]
    T --> Z[End]

    K -- "Needs Help" --> MD1

    %% Meta-Discussion Loop (Separate Cluster)
    subgraph Meta_Discussion ["Meta-Discussion (HMMM)"]
        MD1{Agent Proposes Plan} -->|PubSub| MD2[Other Agents Review]
        MD2 -->|Feedback| MD1
        MD1 -->|Stuck?| MD3{Escalate to N8N}
    end

    H -.-> MD1