# stoic-dad/project-erasmus architecture

> Architecture diagram of the GitHub repository stoic-dad/project-erasmus, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/stoic-dad/project-erasmus
- Repository: https://github.com/stoic-dad/project-erasmus

## Overview

##### Project type and purpose
- This is a containerized, full-stack “reasoning engine” that ingests SBOMs (Software Bill of Materials), enriches them with vulnerability & vendor-geo metadata, and exposes an interactive Streamlit dashboard augmented by local GenAI models (Ollama).
- Primary use-cases: offline SBOM parsing (via Syft CLI), CVE scanning (via Grype CLI), metadata joining (Python/pandas), data visualization (Streamlit), and contextual Q&A (Ollama LLM).

##### File structure
- Top level:
- Dockerfile, Dockerfile.dashboard, docker-compose.yml → container definitions
- app.py, src/… → application code
- *.sh scripts & Python scripts (generate_sboms.sh, generate_vulns.sh, auto_generate_vendor_geo.py, etc.) → data-prep & orchestration
- data/, vendor_geo.csv, unique_suppliers.txt, test_suppliers.py → sample data & tests
- requirements.txt → dependencies
- src/ folder:
- parse_sbom.py → SBOM parsing
- enrich_vendor.py → joining vendor geography
- .py, main.py → Streamlit UI entry points
- CI/Deployment:
- docker-compose.yml orchestrates multiple containers (app, possibly Ollama)

##### README for additional insights
- SBOM ingestion uses Syft CLI → CycloneDX JSON
- Vulnerability scanning uses Grype CLI
- Visualization in Streamlit (port 8501)
- Local LLMs served by Ollama, selectable via dropdown
- Fully Dockerized + offline

##### Main components & relationships
a. SBOM Generation & Vulnerability Scanning
- Syft CLI → SBOM JSON (“sbom-out.json”)
- Grype CLI → vulnerability report JSON
b. Data Enrichment Layer (Python/pandas)
- parse_sbom.py reads SBOM JSON → DataFrame
- run vulnerability JSON → DataFrame
- enrich_vendor.py joins vendor_geo.csv → enriched DataFrame
- persist intermediate CSVs (unique_suppliers.txt, vendor_geo.csv)
c. Streamlit Dashboard (app.py / src/main.py + src/display.py)
- Reads enriched data → interactive charts & tables
- Exposes dropdown to select Ollama model
- Sends prompts → Ollama API → receives textual summaries / answers
d. Local GenAI Engine (Ollama)
- qwen2.5-coder:7b, gemma:2b, openhermes:latest models
- Hosted locally or in a sidecar container
e. Orchestration & Containerization
- docker-compose.yml spawns:
– “erasmus-app” container (Python + Streamlit + CLI tools)
– “ollama” container (if used)
- Shared volumes for SBOMs, CSVs, and scripts

