# jonathanlinat/quake-leveldesign-starterkit architecture

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

- Interactive diagram: https://gitdiagram.com/jonathanlinat/quake-leveldesign-starterkit
- Repository: https://github.com/jonathanlinat/quake-leveldesign-starterkit

## Overview

##### Project type and purpose
- This is a “starter kit” that consolidates multiple specialized tools and resources for creating maps for Quake and similar engines.
- It leverages a wide range of GitHub Actions workflows to continuously build (for multiple platforms), package (pack/unpack artifacts), and release updates to users.

##### File structure
- The top-level directories (especially the .github folder) indicate that the core of this project is its CI/CD pipelines.
- Under .github/actions you have a _shared folder containing common helper actions (e.g., downloading artifacts, setting commit details, installing dependencies like Qt, etc.). These are used by specialized workflows.
- There are separate directories inside .github/actions for “continuous-building”, “continuous-packing”, and “continuous-releasing” – each one having further subfolders for individual tools (e.g., ericw-tools, goldutil, ironwail, etc.). Each tool supports both Linux and Windows builds.
- The workflows in .github/workflows tie the process together by triggering the respective actions.

##### README for additional insights
- The README clearly outlines the suite of applications and tools that QLDSK consolidates. It also provides links to external resources and documentation, emphasizing that the project not only builds the tools but also integrates extra assets (textures, palettes, map sources).
- It explains that this kit aims to simplify the map design process, which in turn requires a well-organized build and release pipeline.

a. Main Components:
- Source Code Repository: Represents the overall repository containing the CI/CD definitions.
- GitHub Actions Workflows: Three main workflows:
▪ Continuous Building – managing compilation and artifact generation for each tool (with subcomponents for Linux and Windows for each tool).
▪ Continuous Packing – handling artifact download and repackaging steps.
▪ Continuous Releasing – packaging the final releases.
- Shared Actions: A collection of reusable actions (found in .github/actions/_shared) that support all the workflows.
- External Components & Tools: Representations of the external level design applications (TrenchBroom, ericw-tools, Ironwail, etc.) and extras (textures, palettes, map sources) that the kit consolidates.
- External Integration Points: Links to the documentation wiki, Discord support channels, and GitHub Releases.

