# vistaminc/auditluma architecture

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

- Interactive diagram: https://gitdiagram.com/vistaminc/auditluma
- Repository: https://github.com/vistaminc/auditluma

## Overview

##### Project type and purpose
- AuditLuma is a Python-based, AI-driven code-audit system with both a CLI entry point (`main.py`) and an optional Web/API server (`app/api`).
- It orchestrates multiple AI “agents” under a Multi-agent Cooperation Protocol (MCP) and Self-Retrieval-Augmented-Generation (Self-RAG) to analyze codebases for security vulnerabilities, generate remediation advice, and produce interactive visual reports.

##### File structure
- Top-level:
- `main.py` & CLI logic
- `app/api/…` – HTTP server (routes, models, API docs)
- `auditluma/…` – Core engine package:
– `agents/` – orchestrator, code_analyzer, security_analyst, remediation agents
– `mcp/`, `rag/` – inter-agent protocol & retrieval components
– `parsers/`, `models/`, `scanner.py` – code ingestion & AST extraction
– `visualizer/` – graph & report generation
– `utils.py`, `config.py` – shared utilities & configuration
- `config/` – example YAML configs
- `lib/` – front-end assets (Tom-Select, Vis.js) for interactive graph views
- Patterns:
- Modular multi-agent micro-architecture
- Asynchronous/concurrent processing
- Optional vector store (built-in or FAISS) for embeddings

##### Insights from the README
- Components: Agent Orchestrator, Code Analysis Agent, Security Analysis Agent, Remediation Agent, Visualization
- Tech stack: Python 3.8+, asyncio, multiple LLM vendors, optional FAISS
- Outputs: HTML/PDF/JSON reports, interactive dependency graphs

a. **Entry Points**
- CLI (`main.py`)
- Web/API Server (`app/api/server.py`, `routes.py`)
b. **Core Engine**
1. **Scan & Parse**
- `scanner.py` → `parsers/code_parser.py` → code AST & dependency model
2. **Orchestrator**
- `agents/orchestrator.py`
- Coordinates sub-agents via `mcp/protocol.py`
3. **Agents**
- Code Analyzer (`agents/code_analyzer.py`)
- Security Analyst (`agents/security_analyst.py`)
- Remediation (`agents/remediation.py`)
4. **Self-RAG Retrieval**
- `rag/self_rag.py` → embedding store (in-memory or FAISS)
5. **LLM Clients**
- Abstract via `mocks/llm_client.py` or real vendor adapters
c. **Visualization & Reporting**
- Graph Visualizer (`visualizer/graph_visualizer.py`) using Vis.js assets
- Report Generator (`visualizer/report_generator.py`) + HTML templates
d. **Configuration & Data Store**
- Config loader (`config.py`) reads `config/*.yaml`
- Output directory for generated reports

##### Relationships & data flow
- User → CLI/API → Core Engine
- Core Engine: Scan → Parse → Orchestrator → Agents ↔ LLM APIs (Self-RAG embeds)
- Aggregated results → Visualizer → Reports written to disk (or served via API)
- Optional: Front-end assets fetch JSON data endpoints for interactive graphs

