# mgonzalezbaile/rag-incident-cve-analysis architecture

> Architecture diagram of the GitHub repository mgonzalezbaile/rag-incident-cve-analysis, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mgonzalezbaile/rag-incident-cve-analysis
- Repository: https://github.com/mgonzalezbaile/rag-incident-cve-analysis

## Overview

##### Project type and purpose
- This is a backend­-only, agentic system for automated CVE (Common Vulnerabilities and Exposures) analysis and prioritization. It exposes an API, runs as a service (via Docker/Docker-Compose), and orchestrates a multi-stage reasoning workflow (agentic GraphRAG) over a Neo4j knowledge graph, LLMs, and other tools.

##### File structure
- Top level
- docker-compose.yml, Dockerfile & .dockerignore under cve-analysis – define two main containers (the agent service and Neo4j)
- INSTALL_AND_USAGE.md, Makefile – build & run instructions
- cve-analysis/src/cve_analysis/
- domain/ – core business logic:
– graphs/ (analyze_incident_graph + two nested sub-graphs for retrieval & prioritization)
– prompts/ (BAML template files for LLM interactions)
– tools/ (CybersecurityDatabaseTool, WebSearchTool, ToolFactory)
- infrastructure/ – adapters & entry points:
– api.py & api_middlewares.py (HTTP interface)
– db/neo4j_db.py (Neo4j driver adapter)
– bootstrap.py (dependency injection with Punq, config loading)
- data/ – scripts to generate and index CVE embeddings (offline prep for hybrid semantic search)
- Notebook folder – exploratory work

