# esl-epfl/szcore architecture

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

- Interactive diagram: https://gitdiagram.com/esl-epfl/szcore
- Repository: https://github.com/esl-epfl/szcore

## Overview

##### Main Components
- Repository & Version Control – Source code, configuration files, algorithm YAML submissions, and website files are all managed in Git.
- Algorithm Submission Interface – Developers add a new YAML file (and submit their containerized algorithm image) into the “algorithms” (and optionally “challenge_algorithms”) directory.
- CI/CD Pipeline – GitHub Actions workflows (listed under .github/workflows) are used to validate PRs (“1-pr-check.yml”), build and deploy the website (“2-build-website.yml”), and to handle Docker image verification (docker-publish-algo-checks.yml).
- Algorithm Container Execution Environment – Docker images built using the provided Dockerfile templates (in config) execute the submitted algorithms offline. They run inference, use predefined paths for I/O, and compute performance metrics.
- Benchmarking Engine – Once merged, the CI jobs pull the Docker images, execute algorithms on benchmark datasets, and produce performance metrics (whose outputs are stored in the “results” directory as JSON files).
- Static Website – The “website” directory contains the static site content (assets, Hugo configuration, layouts, themes) that displays benchmark results, algorithm details, datasets, and challenge descriptions.

##### Relationships and Interactions
- The user (algorithm developer) submits a YAML file and links to their Docker image via a PR.
- The submission triggers the CI/CD workflows; one branch verifies the submission while another builds and deploys the website.
- The Docker image (built according to the provided template) is executed by the CI pipeline, which runs benchmarks using input data stored in “tests” and references datasets defined in “website/content/datasets”.
- Benchmark results are generated and stored in the “results” folder and then pushed/updated on the static website.
- The website serves as an interface for viewing the detailed performance statistics of submitted algorithms.

##### Architectural Patterns and Design Principles
- Modular design with clear separation of concerns: The repository is split between algorithm definitions, site content, CI/CD configurations, and benchmarking data.
- Containerization: The use of Docker ensures that algorithm execution is isolated and standardized.
- Automation through CI/CD: GitHub Actions manages continuous integration, validation, and deployment cycles.
- Static Website Generation: Use of Hugo and static asset management for front-end presentation simplifies the deployment process.
- Open source extensibility: New algorithms and challenges are introduced by adding new YAML files (using a consistent schema) and corresponding Docker images.

##### Technologies, Frameworks, and Libraries
- GitHub Actions as the orchestration/automation tool.
- Docker for containerization (with Dockerfiles provided in the “config” directory).
- YAML as the submission configuration format.
- Hugo and Tailwind CSS (inside the “website” directory) for building the static website.
- Python scripts (in “website/python_scripts”) for parsing and processing benchmark results.
- Various JSON files in “results” and “website/static” to store and serve performance metrics.