##### Architectural patterns & design principles
- Multi-agent coordination (MCP)
- Retrieval-augmented generation (Self-RAG)
- Asynchronous, parallel task execution
- Clear separation of concerns: scanning, analysis, remediation, visualization
- Plugin-style LLM provider support

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Entry Points
    subgraph "Entry Points"
        CLI["CLI: main.py"]:::entry
        API_Server["Web/API Server"]:::entry
        Routes["API Routes"]:::entry
        API_Handlers["API Handlers & Models"]:::entry
    end

    %% Core Engine
    subgraph "Core Engine" 
        Scan["Scanner: scanner.py"]:::core
        Parser["Parser: code_parser.py"]:::core
        Orchestrator["Agent Orchestrator"]:::core
        subgraph "Agents"
            CodeAgent["Code Analysis Agent"]:::core
            SecurityAgent["Security Analysis Agent"]:::core
            RemediationAgent["Remediation Agent"]:::core
        end
        SelfRAG["Self-RAG Retrieval"]:::core
        LLMClient["LLM Client Adapters"]:::external
    end

    %% Visualization & Reporting
    subgraph "Visualization & Reporting"
        GraphVis["Graph Visualizer"]:::output
        ReportGen["Report Generator"]:::output
        Template["HTML Report Template"]:::output
        TemplatesDir["Visualization Templates"]:::output
    end

    %% Config & Data Stores
    subgraph "Configuration & Data"
        ConfigLoader["Configuration Loader"]:::core
        YAMLConfigs["Example Configuration Files"]:::core
        FrontendAssets["Front-end Assets"]:::external
        DataModels["Models & Data Structures"]:::core
        Utils["Utilities"]:::core
    end

    %% External Services
    subgraph "External Services"
        LLMProviders["LLM Providers"]:::external
        FAISS["FAISS Vector Store"]:::external
    end

    %% Connections
    CLI -->|"invoke"| Scan
    API_Server -->|starts| Routes
    Routes -->|calls| API_Handlers
    API_Handlers -->|invoke| Scan

    Scan -->|"code directory"| Parser
    Parser -->|"AST+deps"| Orchestrator

    Orchestrator -->|"MCP message"| CodeAgent
    Orchestrator -->|"MCP message"| SecurityAgent
    Orchestrator -->|"MCP message"| RemediationAgent

    CodeAgent -->|"embedding query"| SelfRAG
    SecurityAgent -->|"embedding query"| SelfRAG
    RemediationAgent -->|"embedding query"| SelfRAG

    SelfRAG -->|"query embeddings"| FAISS
    SelfRAG -->|"in-memory embeddings"| LLMClient

    CodeAgent -->|"LLM request"| LLMClients
    SecurityAgent -->|"LLM request"| LLMClients
    RemediationAgent -->|"LLM request"| LLMClients

    LLMClient -->|calls| LLMProviders

    Orchestrator -->|"results"| GraphVis
    Orchestrator -->|"results"| ReportGen

    GraphVis -->|"render JSON"| FrontendAssets
    ReportGen -->|"generate HTML/PDF"| Template

    API_Handlers -->|"serve JSON"| FrontendAssets

    ConfigLoader -->|reads| YAMLConfigs

    Scan -->|uses| Utils
    Parser -->|uses| DataModels
    Orchestrator -->|uses| ConfigLoader

    %% Click Events
    click CLI "https://github.com/vistaminc/auditluma/blob/master/main.py"
    click API_Server "https://github.com/vistaminc/auditluma/blob/master/app/api/server.py"
    click Routes "https://github.com/vistaminc/auditluma/blob/master/app/api/routes.py"
    click API_Handlers "https://github.com/vistaminc/auditluma/blob/master/app/api/api.py"
    click API_Handlers "https://github.com/vistaminc/auditluma/blob/master/app/api/models.py"
    click API_Handlers "https://github.com/vistaminc/auditluma/blob/master/app/api/utils.py"
    click Scan "https://github.com/vistaminc/auditluma/blob/master/auditluma/scanner.py"
    click Parser "https://github.com/vistaminc/auditluma/blob/master/auditluma/parsers/code_parser.py"
    click Orchestrator "https://github.com/vistaminc/auditluma/blob/master/auditluma/agents/orchestrator.py"
    click CodeAgent "https://github.com/vistaminc/auditluma/blob/master/auditluma/agents/code_analyzer.py"
    click SecurityAgent "https://github.com/vistaminc/auditluma/blob/master/auditluma/agents/security_analyst.py"
    click RemediationAgent "https://github.com/vistaminc/auditluma/blob/master/auditluma/agents/remediation.py"
    click SelfRAG "https://github.com/vistaminc/auditluma/blob/master/auditluma/rag/self_rag.py"
    click LLMClient "https://github.com/vistaminc/auditluma/blob/master/auditluma/mocks/llm_client.py"
    click GraphVis "https://github.com/vistaminc/auditluma/blob/master/auditluma/visualizer/graph_visualizer.py"
    click ReportGen "https://github.com/vistaminc/auditluma/blob/master/auditluma/visualizer/report_generator.py"
    click TemplatesDir "https://github.com/vistaminc/auditluma/blob/master/auditluma/visualizer/templates/report_template.html"
    click Template "https://github.com/vistaminc/auditluma/blob/master/auditluma/templates/report.html"
    click ConfigLoader "https://github.com/vistaminc/auditluma/blob/master/auditluma/config.py"
    click YAMLConfigs "https://github.com/vistaminc/auditluma/blob/master/config/config.yaml.example"
    click YAMLConfigs "https://github.com/vistaminc/auditluma/blob/master/config/api_config.yaml.example"
    click FrontendAssets "https://github.com/vistaminc/auditluma/tree/master/lib/tom-select/"
    click FrontendAssets "https://github.com/vistaminc/auditluma/tree/master/lib/vis-9.1.2/"

    %% Styles
    classDef entry fill:#ccffcc,stroke:#333,stroke-width:1px
    classDef core fill:#CCE5FF,stroke:#333,stroke-width:1px
    classDef external fill:#FFD2A6,stroke:#333,stroke-width:1px
    classDef output fill:#E6CCFF,stroke:#333,stroke-width:1px
```
