# gruizv/agenticcollaborationsystem architecture

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

- Interactive diagram: https://gitdiagram.com/gruizv/agenticcollaborationsystem
- Repository: https://github.com/gruizv/agenticcollaborationsystem

## Overview

##### Project Type and Purpose
- This is an “agentic collaboration” framework rather than a traditional web app or microservice.
- It provides a file-based memory layer for multiple Roo agents (Orchestrator, Architect, Code, Debug, Ask) to coordinate over a shared filesystem.
- The pj_directory holds the actual user project code and tests; roo_state is the append-only state store; SOPFs holds the prompt footers per mode.

##### Main Components
a. External User
b. Agents
- Orchestrator
- Architect
- Code
- Debug
- Ask
c. Shared Memory Layer
- roo_state/project_state.md (central “database”)
- roo_state/.roo-config.yaml (mode metadata)
- roo_state/[Mode]/mode_log.md (per-agent logs)
d. Project Source & Tests
- pj_directory/src/
- pj_directory/tests/tests_log.md
e. SOPF Directory
- SOPFs/[Mode] SOPF.md

##### Relationships & Data Flows
- User → Orchestrator: initial prompt, project goals.
- Agents → Orchestrator: “Work Complete” callbacks.
- All Agents ↔ Shared Memory:
- Read project_state.md then their own mode_log.md (Bootstrapping).
- Write to their mode_log.md + append orchestrator summary to project_state.md (Execution).
- Code & Debug additionally append to tests_log.md when tests are created/fixed.
- Ask mode: occasionally reads from and writes to project_state.md; provides explanations to User and Orchestrator.

##### Architectural Patterns & Principles
- “File-based event sourcing”: append-only logs for auditability.
- “Single source of truth”: project_state.md as central document.
- “Role separation”: each agent has isolated local memory but shared coordination via Orchestrator.
- “Bootstrap–Reconcile–Execute” cycle per agent.

