# eethansmith/dissertation-project architecture

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

- Interactive diagram: https://gitdiagram.com/eethansmith/dissertation-project
- Repository: https://github.com/eethansmith/dissertation-project

## Overview

##### Project Type and Purpose
- Full-stack benchmarking tool: React-based frontend (“react-dashboard”) + Flask backend (“interactive-backend”).
- Purpose: allow users to upload CSV test scripts, select AI guardrails, run adversarial prompt tests asynchronously, and view interactive visualizations of detection rates/latency.

##### File Structure
- Top level:
- Dashboard_App/
– interactive-backend/ (Flask API + guardrail engine)
– react-dashboard/ (Vite + React UI)
- interactive-backend/app/: core modules (routes.py, processing.py, tasks.py, utils.py, config.py)
- interactive-backend/guards/: plug-in guardrail implementations (guardrails_ai.py, lakera_guard.py, presidio.py, etc.)
- interactive-backend/test-scripts/ & test-dataset/: CSV inputs & auto-generated results storage.
- react-dashboard/src/components: presentational components (Dashboard, Tables, Modals, VizBlocks).
- react-dashboard/src/services/api.js: API wrapper.

##### README for Additional Insights
- Backend uses concurrent.futures for asynchronous guard execution.
- Results persist to filesystem under test-dataset/<testID>/.