##### Architectural patterns & design principles
- Pipeline / ETL pattern for data ingestion → transform → load
- Modular separation:
- CLI wrappers & scripts for SBOM/vuln generation
- Domain logic in Python modules (parse, enrich)
- Presentation layer in Streamlit
- LLM integration via API adapter
- Containerized microservices (app vs. LLM engine)
- Data artifacts stored in files/volumes for reproducibility

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Ingestion Layer
    subgraph "Data Ingestion" 
        direction TB
        Syft["Syft CLI\n(generate_sboms.sh)"]:::cli
        Grype["Grype CLI\n(generate_vulns.sh)"]:::cli
    end

    %% ETL Layer
    subgraph "Python ETL" 
        direction TB
        Parse["parse_sbom.py"]:::etl
        Extract["extract_unique_suppliers.py"]:::etl
        Enrich["enrich_vendor.py"]:::etl
        AutoGeo["auto_generate_vendor_geo.py"]:::etl
    end

    %% Data Store
    subgraph "Data Store\n(CSV/JSON Files)" 
        direction TB
        DataDir["data/"]:::store
        VendorGeoCSV["vendor_geo.csv"]:::store
        UniqueSuppliers["unique_suppliers.txt"]:::store
    end

    %% Presentation Layer
    subgraph "Streamlit Dashboard\n(port 8501)" 
        direction TB
        App["app.py"]:::ui
        Main["src/main.py"]:::ui
        Display["src/display.py"]:::ui
    end

    %% LLM Service
    Ollama["Ollama LLM Engine"]:::llm

    %% Orchestration & Infra
    subgraph "Container Orchestration" 
        direction TB
        DockerApp["Dockerfile"]:::infra
        DockerDash["Dockerfile.dashboard"]:::infra
        Compose["docker-compose.yml"]:::infra
        Requirements["requirements.txt"]:::infra
    end

    %% Connections
    Syft -->|outputs SBOM JSON| Parse
    Grype -->|outputs vuln JSON| Parse
    Parse -->|DataFrame| Extract
    Extract -->|unique suppliers| UniqueSuppliers
    UniqueSuppliers --> AutoGeo
    AutoGeo -->|joined geo| Enrich
    Enrich -->|enriched CSV| VendorGeoCSV
    VendorGeoCSV --> DataDir
    DataDir --> App
    App --> Main
    Main --> Display
    Display -->|prompts| Ollama
    Ollama -->|responses| Display

    %% Infrastructure volumes
    Compose -->|mounts volumes| DataDir
    Compose --> DockerApp
    Compose --> DockerDash
    DockerApp -->|builds| App
    DockerApp -->|builds| Parse
    DockerApp -->|builds| Enrich

    %% Click Events
    click Syft "https://github.com/stoic-dad/project-erasmus/blob/main/generate_sboms.sh"
    click Syft "https://github.com/stoic-dad/project-erasmus/blob/main/generate_advanced_sboms.py"
    click Grype "https://github.com/stoic-dad/project-erasmus/blob/main/generate_vulns.sh"
    click Parse "https://github.com/stoic-dad/project-erasmus/blob/main/src/parse_sbom.py"
    click Extract "https://github.com/stoic-dad/project-erasmus/blob/main/extract_unique_suppliers.py"
    click Enrich "https://github.com/stoic-dad/project-erasmus/blob/main/src/enrich_vendor.py"
    click AutoGeo "https://github.com/stoic-dad/project-erasmus/blob/main/auto_generate_vendor_geo.py"
    click VendorGeoCSV "https://github.com/stoic-dad/project-erasmus/blob/main/data/vendor_geo.csv"
    click VendorGeoCSV "https://github.com/stoic-dad/project-erasmus/blob/main/vendor_geo.csv"
    click UniqueSuppliers "https://github.com/stoic-dad/project-erasmus/blob/main/unique_suppliers.txt"
    click DataDir "https://github.com/stoic-dad/project-erasmus/tree/main/data/"
    click App "https://github.com/stoic-dad/project-erasmus/blob/main/app.py"
    click Main "https://github.com/stoic-dad/project-erasmus/blob/main/src/main.py"
    click Display "https://github.com/stoic-dad/project-erasmus/blob/main/src/display.py"
    click DockerApp "https://github.com/stoic-dad/project-erasmus/tree/main/Dockerfile"
    click DockerDash "https://github.com/stoic-dad/project-erasmus/blob/main/Dockerfile.dashboard"
    click Compose "https://github.com/stoic-dad/project-erasmus/blob/main/docker-compose.yml"
    click Requirements "https://github.com/stoic-dad/project-erasmus/blob/main/requirements.txt"

    %% Styles
    classDef cli fill:#f9e79f,stroke:#b7950b,color:#1b2631,stroke-width:1px;
    classDef etl fill:#aed6f1,stroke:#5499c7,color:#1b2631,stroke-width:1px;
    classDef store fill:#d5f5e3,stroke:#28b463,color:#1b2631,stroke-width:1px;
    classDef ui fill:#fadbd8,stroke:#c0392b,color:#1b2631,stroke-width:1px;
    classDef llm fill:#d2b4de,stroke:#8e44ad,color:#1b2631,stroke-width:1px;
    classDef infra fill:#f5cba7,stroke:#d35400,color:#1b2631,stroke-width:1px;
```