##### Technologies & Artifacts
- Markdown/YAML files as “storage” nodes.
- .roo-config.yaml as a small config “service.”
- pj_directory as standard code/test folder.
- SOPFs as prompt templates (show them as static assets).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External User
    User["External User"]:::external

    %% Orchestrator & Agents
    Orchestrator["Orchestrator Agent"]:::agent
    Architect["Architect Agent"]:::agent
    CodeAgent["Code Agent"]:::agent
    DebugAgent["Debug Agent"]:::agent
    AskAgent["Ask Agent"]:::agent

    %% Shared Memory Layer
    subgraph "Shared Memory (roo_state/)" 
        direction TB
        PS["project_state.md"]:::memory
        Config[".roo-config.yaml"]:::memory
        subgraph "Mode Logs"
            direction TB
            OrchLog["Orchestrator/mode_log.md"]:::memory
            ArchLog["Architect/mode_log.md"]:::memory
            CodeLog["Code/mode_log.md"]:::memory
            DebugLog["Debug/mode_log.md"]:::memory
        end
    end

    %% Project Source & Tests
    subgraph "pj_directory" 
        direction TB
        Src["src/"]:::code
        TestsLog["tests/tests_log.md"]:::code
    end

    %% SOPF Assets
    subgraph "SOPFs" 
        direction TB
        OrSOPF["Orchestrator SOPF.md"]:::sopf
        ArSOPF["Architect SOPF.md"]:::sopf
        CoSOPF["Code SOPF.md"]:::sopf
        DeSOPF["Debug SOPF.md"]:::sopf
        AsSOPF["Ask SOPF.md"]:::sopf
    end

    %% User to Orchestrator
    User -->|"Initial Prompt / Goals"| Orchestrator

    %% Task Assignment
    Orchestrator -->|"Assign Task"| Architect
    Orchestrator -->|"Assign Task"| CodeAgent
    Orchestrator -->|"Assign Task"| DebugAgent
    Orchestrator -->|"Assign Task"| AskAgent

    %% Work Complete callbacks
    Architect -->|"Work Complete"| Orchestrator
    CodeAgent -->|"Work Complete"| Orchestrator
    DebugAgent -->|"Work Complete"| Orchestrator
    AskAgent -->|"Work Complete"| Orchestrator

    %% Agents ↔ Shared Memory
    Architect -->|"Read/Write"| PS
    Architect -->|"Append"| ArchLog
    CodeAgent -->|"Read/Write"| PS
    CodeAgent -->|"Append"| CodeLog
    DebugAgent -->|"Read/Write"| PS
    DebugAgent -->|"Append"| DebugLog
    AskAgent -->|"Read/Write"| PS

    %% Config metadata access
    Orchestrator -->|"Read"| Config
    Architect -->|"Read"| Config
    CodeAgent -->|"Read"| Config
    DebugAgent -->|"Read"| Config
    AskAgent -->|"Read"| Config

    %% Code & Debug to Tests Log
    CodeAgent -->|"Append Tests"| TestsLog
    DebugAgent -->|"Append Tests"| TestsLog

    %% Agents → SOPF templates
    Orchestrator -->|"Use Template"| OrSOPF
    Architect -->|"Use Template"| ArSOPF
    CodeAgent -->|"Use Template"| CoSOPF
    DebugAgent -->|"Use Template"| DeSOPF
    AskAgent -->|"Use Template"| AsSOPF

    %% Agents ↔ pj_directory
    CodeAgent -->|"Read/Write Code"| Src
    DebugAgent -->|"Read/Write Code"| Src

    %% Ask Agent to User
    AskAgent -->|"Explanations"| User

    %% Click Events
    click OrchLog "https://github.com/gruizv/agenticcollaborationsystem/blob/main/project_root/roo_state/Orchestrator/mode_log.md"
    click ArchLog "https://github.com/gruizv/agenticcollaborationsystem/blob/main/project_root/roo_state/Architect/mode_log.md"
    click CodeLog "https://github.com/gruizv/agenticcollaborationsystem/blob/main/project_root/roo_state/Code/mode_log.md"
    click DebugLog "https://github.com/gruizv/agenticcollaborationsystem/blob/main/project_root/roo_state/Debug/mode_log.md"
    click PS "https://github.com/gruizv/agenticcollaborationsystem/blob/main/project_root/roo_state/project_state.md"
    click Config "https://github.com/gruizv/agenticcollaborationsystem/blob/main/project_root/roo_state/.roo-config.yaml"
    click OrSOPF "https://github.com/gruizv/agenticcollaborationsystem/blob/main/project_root/SOPF/Orchestrator SOPF.md"
    click ArSOPF "https://github.com/gruizv/agenticcollaborationsystem/blob/main/project_root/SOPF/Architect SOPF.md"
    click CoSOPF "https://github.com/gruizv/agenticcollaborationsystem/blob/main/project_root/SOPF/Code SOPF.md"
    click DeSOPF "https://github.com/gruizv/agenticcollaborationsystem/blob/main/project_root/SOPF/Debug SOPF.md"
    click AsSOPF "https://github.com/gruizv/agenticcollaborationsystem/blob/main/project_root/SOPF/Ask SOPF.md"
    click Src "https://github.com/gruizv/agenticcollaborationsystem/tree/main/project_root/pj_directory"
    click TestsLog "https://github.com/gruizv/agenticcollaborationsystem/blob/main/project_root/pj_directory/tests/test_log.md"

    %% Styles
    classDef agent fill:#D0E8FF,stroke:#333,stroke-width:1px
    classDef memory fill:#D4F4DD,stroke:#333,stroke-width:1px
    classDef code fill:#FFE0B2,stroke:#333,stroke-width:1px
    classDef sopf fill:#E0E0E0,stroke:#333,stroke-width:1px
    classDef external fill:#F0F0F0,stroke:#333,stroke-width:1px
```
