# lavantien/llm-tournament architecture

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

- Interactive diagram: https://gitdiagram.com/lavantien/llm-tournament
- Repository: https://github.com/lavantien/llm-tournament

## Overview

##### Main Components
- Frontend/User Interface:
– HTML templates (in the “templates” directory), CSS (e.g., style.css), and JavaScript (client-side code for handling dynamic interactions, including Chart.js and Marked.js for visualizations and markdown processing).
– The UI displays evaluation results, prompt management, and dashboards.

- Backend Server:
– The Go entry point is “main.go” which sets up the web server.
– “handlers” directory contains various HTTP endpoint handlers (models, profiles, prompts, results, stats, suites) that implement the core business logic.
– “middleware” houses utility plugins for request processing (socket management, state handling, error import utilities).
– “system_prompt_*.xml” files that define base prompt configurations or system messages.

- Data Storage:
– File-based persistence using JSON files stored in the “data” directory (profiles, prompts, results, test and default suites).
– This acts as a lightweight database that holds the system state and evaluation data.

- Real-Time Communication:
– Gorilla WebSocket (as mentioned in the README) used in middleware to provide real-time updates for scoring and collaboration.

- Complementary Tools:
– Located in “tools” (like “tts”, “bg_batch_eraser”, “openwebui”, and “ragweb_agent”), these represent auxiliary utilities that interface with the main system or extend functionality (e.g., generating podcast audio or image background removal).

##### Representing Interactions and Relationships
- Users interact with the Frontend via a web browser.

- Frontend and Backend Connection:
– HTTP endpoints deliver JSON or HTML responses from “handlers” with support for static file serving (assets, templates).
– WebSocket connections (managed by middleware/socket.go) provide real-time updates from the Backend to the client.

- Backend Components:
– The “handlers” interact with the file-based data storage (reading/writing JSON files) to persist evaluation state.
– Middleware components intercept calls for logging, state management, and error handling.
– The server orchestrates these components to deliver the evaluation engine (real-time scoring, state restoration, model ranking, etc.).

- Complementary Tools:
– Although these tools are not part of the core server, they are linked components (for instance, tts for audio generation or background removal will likely be triggered separately or via a UI integration).
– They can be shown as independent modules that can interact with the backend or operate as stand-alone utilities.

##### Architectural Patterns and Design Principles
- Separation of Concerns:
– Clearly divide the system into frontend, backend (with distinct responsibilities in Handlers and Middleware), and data storage.

- Real-Time Data Flow:
– Emphasize WebSocket communication for instantaneous client updates.

- Modular Design:
– The clear directory separation (handlers, middleware, templates, tools) reflects a modular design that can be drawn in separate component blocks.

- File-based Persistence:
– Show the JSON data storage as an integral DB substitute.

- Complementary Components:

##### Technologies and Frameworks
- Backend: Go (version 1.21+), Gorilla WebSocket, Blackfriday, Bluemonday.
- Frontend: HTML5, CSS3, JavaScript (ES6+), Chart.js, Marked.js.
- Data: JSON file storage with import/export support.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Global Entities
    U["User Browser"]:::external

    %% Frontend/UI Layer
    subgraph "Frontend/UI Layer"
        F1["HTML Templates"]:::frontend
        F2["CSS & JavaScript (Assets)"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend Layer"
        B1["Main Go Server (main.go)"]:::backend
        B2["HTTP Handlers"]:::backend
        B3["Middleware"]:::middleware
        S1["System Prompts"]:::config
    end

    %% Data Storage Layer
    subgraph "Data Storage Layer"
        D1["JSON Data Storage"]:::database
    end

    %% Complementary Tools
    subgraph "Complementary Tools"
        T1["TTS Tool"]:::tools
        T2["Background Eraser"]:::tools
        T3["OpenWebUI"]:::tools
        T4["RagWeb Agent"]:::tools
    end

    %% Connections and Data Flow
    U -->|"HTTP"| F1
    U -->|"HTTP"| F2

    B1 -->|"Routes"| B2
    B1 -->|"RealTime(WebSocket)"| B3
    B2 -->|"FileIO"| D1
    B2 -->|"Configures"| S1
    B3 -->|"WebSocket Updates"| U

    F1 -->|"UI_Triggers"| T1
    F1 -->|"UI_Triggers"| T2
    F1 -->|"UI_Triggers"| T3
    F1 -->|"UI_Triggers"| T4

    %% Click Events
    click F1 "https://github.com/lavantien/llm-tournament/tree/main/templates"
    click F2 "https://github.com/lavantien/llm-tournament/tree/main/assets"
    click B1 "https://github.com/lavantien/llm-tournament/blob/main/main.go"
    click B2 "https://github.com/lavantien/llm-tournament/tree/main/handlers"
    click B3 "https://github.com/lavantien/llm-tournament/blob/main/middleware/socket.go"
    click D1 "https://github.com/lavantien/llm-tournament/tree/main/data"
    click T1 "https://github.com/lavantien/llm-tournament/tree/main/tools/tts"
    click T2 "https://github.com/lavantien/llm-tournament/tree/main/tools/bg_batch_eraser"
    click T3 "https://github.com/lavantien/llm-tournament/tree/main/tools/openwebui"
    click T4 "https://github.com/lavantien/llm-tournament/tree/main/tools/ragweb_agent"
    click S1 "https://github.com/lavantien/llm-tournament/blob/main/system_prompt_general.xml"

    %% Styles
    classDef external fill:#D3D3D3,stroke:#000,stroke-width:2px;
    classDef frontend fill:#A0E7E5,stroke:#000,stroke-width:2px;
    classDef backend fill:#B4F8C8,stroke:#000,stroke-width:2px;
    classDef middleware fill:#FFAEBC,stroke:#000,stroke-width:2px;
    classDef database fill:#FFC6FF,stroke:#000,stroke-width:2px;
    classDef tools fill:#FAF0BE,stroke:#000,stroke-width:2px;
    classDef config fill:#cce5ff,stroke:#000,stroke-width:2px;
```
