# yacwagh/arrows architecture

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

- Interactive diagram: https://gitdiagram.com/yacwagh/arrows
- Repository: https://github.com/yacwagh/arrows

## Overview

##### Project Type and Purpose
- This project is a full-stack web application focused on automated threat modeling using artificial intelligence. It leverages the STRIDE methodology to analyze both application descriptions and codebases.
- The tool offers interactive visualization (using Vis.js) and integrates with external LLM services (OpenAI or OpenRouter).

##### File Structure
- Key directories include:
- Root-level Python files (app.py, main.py) that indicate the Flask web server initialization and entry points.
- The "llm" directory containing configuration and prompt definitions for LLM integration.
- The "system_architecture" directory housing scripts for system and whitebox analysis.
- The "threat_model" directory, which defines various threat analyzers based on STRIDE (e.g., Dos, Elevation, Info Disclosure, etc.).
- The "static" and "templates" folders for frontend assets (HTML, CSS, and JavaScript) supporting the interactive visualization.
- An "examples" folder which provides sample inputs for both application descriptions and a React-based codebase.

a. Main Components:
- Frontend/UI: Represented by the web server (Flask in app.py) that serves HTML templates and static assets.
- Core Analysis Engine:
- System Analyzer and Whitebox Analyzer (located in system_architecture)
- Threat Analyzers (in threat_model) that process and model the security threats.
- LLM Integration: Represented by the "llm" directory where LLM configuration and prompt handling are defined. It interfaces with external APIs (OpenAI and OpenRouter).
- Input Sources: Two distinct inputs for description-based and codebase analysis (as depicted in the examples folder).
- Threat Model Composer: The component that organizes results into detailed threat models (identifying components, data flows, assets, trust boundaries, threats).
- Analysis Features: STRIDE-based analysis with additional risk assessment and mitigation strategies.

b. Relationships and Interactions:
- Input Sources feed data into two separate analysis pipelines (Description Input goes to the System Analyzer and Code Input goes to the Whitebox Analyzer).
- Both analyzers pass their results to the Threat Analyzer, which then involves the LLM service for deeper analysis.
- The LLM service communicates with external LLM providers to get enhanced insights before the final threat model output is generated.
- The final output is structured into a visual representation (graph) showing components, data flows, and trust boundaries.

c. Architectural Patterns and Design Principles:
- Layered Architecture: A clear separation between the user interface (frontend), the business logic (analysis engines), integration with data sources (LLM services), and presentation (interactive threat model visualization).
- Modularity: Each analysis component (system analyzer, whitebox analysis, threat analyzers) is isolated in different directories, which makes future extensions or adjustments more manageable.

d. Relevant Technologies/Frameworks:
- Backend: Python (Flask), analysis modules (for STRIDE threat detection), integration with LLM services.
- Frontend: HTML5, CSS3, JavaScript (utilizing Vis.js and Bootstrap 5).
- External services: OpenAI/OpenRouter APIs for LLM services.

##### Elements
- Use clear and descriptive labels for each component (e.g., “System Analyzer”, “Whitebox Analyzer”, “Threat Analyzer”, “LLM Service”, “OpenAI API”, “Threat Model Component”).
- Input Sources → System/Whitebox Analysis → Threat Analyzer → LLM Integration → Threat Model.
- Frontend/UI components (e.g., rectangles)
- Backend analysis components (e.g., rounded rectangles or clouds)

