# jonathanchaveztamales/llm-leaderboard architecture

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

- Interactive diagram: https://gitdiagram.com/jonathanchaveztamales/llm-leaderboard
- Repository: https://github.com/jonathanchaveztamales/llm-leaderboard

## Overview

##### Project type and purpose
- This is a “static data + schema repository” that feeds an interactive dashboard (llm-stats.com).
- No traditional MVC backend: data lives as JSON, validated via JSON Schema and Node.js scripts; front-end is a static site (hosted on a CDN).

##### File structure
- Top-level:
- data/ – JSON files (models, providers, benchmarks, organizations, licenses)
- schemas/ – JSON Schema files + validator scripts
- results-validator/ – CLI or helper code for validating result sets
- package.json – Node.js tooling for validation and build
- .github/workflows/schema-validation.yml – CI workflow for running validators
- No src/frontend folder here: the site itself likely lives elsewhere or is built via another pipeline reading these files.

##### Main components
a. Contributors & Maintainers
b. GitHub Repository (Data + Schemas + Validation scripts)
c. CI/CD (GitHub Actions)
d. Validator Service (Node.js JSON-Schema checks)
e. Deployment Target (Static-site hosting or CDN)
f. End-User Client (Browser running the dashboard)

##### Relationships and interactions
- Contributor opens a Pull Request → GitHub Actions triggers schema and integrity validation → Validator scripts run against data/ JSON using schemas/ → If validation passes, PR can merge.
- On merge (main branch): GitHub Actions or another workflow builds/deploys the static site (pulls data folder, bundles it, publishes to hosting).
- End-user’s browser fetches static assets (HTML/CSS/JS) + JSON data from the CDN, then renders the interactive dashboard.

##### Architectural patterns & design principles
- Static-Site Generation pattern: treat JSON files as data source, build artifacts served on CDN.
- CI/CD pipeline ensures data integrity before merge or deploy.
- Schema-first design: all JSON must conform to schemas/ via automated validation.
- Separation of concerns:
- Data storage (data/)
- Data validation (schemas/, results-validator/)
- Build & deploy (GitHub Actions)
- Consumption (static site + client)

##### Technologies & frameworks
- GitHub Actions (.github/workflows/schema-validation.yml) for CI.
- Node.js (package.json) & JSON-Schema (schemas/*.schema.json + validator.js).
- JSON files served over HTTP from a CDN or GitHub Pages/custom domain.
- Front-end (not in this repo) likely a JS framework fetching these JSON endpoints.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Actors
    C["Contributor"]:::actor
    U["End-User (Browser)"]:::actor

    %% GitHub Repository
    subgraph "GitHub Repository"
        Data["data/ (JSON)"]:::data
        subgraph "schemas/ (JSON-Schema)"
            BS1["benchmark-results.schema.json"]:::data
            BS2["benchmark.schema.json"]:::data
            BS3["license.schema.json"]:::data
            BS4["model.schema.json"]:::data
            BS5["organization.schema.json"]:::data
            BS6["provider-models.schema.json"]:::data
            BS7["provider.schema.json"]:::data
        end
        subgraph "Validation Scripts"
            V1["validator.js"]:::process
            V2["integrity-validator.js"]:::process
            VR["results-validator/"]:::process
        end
        CFG1["package.json"]:::process
        CFG2["package-lock.json"]:::process
        CI[".github/workflows/schema-validation.yml"]:::process
    end

    %% Validation Service
    VS["Validator Service (Node.js)"]:::process

    %% Merge & Deploy
    MB["Merge, Build & Deploy"]:::process

    %% Hosting
    Host["Hosting/CDN"]:::external

    %% Flows
    C -->|"opens PR"| CI
    CI -->|"runs validation"| VS
    VS -->|"uses data & schemas"| CI
    Data --> VS
    BS1 --> VS
    BS2 --> VS
    BS3 --> VS
    BS4 --> VS
    BS5 --> VS
    BS6 --> VS
    BS7 --> VS
    V1 --> VS
    V2 --> VS
    VR --> VS
    CI -->|"on merge"| MB
    MB -->|"publishes static site"| Host
    U -->|"fetches assets & JSON"| Host
    Host -->|"serves JSON data and site"| U

    %% Click Events
    click Data "https://github.com/jonathanchaveztamales/llm-leaderboard/tree/main/data/"
    click BS1 "https://github.com/jonathanchaveztamales/llm-leaderboard/blob/main/schemas/benchmark-results.schema.json"
    click BS2 "https://github.com/jonathanchaveztamales/llm-leaderboard/blob/main/schemas/benchmark.schema.json"
    click BS3 "https://github.com/jonathanchaveztamales/llm-leaderboard/blob/main/schemas/license.schema.json"
    click BS4 "https://github.com/jonathanchaveztamales/llm-leaderboard/blob/main/schemas/model.schema.json"
    click BS5 "https://github.com/jonathanchaveztamales/llm-leaderboard/blob/main/schemas/organization.schema.json"
    click BS6 "https://github.com/jonathanchaveztamales/llm-leaderboard/blob/main/schemas/provider-models.schema.json"
    click BS7 "https://github.com/jonathanchaveztamales/llm-leaderboard/blob/main/schemas/provider.schema.json"
    click V1 "https://github.com/jonathanchaveztamales/llm-leaderboard/blob/main/schemas/validator.js"
    click V2 "https://github.com/jonathanchaveztamales/llm-leaderboard/blob/main/schemas/integrity-validator.js"
    click VR "https://github.com/jonathanchaveztamales/llm-leaderboard/tree/main/results-validator/"
    click CI "https://github.com/jonathanchaveztamales/llm-leaderboard/blob/main/.github/workflows/schema-validation.yml"
    click CFG1 "https://github.com/jonathanchaveztamales/llm-leaderboard/blob/main/package.json"
    click CFG2 "https://github.com/jonathanchaveztamales/llm-leaderboard/blob/main/package-lock.json"

    %% Styles
    classDef actor fill:#f96,stroke:#333,stroke-width:2px
    classDef data fill:#bbf,stroke:#333,stroke-width:1px
    classDef process fill:#cfc,stroke:#333,stroke-width:1px
    classDef external fill:#ddd,stroke:#333,stroke-width:1px
```
