# deadbits/vigil-llm architecture

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

- Interactive diagram: https://gitdiagram.com/deadbits/vigil-llm
- Repository: https://github.com/deadbits/vigil-llm

## Overview

##### Main Components
- API Server: Represent the REST API layer (e.g., the entry point in vigil-server.py) that receives and handles incoming HTTP requests for analysis.
- Core Engine (Library): Include the main Vigil core (the vigil/vigil.py and related modules) responsible for orchestrating analyses. This component instantiates and coordinates all scanners.
- Configuration Layer: Include a component for configuration (conf folder, such as server.conf and docker.conf) that feeds settings into both the core engine and scanners.
- External Dependencies & Integration Points: Optionally include external services such as vector database services for embeddings, open-source libraries (like SentenceTransformers for embeddings, OpenAI API, YARA installation), and even the optional Streamlit-based web UI interface (streamlit_app.py).

##### Relationships and Interactions
- The API Server receives incoming requests (e.g., /analyze/prompt, /analyze/response, /canary/add, /canary/check) and routes them to the Vigil core.
- Each scanner interacts with underlying data/signature files (from the data folder) and may access external libraries or resources for computing embeddings or performing pattern matching.
- Configuration flow: the conf files (e.g., conf/server.conf) are read at startup by the API server and core engine to determine settings for scanners, model selections, and database connections.

##### Architectural Patterns and Principles
- A modular and extensible architecture where each scanner module is developed independently (as seen in the vigil/scanners directory).
- Separation of concerns (API handling, core orchestration, detection modules, data loading/configuration).
- That the design supports both library usage (for integration in other Python apps) and standalone REST API serving.
- Optionally, mention the layered security pattern: multiple detection approaches (heuristics, embeddings, token-based) to defend against prompt injection vulnerabilities.

##### Relevant Technologies, Frameworks, or Libraries
- Python as the main programming language.
- YARA (for heuristics scanning).
- Machine learning libraries or pre-trained transformer models for text similarity/injection detection.
- Vector database or embedding generation tools (e.g., sentence-transformers) for similarity-based detection.
- REST API frameworks (evident from the Python server script, though it may be lightweight and custom built).
- Docker for containerization (supported by both Dockerfile and the conf/docker.conf file).
- Streamlit for the optional web UI (streamlit_app.py).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% REST API Layer
    subgraph "REST API Layer"
        API_Server["REST API Server"]:::api
    end

    %% Core Processing Layer
    subgraph "Core Processing Layer"
        CORE["Core Engine"]:::core
    end

    %% Detection Modules
    subgraph "Detection Modules"
        SC_YARA["YARA Scanner"]:::scanner
        SC_Similarity["Similarity Scanner"]:::scanner
        SC_Transformer["Transformer Scanner"]:::scanner
        SC_Sentiment["Sentiment Scanner"]:::scanner
        SC_Relevance["Relevance Scanner"]:::scanner
        SC_VectorDB["VectorDB Scanner"]:::scanner
    end

    %% Data Layer
    subgraph "Data Layer"
        Datasets["Datasets"]:::data
        VDB["VDB Data"]:::data
        YARA_Data["YARA Signatures"]:::data
        Prompts["Prompts Data"]:::data
        Regex["Regex Patterns"]:::data
        LOADER["Loader Utility"]:::data
    end

    %% Configuration
    subgraph "Configuration"
        ServerConf["Server Config"]:::config
        DockerConf["Docker Config"]:::config
    end

    %% External Interfaces
    subgraph "External Interfaces"
        UI["Streamlit Web UI"]:::external
    end

    %% Connections: API and Core
    API_Server -->|"receives_request"| CORE
    UI -->|"sends_req"| API_Server

    %% Configuration flow
    API_Server -->|"reads_config"| ServerConf
    API_Server -->|"reads_config"| DockerConf
    CORE -->|"reads_config"| ServerConf
    CORE -->|"reads_config"| DockerConf

    %% Core to Detection Modules
    CORE -->|"invokes"| SC_YARA
    CORE -->|"invokes"| SC_Similarity
    CORE -->|"invokes"| SC_Transformer
    CORE -->|"invokes"| SC_Sentiment
    CORE -->|"invokes"| SC_Relevance
    CORE -->|"invokes"| SC_VectorDB

    %% Detection Modules accessing Data
    SC_YARA -->|"accesses"| YARA_Data
    SC_Similarity -->|"accesses"| Datasets
    SC_Transformer -->|"accesses"| Datasets
    SC_Sentiment -->|"accesses"| Datasets
    SC_Relevance -->|"accesses"| Datasets
    SC_VectorDB -->|"accesses"| VDB

    %% Core Engine loading data
    CORE -->|"loads_data_from"| Datasets
    CORE -->|"loads_data_from"| VDB
    CORE -->|"loads_data_from"| YARA_Data
    CORE -->|"loads_data_from"| Prompts
    CORE -->|"loads_data_from"| Regex

    %% Loader populates Data Layer
    LOADER -->|"populates"| Datasets
    LOADER -->|"populates"| VDB
    LOADER -->|"populates"| YARA_Data
    LOADER -->|"populates"| Prompts
    LOADER -->|"populates"| Regex

    %% Click Events
    click API_Server "https://github.com/deadbits/vigil-llm/blob/main/vigil-server.py"
    click CORE "https://github.com/deadbits/vigil-llm/blob/main/vigil/vigil.py"
    click SC_YARA "https://github.com/deadbits/vigil-llm/blob/main/vigil/scanners/yara.py"
    click SC_Similarity "https://github.com/deadbits/vigil-llm/blob/main/vigil/scanners/similarity.py"
    click SC_Transformer "https://github.com/deadbits/vigil-llm/blob/main/vigil/scanners/transformer.py"
    click SC_Sentiment "https://github.com/deadbits/vigil-llm/blob/main/vigil/scanners/sentiment.py"
    click SC_Relevance "https://github.com/deadbits/vigil-llm/blob/main/vigil/scanners/relevance.py"
    click SC_VectorDB "https://github.com/deadbits/vigil-llm/blob/main/vigil/scanners/vectordb.py"
    click Datasets "https://github.com/deadbits/vigil-llm/tree/main/data/datasets"
    click VDB "https://github.com/deadbits/vigil-llm/tree/main/data/vdb"
    click YARA_Data "https://github.com/deadbits/vigil-llm/tree/main/data/yara"
    click Prompts "https://github.com/deadbits/vigil-llm/tree/main/data/prompts"
    click Regex "https://github.com/deadbits/vigil-llm/tree/main/data/regex"
    click LOADER "https://github.com/deadbits/vigil-llm/blob/main/loader.py"
    click ServerConf "https://github.com/deadbits/vigil-llm/blob/main/conf/server.conf"
    click DockerConf "https://github.com/deadbits/vigil-llm/blob/main/conf/docker.conf"
    click UI "https://github.com/deadbits/vigil-llm/blob/main/streamlit_app.py"

    %% Styles
    classDef api fill:#b3e5fc,stroke:#0277bd,stroke-width:2px;
    classDef core fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px;
    classDef scanner fill:#d1c4e9,stroke:#6a1b9a,stroke-width:2px;
    classDef data fill:#ffe0b2,stroke:#ef6c00,stroke-width:2px;
    classDef config fill:#ffcdd2,stroke:#c62828,stroke-width:2px;
    classDef external fill:#f0f4c3,stroke:#9e9d24,stroke-width:2px;
```