b. Relationships and interactions:
- Initially, code commits trigger specific GitHub workflow files (.github/workflows/*.yml).
- The Continuous Building component uses shared actions for environment setup and artifact management to build binaries on both Linux and Windows.
- The output binary artifacts proceed to the Continuous Packing component, which downloads and processes these artifacts.
- Finally, the Continuous Releasing component collects the packed artifacts and triggers a release, making them available for download.
- External integrations (documentation, Discord) connect users back to supporting information and community channels.

c. Architectural patterns/design principles:
- Modularization: The repository design intentionally modularizes shared actions and separates workflows by function (build, pack, release).
- Platform-Specific Pipelines: Clearly distinct paths for Linux and Windows builds for each supported tool.
- Continuous Integration/Continuous Deployment (CI/CD): Extensive use of GitHub Actions as the orchestration engine to ensure smooth and automated processes.

d. Technologies and frameworks:
- GitHub Actions as the CI/CD automation platform.
- YAML configuration files for defining workflows and actions.
- Build tools/scripts referenced implicitly in the actions (e.g., MSVC setup, Qt installation).
- Integration with external repositories and tools (e.g., external source ports, third-party packages).

##### Instructing the principal software engineer to include these elements
– Repository (and within it, the .github folder)
– Shared Actions (listing some key actions like artifact management, environment setup)
– Continuous Packing and Continuous Releasing
– External tools/resources and integration links.
– Triggering of workflows (commit → workflows)
– Flow of artifacts from building to packing to releasing.
– Connections between the CI/CD pipeline and external delivery endpoints (like GitHub Releases and the documentation wiki).

## Diagram (Mermaid)

```mermaid
flowchart TD
    CC("Code Commit Trigger"):::external
    Repo("Repository (CI/CD Pipeline)"):::repo
    WF("GitHub Actions Workflows (.github/workflows)"):::workflow
    Shared("Shared Actions (.github/actions/_shared)"):::shared

    CC -->|"trigger"| Repo
    Repo -->|"contains"| WF

    %% Continuous Building Subgraph
    subgraph "Continuous Building"
        E("ericw-tools"):::build
        G("goldutil"):::build
        I("ironwail"):::build
        Q("quake-cli-tools"):::build
        T("trenchbroom"):::build
        X("Extras (Resources)"):::build
    end

    %% Build Artifacts node to collect outputs from building stage
    Artifacts("Build Artifacts"):::build

    %% Continuous Packing and Releasing
    Packing("Continuous Packing (.github/actions/continuous-packing)"):::pack
    Releasing("Continuous Releasing (.github/actions/continuous-releasing)"):::release
    External("External Integration Points"):::external

    %% Workflow triggers Continuous Building nodes
    WF -->|"initiates"| E
    WF -->|"initiates"| G
    WF -->|"initiates"| I
    WF -->|"initiates"| Q
    WF -->|"initiates"| T
    WF -->|"initiates"| X

    %% Each building tool produces build artifacts
    E --> Artifacts
    G --> Artifacts
    I --> Artifacts
    Q --> Artifacts
    T --> Artifacts
    X --> Artifacts

    %% Build tools depend on Shared Actions (dashed arrows)
    E -.->|"uses"| Shared
    G -.->|"uses"| Shared
    I -.->|"uses"| Shared
    Q -.->|"uses"| Shared
    T -.->|"uses"| Shared
    X -.->|"uses"| Shared

    %% Flow from build artifacts to packing to releasing and external delivery
    Artifacts -->|"packaged"| Packing
    Packing -->|"released"| Releasing
    Releasing -->|"delivers"| External

    %% Styling classes
    classDef repo fill:#a3d5ff,stroke:#333,stroke-width:2px;
    classDef workflow fill:#ffe599,stroke:#333,stroke-width:2px;
    classDef shared fill:#f9cb9c,stroke:#333,stroke-width:2px;
    classDef build fill:#d9ead3,stroke:#333,stroke-width:2px;
    classDef pack fill:#ead1dc,stroke:#333,stroke-width:2px;
    classDef release fill:#c9daf8,stroke:#333,stroke-width:2px;
    classDef external fill:#d9d2e9,stroke:#333,stroke-width:2px;

    %% Click Events
    click Repo "https://github.com/jonathanlinat/quake-leveldesign-starterkit/blob/main/.github"
    click WF "https://github.com/jonathanlinat/quake-leveldesign-starterkit/tree/main/.github/workflows"
    click Shared "https://github.com/jonathanlinat/quake-leveldesign-starterkit/tree/main/.github/actions/_shared"
    click E "https://github.com/jonathanlinat/quake-leveldesign-starterkit/tree/main/.github/actions/continuous-building/ericw-tools"
    click G "https://github.com/jonathanlinat/quake-leveldesign-starterkit/tree/main/.github/actions/continuous-building/goldutil"
    click I "https://github.com/jonathanlinat/quake-leveldesign-starterkit/tree/main/.github/actions/continuous-building/ironwail"
    click Q "https://github.com/jonathanlinat/quake-leveldesign-starterkit/tree/main/.github/actions/continuous-building/quake-cli-tools"
    click T "https://github.com/jonathanlinat/quake-leveldesign-starterkit/tree/main/.github/actions/continuous-building/trenchbroom"
    click X "https://github.com/jonathanlinat/quake-leveldesign-starterkit/tree/main/.github/actions/continuous-building/extras"
    click Packing "https://github.com/jonathanlinat/quake-leveldesign-starterkit/tree/main/.github/actions/continuous-packing"
    click Releasing "https://github.com/jonathanlinat/quake-leveldesign-starterkit/tree/main/.github/actions/continuous-releasing"
```
