# pomdap/gb-studio-ci-example architecture

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

- Interactive diagram: https://gitdiagram.com/pomdap/gb-studio-ci-example
- Repository: https://github.com/pomdap/gb-studio-ci-example

## Overview

##### Project type and purpose
- This is not a user-facing application but a CI/CD template repository for GB Studio game projects.
- It provides a set of GitHub Actions workflows and utilities to automate building GB Studio games (ROMs, web builds, Pocket builds) and deploying them to GitHub Releases or itch.io.

##### File structure
- Top-level folders:
– .github/workflows: Contains all the CI workflows (main-branch CI, itchio-release, github-release, plus utility workflows).
– assets/: A library of game assets (avatars, backgrounds, fonts, music, etc.) for use in the GB Studio project.
– plugins/: A place to add GB Studio plugins.
– project/: The actual GB Studio project files (.gbsres resources, .gbsproj project file, sprites, scenes, variables).
- Config files:
– README.md: Explains usage and architecture.
– .gitignore, LICENSE, etc.
- The workflows folder contains three “entrypoint” workflows and three utility workflows:
– ci-main-branch.yml
– ci-itchio-release.yml
– ci-github-release.yml
– utility-validate-target-list.yml
– utility-extract-project-configuration.yml
– utility-build-and-upload-artifact.yml

##### Key insights from the README
- Workflow triggers:
– Push/PR on default branch → main-branch CI
– Tag `v*` → GitHub Release & itch.io Release
- Uses a Docker image (pomdap/gb-studio-ci) to perform builds.
- Utility workflows serve as reusable building blocks for:
validate targets → extract metadata → build + upload artefacts.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Events
    Push_PR["push/PR on default branch"]:::event
    Tag["tag v*"]:::event

    %% Entrypoint Workflows
    subgraph "Entrypoint Workflows"
        ciMain["ci-main-branch.yml"]:::workflow
        ciGitHubRelease["ci-github-release.yml"]:::workflow
        ciItchioRelease["ci-itchio-release.yml"]:::workflow
    end

    %% Utility Workflows
    subgraph "Utility Workflows"
        validate["utility-validate-target-list.yml"]:::workflow
        extract["utility-extract-project-configuration.yml"]:::workflow
        build["utility-build-and-upload-artifact.yml"]:::workflow
    end

    %% Build Environment and Storage
    Docker["Docker Build Environment (gb-studio-ci)"]:::external
    Artifacts["GitHub Actions Artifacts"]:::storage

    %% External Services
    GH_API["GitHub Releases API"]:::external
    ItchIO["itch.io (butler CLI)"]:::external

    %% Project and Assets
    Assets["assets/"]:::folder
    Project["project/"]:::folder

    %% Triggers
    Push_PR --> ciMain
    Tag --> ciGitHubRelease
    Tag --> ciItchioRelease

    %% Entrypoint to Utility
    ciMain --> validate
    ciGitHubRelease --> validate
    ciItchioRelease --> validate

    validate --> extract
    extract --> build

    %% Build and Storage
    build --> Docker
    Assets --> Docker
    Project --> Docker
    Docker --> Artifacts

    %% Deployments
    ciGitHubRelease --> GH_API
    ciItchioRelease --> ItchIO

    %% Click Events
    click ciMain "https://github.com/pomdap/gb-studio-ci-example/blob/main/.github/workflows/ci-main-branch.yml"
    click ciGitHubRelease "https://github.com/pomdap/gb-studio-ci-example/blob/main/.github/workflows/ci-github-release.yml"
    click ciItchioRelease "https://github.com/pomdap/gb-studio-ci-example/blob/main/.github/workflows/ci-itchio-release.yml"
    click validate "https://github.com/pomdap/gb-studio-ci-example/blob/main/.github/workflows/utility-validate-target-list.yml"
    click extract "https://github.com/pomdap/gb-studio-ci-example/blob/main/.github/workflows/utility-extract-project-configuration.yml"
    click build "https://github.com/pomdap/gb-studio-ci-example/blob/main/.github/workflows/utility-build-and-upload-artifact.yml"
    click Assets "https://github.com/pomdap/gb-studio-ci-example/tree/main/assets/"
    click Project "https://github.com/pomdap/gb-studio-ci-example/tree/main/project/"

    %% Styles
    classDef workflow fill:#ADD8E6,stroke:#0000FF,color:#000
    classDef external fill:#FFA500,stroke:#FF8C00,color:#000
    classDef storage fill:#90EE90,stroke:#006400,color:#000
    classDef folder fill:#D3D3D3,stroke:#808080,color:#000
    classDef event fill:#E0FFFF,stroke:#00CED1,color:#000
```