- Submission (developers pushing PRs) → CI/CD jobs →
- Containerized Testing/Benchmarking (using Docker images based on the template) →
- Results Output (JSON files saved in the “results” directory) →
- Website Update (static site regeneration and deployment).
- External actors like “Algorithm Developer” (initiates a PR) and “User/Researcher” (viewing the website).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Actors
    Developer("Algorithm Developer"):::actor
    User("User/Researcher"):::actor

    %% Repository & Version Control Subgraph
    subgraph "Repository & Version Control"
        Alg("Algorithms (algorithms/)"):::repo
        Challenge("Challenge Algorithms (challenge_algorithms/)"):::repo
    end

    %% CI/CD Pipeline Subgraph
    subgraph "CI/CD Pipeline"
        PR_Check("PR Check (.github/workflows/1-pr-check.yml)"):::cicd
        Build_Web("Build Website (.github/workflows/2-build-website.yml)"):::cicd
        Docker_Publish("Docker Publish Checks (.github/workflows/docker-publish-algo-checks.yml)"):::cicd
    end

    %% Algorithm Container Execution Environment Subgraph
    subgraph "Algorithm Container Execution Environment"
        AlgoDocker("Algo-checks Dockerfile (config/algo-checks.Dockerfile)"):::docker
        TemplateDocker("Template Dockerfile (config/template.Dockerfile)"):::docker
    end

    %% Benchmarking Engine Subgraph
    subgraph "Benchmarking Engine"
        Benchmark("Benchmark Results (results/)"):::benchmark
    end

    %% Static Website Subgraph
    subgraph "Static Website"
        Site_Config("Hugo Config (website/config)"):::website
        Site_Content("Content (website/content)"):::website
        Site_Layouts("Layouts (website/layouts)"):::website
        Site_Static("Static files (website/static)"):::website
        Site_Python("Python Scripts (website/python_scripts)"):::website
        Site_Themes("Themes (website/themes)"):::website
    end

    %% Flow connections
    Developer -->|"submits PR with YAML & Docker image"| Alg
    Developer -->|"submits PR with YAML & Docker image"| Challenge

    Alg -->|"triggers"| PR_Check
    Challenge -->|"triggers"| PR_Check

    PR_Check -->|"initiates"| Docker_Publish
    PR_Check -->|"initiates"| Build_Web

    Docker_Publish -->|"builds container"| AlgoDocker
    Docker_Publish -->|"builds container"| TemplateDocker

    AlgoDocker -->|"executes algorithm"| Benchmark
    TemplateDocker -->|"supports template"| Benchmark

    Build_Web -->|"deploys site"| Site_Config
    Build_Web -->|"deploys site"| Site_Content
    Build_Web -->|"deploys site"| Site_Layouts
    Build_Web -->|"deploys site"| Site_Static
    Build_Web -->|"deploys site"| Site_Python
    Build_Web -->|"deploys site"| Site_Themes

    Benchmark -->|"updates website"| Site_Content

    Site_Static -->|"view performance"| User

    %% Click Events
    click Alg "https://github.com/esl-epfl/szcore/tree/main/algorithms/"
    click Challenge "https://github.com/esl-epfl/szcore/tree/main/challenge_algorithms/"
    click PR_Check "https://github.com/esl-epfl/szcore/blob/main/.github/workflows/1-pr-check.yml"
    click Build_Web "https://github.com/esl-epfl/szcore/blob/main/.github/workflows/2-build-website.yml"
    click Docker_Publish "https://github.com/esl-epfl/szcore/blob/main/.github/workflows/docker-publish-algo-checks.yml"
    click AlgoDocker "https://github.com/esl-epfl/szcore/blob/main/config/algo-checks.Dockerfile"
    click TemplateDocker "https://github.com/esl-epfl/szcore/blob/main/config/template.Dockerfile"
    click Benchmark "https://github.com/esl-epfl/szcore/tree/main/results/"
    click Site_Config "https://github.com/esl-epfl/szcore/tree/main/website/config"
    click Site_Content "https://github.com/esl-epfl/szcore/tree/main/website/content"
    click Site_Layouts "https://github.com/esl-epfl/szcore/tree/main/website/layouts"
    click Site_Static "https://github.com/esl-epfl/szcore/tree/main/website/static"
    click Site_Python "https://github.com/esl-epfl/szcore/tree/main/website/python_scripts"
    click Site_Themes "https://github.com/esl-epfl/szcore/tree/main/website/themes"

    %% Styles
    classDef actor fill:#b3e5fc,stroke:#0277bd,stroke-width:2px;
    classDef repo fill:#ffe082,stroke:#ff6f00,stroke-width:2px;
    classDef cicd fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px;
    classDef docker fill:#d7ccc8,stroke:#3e2723,stroke-width:2px;
    classDef benchmark fill:#f8bbd0,stroke:#880e4f,stroke-width:2px;
    classDef website fill:#d1c4e9,stroke:#4527a0,stroke-width:2px;
```
