# swarm-game/swarm architecture

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

- Interactive diagram: https://gitdiagram.com/swarm-game/swarm
- Repository: https://github.com/swarm-game/swarm

## Overview

##### Project type and purpose
- This is a full-stack, multi-component Haskell “monorepo” implementing:
– A 2D programming game engine (Swarm)
– A domain-specific language (DSL) for robot programs
– Scenario and topography libraries to describe worlds
– Multiple front-ends (CLI game, TUI, web UI, tournament server)
– Developer tools (doc generator, editor plugins, scripts)
- The README describes Swarm as a 2D resource-gathering game with programmable robots.

##### Break down the file structure into logical components
A. Core libraries (in src/)
- swarm-util: shared utilities (JSON/YAML, graph, lens, etc.)
- swarm-scenario: scenario definitions, parsing, validation
- swarm-topography: world layout, navigation, structure recognition
- swarm-engine: heart of the game loop, robot execution, achievements, scoring
- swarm-lang: DSL for writing robot programs (parser, typechecker, LSP)
- swarm-doc: documentation generator for commands & schema
- swarm-tournament: back-end logic for tournament server (REST API, DB)
- swarm-tui: terminal UI front-end
- swarm-web: web UI rendering & server
B. Executables (in app/)
- app/game: the main Swarm game CLI (invokes engine + UI layer)
- app/tournament: tournament server front end
- app/scene, app/doc: support tools (scene renderer, doc CLI)
C. Static assets and data
- data/: YAML scenario files, JSON schemas, text resources, images
- web/, tournament/web/: static HTML/JS/CSS for front-end UIs
D. Developer tooling
- scripts/: build, test, CI automation, normalization scripts
- editors/: Emacs, Vim, VSCode integrations
- test/: unit, integration, benchmark suites

##### Inter-component relationships
- Core libraries form a layered dependency graph:
swarm-util ← swarm-scenario ← swarm-engine ← app/game
swarm-util ← swarm-scenario ← swarm-lang ← app/game
swarm-util ← swarm-scenario ← swarm-topography ← swarm-engine
…and so on for doc, tournament, tui, web
- Data files (YAML, JSON) are loaded at runtime by swarm-scenario or engine.
- app/game chooses a UI: TUI (via swarm-tui) or web UI (via swarm-web).
- Tournament server (app/tournament) exposes REST endpoints, persists to SQLite.
- Editor plugins and LSP server (in swarm-lang) communicate via Language Server Protocol.

##### Key architectural patterns and principles
- Modular library design: small focused Haskell packages, each with clear responsibilities
- Layered dependencies: util → scenario → language/engine → front ends
- Data-driven world definitions: YAML scenarios + JSON schemas
- Pluggable UIs: swap TUI, web, or headless modes
- CLI + server executables all composed from core libraries

##### Diagramming conventions
- Libraries (e.g., blue rectangles)
- Executables/servers (e.g., green)
- Data stores/files (e.g., yellow)
- Scripts/plugins (e.g., gray)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Core Libraries"
        util["swarm-util"]:::lib
        scenario["swarm-scenario"]:::lib
        topography["swarm-topography"]:::lib
        engine["swarm-engine"]:::lib
        lang["swarm-lang"]:::lib
        doclib["swarm-doc"]:::lib
        tournlib["swarm-tournament"]:::lib
    end

    subgraph "Front-end Libraries"
        tui["swarm-tui"]:::lib
        weblib["swarm-web"]:::lib
    end

    subgraph "Executables/Servers"
        cli["Swarm CLI (app/game)"]:::exec
        tourserv["Tournament Server CLI"]:::exec
        doccli["Doc Generator CLI"]:::exec
        scene["Scene Renderer CLI"]:::exec
    end

    subgraph "Data Sources"
        scen_data["Scenarios (YAML)"]:::data
        schema["JSON Schemas"]:::data
        worlds["Topography Worlds"]:::data
        sqlite[(SQLite DB)]:::db
    end

    subgraph "Static Web Assets"
        web_static["Web UI Assets"]:::assets
        tour_web_static["Tournament Web UI Assets"]:::assets
    end

    subgraph "Developer Tools"
        scripts["scripts/"]:::tool
        editors["editors/"]:::tool
    end

    util --> scenario
    scenario --> engine
    scenario --> lang
    scenario --> topography
    engine --> tui
    engine --> weblib
    lang --> cli
    engine --> cli
    tui --> cli
    weblib --> cli

    tournlib --> tourserv
    tourserv --> sqlite
    weblib --> web_static
    tourserv --> tour_web_static

    scen_data --> scenario
    schema --> scenario
    worlds --> topography

    lang --> editors
    editors --> cli

    click util "https://github.com/swarm-game/swarm/tree/main/src/swarm-util"
    click scenario "https://github.com/swarm-game/swarm/tree/main/src/swarm-scenario"
    click topography "https://github.com/swarm-game/swarm/tree/main/src/swarm-topography"
    click engine "https://github.com/swarm-game/swarm/tree/main/src/swarm-engine"
    click lang "https://github.com/swarm-game/swarm/tree/main/src/swarm-lang"
    click doclib "https://github.com/swarm-game/swarm/tree/main/src/swarm-doc"
    click tournlib "https://github.com/swarm-game/swarm/tree/main/src/swarm-tournament"
    click tui "https://github.com/swarm-game/swarm/tree/main/src/swarm-tui"
    click weblib "https://github.com/swarm-game/swarm/tree/main/src/swarm-web"

    click cli "https://github.com/swarm-game/swarm/blob/main/app/game/Main.hs"
    click tourserv "https://github.com/swarm-game/swarm/blob/main/app/tournament/Main.hs"
    click doccli "https://github.com/swarm-game/swarm/blob/main/app/doc/Main.hs"
    click scene "https://github.com/swarm-game/swarm/blob/main/app/scene/Main.hs"

    click scen_data "https://github.com/swarm-game/swarm/tree/main/data/scenarios/"
    click schema "https://github.com/swarm-game/swarm/tree/main/data/schema/"
    click worlds "https://github.com/swarm-game/swarm/tree/main/data/worlds/"

    click web_static "https://github.com/swarm-game/swarm/blob/main/web/index.html"
    click tour_web_static "https://github.com/swarm-game/swarm/blob/main/tournament/web/index.html"

    click scripts "https://github.com/swarm-game/swarm/tree/main/scripts/"
    click editors "https://github.com/swarm-game/swarm/tree/main/editors/"

    classDef lib fill:#bbdefb,stroke:#2196f3
    classDef exec fill:#c8e6c9,stroke:#4caf50
    classDef data fill:#fff9c4,stroke:#fbc02d
    classDef db fill:#ffe0b2,stroke:#fb8c00,stroke-width:2px
    classDef assets fill:#d1c4e9,stroke:#7e57c2
    classDef tool fill:#e0e0e0,stroke:#9e9e9e
```
