# repello-ai/agent-wiz architecture

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

- Interactive diagram: https://gitdiagram.com/repello-ai/agent-wiz
- Repository: https://github.com/repello-ai/agent-wiz

## Overview

##### Project Overview & Goals
- Explanation: Agent Wiz is a Python-based CLI tool that (a) parses agentic workflows from code (via AST‐based mappers), (b) visualizes them as interactive D3 graphs, and (c) runs automated threat assessments producing Markdown reports.
- If single, we’ll group all major components in one view.

##### Main Components
- Core CLI (entrypoint in src/repello_agent_wiz/cli.py)
- Framework Parsers (one mapper per supported framework under src/repello_agent_wiz/frameworks/*/mapper.py)
- Graph Model (in memory representation → JSON output under examples/output/)
- Visualizer (src/repello_agent_wiz/visualizers/visualizer.py + src/repello_agent_wiz/templates/index.html + D3 assets)
- Analyzer (src/repello_agent_wiz/analyzers/threat_modelling.py + sys_prompt.txt, maestro.txt)
- File System I/O (reading input code directories + writing JSON, HTML, Markdown)
- External Service: OpenAI API (for optional threat‐assessment NLP calls)
- Prompt: Are there any other external services or subsystems (e.g., custom logging, metrics) you want to include?

##### Relationships & Data Flows
- Extraction Flow:
- CLI “extract” command → invokes selected framework mapper → produces internal graph model → writes graph.json
- Visualization Flow:
- Analysis Flow:
- CLI “analyze” → reads graph.json → passes it to Analyzer → applies MAESTRO rules & (optionally) OpenAI API → outputs threat_report.md

##### Architectural Patterns
- Plugin/Adapter Pattern: one mapper per framework implements a common extraction interface
- Model–View–Controller style within CLI:
- Controller = CLI commands
- Model = Graph internal representation
- View = HTML templates + D3
- Template‐based Code Generation for reports and visual outputs

##### Technologies & Frameworks
- Python 3.x, Click or argparse for CLI
- AST module for static parsing
- Jinja2 or string‐based templates for HTML (index.html under templates)
- D3.js for interactive graph rendering
- Markdown generator for threat reports

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Core CLI
    CLI["Core CLI\n(src/repello_agent_wiz/cli.py)"]:::python

    %% Framework Parsers Subgraph
    subgraph "Framework Parsers (Adapters)" 
        direction TB
        AC["agent_chat mapper"]:::python
        AU["autogen mapper"]:::python
        CR["crewai mapper"]:::python
        GA["google_adk mapper"]:::python
        LG["langgraph mapper"]:::python
        LI["llama_index mapper"]:::python
        N8["n8n mapper"]:::python
        OA["openai_agents mapper"]:::python
        PY["pydantic mapper"]:::python
        SW["swarm mapper"]:::python
    end

    %% Graph Model
    GraphModel["Graph JSON\n(examples/output/*.json)"]:::data

    %% Visualizer Subgraph
    subgraph "Visualizer & Templates"
        direction TB
        VIZ["Visualizer\n(src/repello_agent_wiz/visualizers/visualizer.py)"]:::python
        TPL["index.html\n(src/repello_agent_wiz/templates/index.html)"]:::templates
        ASSETS["D3.js & static assets\n(src/repello_agent_wiz/templates/assets/)"]:::assets
    end

    %% Analyzer Subgraph
    subgraph "Analyzer (Threat Modeling Engine)"
        direction TB
        TH["threat_modelling.py\n(src/repello_agent_wiz/analyzers/threat_modelling.py)"]:::python
        SP["sys_prompt.txt\n(src/repello_agent_wiz/analyzers/sys_prompt.txt)"]:::docs
        MAE["maestro.txt\n(src/repello_agent_wiz/analyzers/maestro.txt)"]:::docs
        OAI["OpenAI API"]:::external
    end

    %% Example Inputs & Outputs
    ExamplesCode["Example Code Inputs\n(examples/code/)"]:::data
    Reports["Markdown Reports\n(examples/report/*.md)"]:::data

    %% Relationships
    CLI -->|"extract"| AC
    CLI -->|"extract"| AU
    CLI -->|"extract"| CR
    CLI -->|"extract"| GA
    CLI -->|"extract"| LG
    CLI -->|"extract"| LI
    CLI -->|"extract"| N8
    CLI -->|"extract"| OA
    CLI -->|"extract"| PY
    CLI -->|"extract"| SW

    AC -->|"graph.json"| GraphModel
    AU -->|"graph.json"| GraphModel
    CR -->|"graph.json"| GraphModel
    GA -->|"graph.json"| GraphModel
    LG -->|"graph.json"| GraphModel
    LI -->|"graph.json"| GraphModel
    N8 -->|"graph.json"| GraphModel
    OA -->|"graph.json"| GraphModel
    PY -->|"graph.json"| GraphModel
    SW -->|"graph.json"| GraphModel

    GraphModel -->|"graph.json"| VIZ
    VIZ -->|"interactive HTML"| TPL
    TPL -->|"assets"| ASSETS

    GraphModel -->|"graph.json"| TH
    TH -->|"use prompts"| SP
    TH -->|"use rules"| MAE
    TH -->|"optional NLP"| OAI
    TH -->|"threat_report.md"| Reports

    ExamplesCode --> CLI

    %% Click Events
    click CLI "https://github.com/repello-ai/agent-wiz/blob/master/src/repello_agent_wiz/cli.py"
    click AC "https://github.com/repello-ai/agent-wiz/blob/master/src/repello_agent_wiz/frameworks/agent_chat/mapper.py"
    click AU "https://github.com/repello-ai/agent-wiz/blob/master/src/repello_agent_wiz/frameworks/autogen/mapper.py"
    click CR "https://github.com/repello-ai/agent-wiz/blob/master/src/repello_agent_wiz/frameworks/crewai/mapper.py"
    click GA "https://github.com/repello-ai/agent-wiz/blob/master/src/repello_agent_wiz/frameworks/google_adk/mapper.py"
    click LG "https://github.com/repello-ai/agent-wiz/blob/master/src/repello_agent_wiz/frameworks/langgraph/mapper.py"
    click LI "https://github.com/repello-ai/agent-wiz/blob/master/src/repello_agent_wiz/frameworks/llama_index/mapper.py"
    click N8 "https://github.com/repello-ai/agent-wiz/blob/master/src/repello_agent_wiz/frameworks/n8n/mapper.py"
    click OA "https://github.com/repello-ai/agent-wiz/blob/master/src/repello_agent_wiz/frameworks/openai_agents/mapper.py"
    click PY "https://github.com/repello-ai/agent-wiz/blob/master/src/repello_agent_wiz/frameworks/pydantic/mapper.py"
    click SW "https://github.com/repello-ai/agent-wiz/blob/master/src/repello_agent_wiz/frameworks/swarm/mapper.py"
    click VIZ "https://github.com/repello-ai/agent-wiz/blob/master/src/repello_agent_wiz/visualizers/visualizer.py"
    click TPL "https://github.com/repello-ai/agent-wiz/blob/master/src/repello_agent_wiz/templates/index.html"
    click ASSETS "https://github.com/repello-ai/agent-wiz/tree/master/src/repello_agent_wiz/templates/assets/"
    click TH "https://github.com/repello-ai/agent-wiz/blob/master/src/repello_agent_wiz/analyzers/threat_modelling.py"
    click SP "https://github.com/repello-ai/agent-wiz/blob/master/src/repello_agent_wiz/analyzers/sys_prompt.txt"
    click MAE "https://github.com/repello-ai/agent-wiz/blob/master/src/repello_agent_wiz/analyzers/maestro.txt"

    %% Styles
    classDef python fill:#E0F7FA,stroke:#006064,color:#006064
    classDef templates fill:#E8F5E9,stroke:#2E7D32,color:#2E7D32
    classDef assets fill:#FFF3E0,stroke:#EF6C00,color:#E65100
    classDef data fill:#ECEFF1,stroke:#607D8B,color:#37474F
    classDef external fill:#FFEBEE,stroke:#C62828,color:#B71C1C
    classDef docs fill:#F3E5F5,stroke:#6A1B9A,color:#4A148C
```