##### README for additional insights
- Clean/Hexagonal Architecture (Ports & Adapters): domain logic isolated from infra
- LangGraph: orchestrates the multi-stage reasoning workflow as a state machine
- BAML: abstracts LLM provider details (retry, fallback)
- Opik: observability & traceability for LLM calls
- OpenRouter: LLM selection & routing
- Punq: lightweight dependency injection

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Agent Service Container
    subgraph "Agent Service Container"
        direction TB

        %% Domain Layer
        subgraph "Domain Core" 
            direction TB
            Orchestrator["LangGraph Orchestrator"]:::domain
            subgraph "Analyze Incident Graph"
                direction TB
                Context["Understand Incident Context"]:::domain
                Identify["Identify Relevant CVEs"]:::domain
                Prioritize["Prioritize CVEs"]:::domain
                ReportGen["Generate Analysis Report"]:::domain
            end
            StateFiles["State & Node Definitions"]:::domain
        end

        %% Prompts (BAML)
        Prompts["Prompt Templates (BAML)"]:::prompts

        %% Tools Layer
        subgraph "Tools Layer"
            direction TB
            ToolIface["Domain Tool Interface"]:::tool
            ToolFactory["ToolFactory"]:::tool
            CyberDB["CybersecurityDatabaseTool"]:::tool
            WebSearch["WebSearchTool"]:::tool
        end

        %% Infrastructure Adapters
        subgraph "Infrastructure"
            direction TB
            API["HTTP API Adapter"]:::infra
            Mid["API Middlewares"]:::infra
            Bootstrap["Dependency Injection & Bootstrap"]:::infra
            Config["Configuration"]:::infra
            Neo4jAdapter["Neo4j Driver Adapter"]:::infra
            Opik["Observability (Opik)"]:::infra
        end
    end

    %% Neo4j Container
    subgraph "Neo4j Database Container"
        direction TB
        Neo4jDB["Neo4j Knowledge Graph"]:::db
    end

    %% External Services
    subgraph "External Services"
        direction TB
        LLM["LLM Providers (via OpenRouter)"]:::external
        WebAPI["Web Search Endpoint"]:::external
    end

    %% Data Flows
    API -->|"API Call"| Orchestrator
    Orchestrator -->|"run Understand"| Context
    Context -->|"uses prompts"| Prompts
    Context -->|"calls LLM"| LLM
    Orchestrator -->|"run Identify"| Identify
    Identify -->|"Reason/Act/Observe"| Identify
    Identify -->|"calls ToolFactory"| ToolFactory
    ToolFactory -->|"instantiates"| CyberDB
    ToolFactory -->|"instantiates"| WebSearch
    CyberDB -->|"query"| Neo4jDB
    WebSearch -->|"request"| WebAPI
    Orchestrator -->|"run Prioritize"| Prioritize
    Prioritize -->|"Reason/Act/Observe"| Prioritize
    Prioritize -->|"calls ToolFactory"| ToolFactory
    Orchestrator -->|"run ReportGen"| ReportGen
    ReportGen -->|"uses prompts"| Prompts
    ReportGen -->|"calls LLM"| LLM

    %% Observability Hooks
    Opik -.->|wraps LLM calls| LLM
    Opik -.->|wraps tool exec| ToolFactory

    %% Adapters to Core
    Bootstrap -->|injects deps| Orchestrator
    Config -->|provides config| Bootstrap
    Neo4jAdapter -->|adapter for| Neo4jDB

    %% Click Events
    click Orchestrator "https://github.com/mgonzalezbaile/rag-incident-cve-analysis/blob/main/cve-analysis/src/cve_analysis/domain/graphs/analyze_incident_graph/analyze_incident_graph.py"
    click Context "https://github.com/mgonzalezbaile/rag-incident-cve-analysis/blob/main/cve-analysis/src/cve_analysis/domain/graphs/analyze_incident_graph/retrieve_relevant_cves_graph/retrieve_relevant_cves_graph.py"
    click Identify "https://github.com/mgonzalezbaile/rag-incident-cve-analysis/tree/main/cve-analysis/src/cve_analysis/domain/graphs/analyze_incident_graph/retrieve_relevant_cves_graph"
    click Prioritize "https://github.com/mgonzalezbaile/rag-incident-cve-analysis/blob/main/cve-analysis/src/cve_analysis/domain/graphs/analyze_incident_graph/prioritize_cves_graph/prioritize_cves_graph.py"
    click StateFiles "https://github.com/mgonzalezbaile/rag-incident-cve-analysis/blob/main/cve-analysis/src/cve_analysis/domain/graphs/analyze_incident_graph/analyze_incident_state.py"
    click StateFiles "https://github.com/mgonzalezbaile/rag-incident-cve-analysis/blob/main/cve-analysis/src/cve_analysis/domain/graphs/analyze_incident_graph/analyze_incident_nodes.py"
    click StateFiles "https://github.com/mgonzalezbaile/rag-incident-cve-analysis/blob/main/cve-analysis/src/cve_analysis/domain/graphs/analyze_incident_graph/retrieve_relevant_cves_graph/retrieve_relevant_cves_state.py"
    click StateFiles "https://github.com/mgonzalezbaile/rag-incident-cve-analysis/blob/main/cve-analysis/src/cve_analysis/domain/graphs/analyze_incident_graph/retrieve_relevant_cves_graph/retrieve_relevant_cves_nodes.py"
    click StateFiles "https://github.com/mgonzalezbaile/rag-incident-cve-analysis/blob/main/cve-analysis/src/cve_analysis/domain/graphs/analyze_incident_graph/prioritize_cves_graph/prioritize_cves_state.py"
    click StateFiles "https://github.com/mgonzalezbaile/rag-incident-cve-analysis/blob/main/cve-analysis/src/cve_analysis/domain/graphs/analyze_incident_graph/prioritize_cves_graph/prioritize_cves_nodes.py"
    click ReportGen "https://github.com/mgonzalezbaile/rag-incident-cve-analysis/blob/main/cve-analysis/src/cve_analysis/domain/graphs/analyze_incident_graph/markdown_generator.py"
    click Prompts "https://github.com/mgonzalezbaile/rag-incident-cve-analysis/tree/main/cve-analysis/src/cve_analysis/domain/prompts/baml_src/"
    click CyberDB "https://github.com/mgonzalezbaile/rag-incident-cve-analysis/blob/main/cve-analysis/src/cve_analysis/domain/tools/cybersecurity_database_tool.py"
    click WebSearch "https://github.com/mgonzalezbaile/rag-incident-cve-analysis/blob/main/cve-analysis/src/cve_analysis/domain/tools/web_search_tool.py"
    click ToolFactory "https://github.com/mgonzalezbaile/rag-incident-cve-analysis/blob/main/cve-analysis/src/cve_analysis/domain/tools/tool_factory.py"
    click ToolIface "https://github.com/mgonzalezbaile/rag-incident-cve-analysis/blob/main/cve-analysis/src/cve_analysis/domain/tools/tool.py"
    click API "https://github.com/mgonzalezbaile/rag-incident-cve-analysis/blob/main/cve-analysis/src/cve_analysis/infrastructure/api.py"
    click Mid "https://github.com/mgonzalezbaile/rag-incident-cve-analysis/blob/main/cve-analysis/src/cve_analysis/infrastructure/api_middlewares.py"
    click Bootstrap "https://github.com/mgonzalezbaile/rag-incident-cve-analysis/blob/main/cve-analysis/src/cve_analysis/infrastructure/bootstrap.py"
    click Config "https://github.com/mgonzalezbaile/rag-incident-cve-analysis/blob/main/cve-analysis/src/cve_analysis/config.py"
    click Neo4jAdapter "https://github.com/mgonzalezbaile/rag-incident-cve-analysis/blob/main/cve-analysis/src/cve_analysis/infrastructure/db/neo4j_db.py"
    click Opik "https://github.com/mgonzalezbaile/rag-incident-cve-analysis/blob/main/cve-analysis/src/cve_analysis/infrastructure/opik_utils.py"
    click docker-compose.yml "https://github.com/mgonzalezbaile/rag-incident-cve-analysis/blob/main/docker-compose.yml"
    click Dockerfile "https://github.com/mgonzalezbaile/rag-incident-cve-analysis/tree/main/cve-analysis/Dockerfile"
    click CreateIndex "https://github.com/mgonzalezbaile/rag-incident-cve-analysis/blob/main/cve-analysis/data/create_cve_embeddings_index.py"
    click EmbedDesc "https://github.com/mgonzalezbaile/rag-incident-cve-analysis/blob/main/cve-analysis/data/embed_cve_descriptions.py"

    %% Styles
    classDef domain fill:#D5E8D4,stroke:#82B366
    classDef infra fill:#F8CECC,stroke:#B85450
    classDef tool fill:#FFF2CC,stroke:#D6B656
    classDef external fill:#DAE8FC,stroke:#6C8EBF
    classDef db fill:#E1D5E7,stroke:#9673A6
    classDef prompts fill:#F5F5F5,stroke:#999999
```