##### Putting It All Together
- That the integration with the LLM module (from the "llm" folder) and its connection to external API endpoints is clearly visualized.
- Additional details such as interactive visualization components (static/js/graph.js) that render the threat model output dynamically in the web interface.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Input Sources Subgraph
    subgraph "Input Sources"
        AD["Application Description"]:::input
        CS["Codebase Sample"]:::input
    end

    %% Core Analysis Engine Subgraph
    subgraph "Core Analysis Engine"
        SA["System Analyzer"]:::analysis
        WA["Whitebox Analyzer"]:::analysis
    end

    %% Threat Analyzer Subgraph
    subgraph "Threat Analyzer"
        DA["Dos Analyzer"]:::threat
        EA["Elevation Analyzer"]:::threat
        IDA["Info Disclosure Analyzer"]:::threat
        RA["Repudiation Analyzer"]:::threat
        SAa["Spoofing Analyzer"]:::threat
        TA["Tampering Analyzer"]:::threat
        ST["STRIDE Analyzer"]:::threat
    end

    %% LLM Integration Subgraph
    subgraph "LLM Integration"
        LS["LLM Service"]:::llm
        LP["LLM Prompts"]:::llm
        API1(("OpenAI API")):::external
        API2(("OpenRouter API")):::external
    end

    %% Threat Model Composer Node
    TMC["Threat Model Composer"]:::analysis

    %% Frontend/UI Subgraph
    subgraph "Frontend/UI"
        WS["Web Server & Template Rendering"]:::frontend
        TEMPL["Templates"]:::frontend
        GS["Graph Script"]:::frontend
        CSSN["CSS Styles"]:::frontend
    end

    %% Data Flow Connections
    AD -->|"feeds"| SA
    CS -->|"feeds"| WA
    SA -->|"analyzes"| DA
    WA -->|"analyzes"| DA
    %% (Threat Analyzer sub-components are considered parallel analyzers)
    DA --- EA
    EA --- IDA
    IDA --- RA
    RA --- SAa
    SAa --- TA
    TA --- ST

    %% Aggregating threat analyzer output to LLM service
    ST -->|"refines"| LS
    LP -->|"configures"| LS
    LS -->|"calls"| API1
    LS -->|"calls"| API2

    %% LLM result feeds into threat model composition
    LS -->|"composes"| TMC

    %% Threat model output is served to frontend
    TMC -->|"renders"| WS
    WS -->|"serves"| TEMPL
    WS -->|"integrates"| GS
    WS -->|"styles"| CSSN

    %% Click Events for Input Sources
    click AD "https://github.com/yacwagh/arrows/blob/main/examples/application.txt"
    click CS "https://github.com/yacwagh/arrows/tree/main/examples/react-app/"

    %% Click Events for Core Analysis Engine
    click SA "https://github.com/yacwagh/arrows/blob/main/system_architecture/system_analyzer.py"
    click WA "https://github.com/yacwagh/arrows/blob/main/system_architecture/whitebox_analyzer.py"

    %% Click Events for Threat Analyzer Components
    click DA "https://github.com/yacwagh/arrows/blob/main/threat_model/dos_analyzer.py"
    click EA "https://github.com/yacwagh/arrows/blob/main/threat_model/elevation_analyzer.py"
    click IDA "https://github.com/yacwagh/arrows/blob/main/threat_model/info_disclosure_analyzer.py"
    click RA "https://github.com/yacwagh/arrows/blob/main/threat_model/repudiation_analyzer.py"
    click SAa "https://github.com/yacwagh/arrows/blob/main/threat_model/spoofing_analyzer.py"
    click TA "https://github.com/yacwagh/arrows/blob/main/threat_model/tampering_analyzer.py"
    click ST "https://github.com/yacwagh/arrows/blob/main/threat_model/stride_analyzer.py"

    %% Click Events for LLM Integration
    click LS "https://github.com/yacwagh/arrows/blob/main/llm/llmConfig.py"
    click LP "https://github.com/yacwagh/arrows/tree/main/llm/prompts/"

    %% Click Events for Frontend/UI Components
    click WS "https://github.com/yacwagh/arrows/blob/main/app.py"
    click TEMPL "https://github.com/yacwagh/arrows/tree/main/templates/"
    click GS "https://github.com/yacwagh/arrows/blob/main/static/js/graph.js"
    click CSSN "https://github.com/yacwagh/arrows/blob/main/static/css/styles.css"

    %% Styles
    classDef input fill:#f9e79f,stroke:#d35400,stroke-width:2px;
    classDef analysis fill:#aed6f1,stroke:#2874a6,stroke-width:2px;
    classDef threat fill:#f9c79f,stroke:#e67e22,stroke-width:2px;
    classDef llm fill:#abebc6,stroke:#27ae60,stroke-width:2px;
    classDef frontend fill:#d6eaf8,stroke:#2e86c1,stroke-width:2px;
    classDef external fill:#f5b7b1,stroke:#cb4335,stroke-width:2px;
```