##### Main Components and Their Relationships
a. Frontend (React Dashboard)
- Components: Upload form, Guardrail Panel, Run Test button, Real-time charts (D3).
- Service layer calls REST endpoints on Flask backend.
b. Backend (Flask API Gateway)
- routes.py: defines endpoints (upload CSV, start test, fetch results).
- processing.py & tasks.py: orchestrate asynchronous execution.
- utils.py/config.py: config, env var handling.
c. Guard Execution Layer
- Each guard implementation in guards/*.py exposes preprocess() / postprocess().
- Orchestrated by concurrent.futures worker pool.
d. LLM Provider (external service)
- OpenRouter / OpenAI / HuggingFace, selected via LLM_PROVIDER env var.
e. Data Stores (local filesystem)
- test-scripts/: CSV inputs
- test-dataset/<testID>/: JSON/CSV outputs (pie_chart.csv, success_bar_chart.csv, etc.)
- test_list.csv: registry of test runs.

##### Architectural Patterns and Design Principles
- Plug-in architecture: drop new guard file → auto-discovered by backend.
- Asynchronous task execution: non-blocking guard + LLM calls.
- Separation of concerns: clear boundary between UI (React), API (Flask), guard modules, and data persistence.
- REST/JSON API layer for communication.
- File-based persistence simplifies traceability (no external DB).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User
    User["User"]:::external

    %% Frontend Layer
    subgraph "React Dashboard"
        direction TB
        FE_Index["src/index.js"]:::frontend
        FE_Dashboard["components/Dashboard.js"]:::frontend
        FE_Table["components/DashboardTable.js"]:::frontend
        FE_Viz["components/VizBlock.js"]:::frontend
        FE_Modal["components/TestModal.js"]:::frontend
        FE_API["services/api.js"]:::frontend
    end

    %% API Gateway
    subgraph "Flask API Gateway"
        direction TB
        API_Run["run.py"]:::api
        API_Routes["app/routes.py"]:::api
        API_Processing["app/processing.py"]:::api
        API_Tasks["app/tasks.py"]:::api
        API_Config["app/config.py"]:::api
        API_Utils["app/utils.py"]:::api
    end

    %% Guard Execution Layer
    subgraph "Guard Execution" 
        direction TB
        Guard_AI["guards/guardrails_ai.py"]:::processing
        Guard_Lakera["guards/lakera_guard.py"]:::processing
        Guard_Presidio["guards/presidio.py"]:::processing
        AutoLoader["guards/*.py auto-loader"]:::processing
    end

    %% External LLM Provider
    LLM["LLM Provider"]:::external

    %% Data Stores
    subgraph "Filesystem Data Stores"
        direction TB
        Scripts["test-scripts/"]:::storage
        Registry["test_list.csv"]:::storage
        Results["test-dataset/"]:::storage
    end

    %% Connections
    User -->|"interacts"| FE_Index
    FE_Index -->|"HTTP/JSON"| API_Run
    FE_API -->|"HTTP/JSON"| API_Routes
    API_Run -->|"register routes"| API_Routes
    API_Routes -->|"invoke"| API_Processing
    API_Processing -->|"submit tasks (concurrent.futures)"| API_Tasks
    API_Tasks -->|"load plugins"| AutoLoader
    AutoLoader --> Guard_AI
    AutoLoader --> Guard_Lakera
    AutoLoader --> Guard_Presidio
    API_Tasks -->|"reads scripts"| Scripts
    Guard_AI -->|"HTTP/JSON"| LLM
    Guard_Lakera -->|"HTTP/JSON"| LLM
    Guard_Presidio -->|"HTTP/JSON"| LLM
    Guard_AI -->|"Filesystem I/O"| Results
    Guard_Lakera -->|"Filesystem I/O"| Results
    Guard_Presidio -->|"Filesystem I/O"| Results
    FE_Index -->|"polls/fetches results"| API_Routes
    API_Routes -->|"reads results"| Results
    API_Routes -->|"reads registry"| Registry

    %% Click Events
    click FE_Index "https://github.com/eethansmith/dissertation-project/blob/main/Dashboard_App/react-dashboard/src/index.js"
    click FE_Dashboard "https://github.com/eethansmith/dissertation-project/blob/main/Dashboard_App/react-dashboard/src/components/Dashboard.js"
    click FE_Table "https://github.com/eethansmith/dissertation-project/blob/main/Dashboard_App/react-dashboard/src/components/DashboardTable.js"
    click FE_Viz "https://github.com/eethansmith/dissertation-project/blob/main/Dashboard_App/react-dashboard/src/components/VizBlock.js"
    click FE_Modal "https://github.com/eethansmith/dissertation-project/blob/main/Dashboard_App/react-dashboard/src/components/TestModal.js"
    click FE_API "https://github.com/eethansmith/dissertation-project/blob/main/Dashboard_App/react-dashboard/src/services/api.js"
    click API_Run "https://github.com/eethansmith/dissertation-project/blob/main/Dashboard_App/interactive-backend/run.py"
    click API_Routes "https://github.com/eethansmith/dissertation-project/blob/main/Dashboard_App/interactive-backend/app/routes.py"
    click API_Processing "https://github.com/eethansmith/dissertation-project/blob/main/Dashboard_App/interactive-backend/app/processing.py"
    click API_Tasks "https://github.com/eethansmith/dissertation-project/blob/main/Dashboard_App/interactive-backend/app/tasks.py"
    click API_Config "https://github.com/eethansmith/dissertation-project/blob/main/Dashboard_App/interactive-backend/app/config.py"
    click API_Utils "https://github.com/eethansmith/dissertation-project/blob/main/Dashboard_App/interactive-backend/app/utils.py"
    click Guard_AI "https://github.com/eethansmith/dissertation-project/blob/main/Dashboard_App/interactive-backend/guards/guardrails_ai.py"
    click Guard_Lakera "https://github.com/eethansmith/dissertation-project/blob/main/Dashboard_App/interactive-backend/guards/lakera_guard.py"
    click Guard_Presidio "https://github.com/eethansmith/dissertation-project/blob/main/Dashboard_App/interactive-backend/guards/presidio.py"
    click Scripts "https://github.com/eethansmith/dissertation-project/tree/main/Dashboard_App/interactive-backend/test-scripts/"
    click Registry "https://github.com/eethansmith/dissertation-project/blob/main/Dashboard_App/interactive-backend/test_list.csv"
    click Results "https://github.com/eethansmith/dissertation-project/tree/main/Dashboard_App/interactive-backend/test-dataset/"

    %% Styles
    classDef frontend fill:#9f6,stroke:#333,stroke-width:1px
    classDef api fill:#6cf,stroke:#333,stroke-width:1px
    classDef processing fill:#fc6,stroke:#333,stroke-width:1px
    classDef external fill:#ccc,stroke:#333,stroke-width:1px
    classDef storage fill:#f96,stroke:#333,stroke-width:1px
```
