# rhombusgg/rhombus architecture

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

- Interactive diagram: https://gitdiagram.com/rhombusgg/rhombus
- Repository: https://github.com/rhombusgg/rhombus

## Overview

##### Project type and purpose
- This is a full-stack, extendable Capture-The-Flag (CTF) framework written in Rust, with a TypeScript/JS frontend and a plugin system.
- It provides a core Rust web server (rhombus/), a CLI tool (rhombus-cli/), build-script support (rhombus-build/), plus example deployments and plugins.

##### File structure
- Top-level components:
- rhombus/ – the core library and server (Rust, templates, static, frontend TSX, migrations, locales)
- rhombus-cli/ – CLI management tool for contests
- rhombus-build/ – build-time library for code‐generation or assets
- examples/ – standalone servers, demo site, plugin samples
- docs/ – documentation site (VitePress)
- Within rhombus/:
- src/internal/ – HTTP routing, business logic, plugin loader, email, Discord, database providers
- frontend/ – Deno/TypeScript React-style code for interactive UI components
- templates/ – server-side Minijinja HTML templates
- static/ – JS helper scripts and CSS assets
- migrations/ – SQL schema for Postgres and libSQL (SQLite)
- Config and CI: Dockerfile, Taskfile.yaml, GitHub workflows, Nix flake

##### README for insights
- Project is deployed as a monolithic Rust server that embeds TSX frontend via Deno, serves HTML templates, and exposes HTTP/gRPC endpoints.
- Supports swapping database backends, email providers, upload backends, and plugin extensions.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Frontend Layer
    subgraph "Frontend Layer"
        Browser["Client (Browser)"]:::frontend
        TSX["TSX Components"]:::frontend
        Static["Static Assets (JS/CSS)"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend (Rust Server)" 
        router["HTTP Router"]:::backend
        grpcServ["gRPC Server"]:::backend
        coreAuth["Authentication Module"]:::backend
        challengeLoader["Challenge Loader / Plugin Entry"]:::backend
        scoreboard["Scoreboard Service"]:::backend
        emailSvc["Email Service Providers"]:::backend
        discordInt["Discord Integration"]:::backend
        uploadProv["Upload Providers"]:::backend
        dbLayer["Database Layer & Migrations"]:::backend
        templates["Server Templates"]:::backend
        pluginSys["Plugin System Runtime"]:::backend
    end

    %% Infrastructure & Tools
    subgraph "Infrastructure & Tools"
        subgraph "Database"
            Postgres["Postgres"]:::infra
            libSQL["libSQL (SQLite)"]:::infra
        end
        subgraph "Migrations"
            pgMigrations["Postgres Migrations"]:::infra
            lsMigrations["libSQL Migrations"]:::infra
        end
        subgraph "External Services"
            SMTP["SMTP/IMAP"]:::external
            Mailgun["Mailgun API"]:::external
            DiscordAPI["Discord API"]:::external
            S3["S3 Storage"]:::external
        end
        CLI["CLI Tool"]:::infra
        Build["Build System / Codegen"]:::infra
        Config["Docker / CI / Nix"]:::infra
    end

    %% Connections
    Browser -->|GET TSX| TSX
    Browser -->|GET Static| Static
    Browser -->|AJAX/JSON| router

    TSX --> router
    Static --> router

    router -->|routes to| coreAuth
    router -->|routes to| scoreboard
    router -->|routes to| uploadProv
    router -->|render| templates
    router -->|invoke| pluginSys

    router -->|SQL queries| dbLayer
    grpcServ -->|gRPC calls| pluginSys
    grpcServ -->|admin tasks| CLI

    pluginSys -->|load| challengeLoader
    challengeLoader -->|extends| router

    coreAuth -->|queries| dbLayer
    scoreboard -->|queries| dbLayer
    uploadProv -->|writes| S3
    uploadProv -->|writes| Config

    emailSvc -->|send via| SMTP
    emailSvc -->|send via| Mailgun
    discordInt -->|post to| DiscordAPI

    dbLayer -->|migrate| pgMigrations
    dbLayer -->|migrate| lsMigrations
    dbLayer -->|stores in| Postgres
    dbLayer -->|stores in| libSQL

    Build -->|generate code| router
    Build -->|generate code| CLI

    %% Click Events
    click TSX "https://github.com/rhombusgg/rhombus/tree/main/rhombus/frontend/"
    click Static "https://github.com/rhombusgg/rhombus/tree/main/rhombus/static/"
    click router "https://github.com/rhombusgg/rhombus/blob/main/rhombus/src/internal/router.rs"
    click grpcServ "https://github.com/rhombusgg/rhombus/blob/main/rhombus/src/grpc.rs"
    click coreAuth "https://github.com/rhombusgg/rhombus/blob/main/rhombus/src/internal/auth.rs"
    click challengeLoader "https://github.com/rhombusgg/rhombus/blob/main/rhombus/src/challenge_loader_plugin.rs"
    click scoreboard "https://github.com/rhombusgg/rhombus/blob/main/rhombus/src/internal/routes/scoreboard.rs"
    click SMTP "https://github.com/rhombusgg/rhombus/blob/main/rhombus/src/internal/email/smtp.rs"
    click Mailgun "https://github.com/rhombusgg/rhombus/blob/main/rhombus/src/internal/email/mailgun.rs"
    click DiscordAPI "https://github.com/rhombusgg/rhombus/blob/main/rhombus/src/internal/discord.rs"
    click uploadProv "https://github.com/rhombusgg/rhombus/blob/main/rhombus/src/internal/upload_provider.rs"
    click dbLayer "https://github.com/rhombusgg/rhombus/tree/main/rhombus/src/internal/database/"
    click pgMigrations "https://github.com/rhombusgg/rhombus/tree/main/rhombus/migrations/postgresql/"
    click lsMigrations "https://github.com/rhombusgg/rhombus/tree/main/rhombus/migrations/libsql/"
    click templates "https://github.com/rhombusgg/rhombus/tree/main/rhombus/templates/"
    click CLI "https://github.com/rhombusgg/rhombus/tree/main/rhombus-cli/"
    click Build "https://github.com/rhombusgg/rhombus/tree/main/rhombus-build/"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#004085,color:#004085
    classDef backend fill:#d4edda,stroke:#155724,color:#155724
    classDef external fill:#fff3cd,stroke:#856404,color:#856404
    classDef infra fill:#e2e3e5,stroke:#6c757d,color:#383d41
```
