# waterloo-rocketry/universe architecture

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

- Interactive diagram: https://gitdiagram.com/waterloo-rocketry/universe
- Repository: https://github.com/waterloo-rocketry/universe

## Overview

This repository is a Waterloo Rocketry monorepo whose implemented product is tooling for managing area-specific GitHub Actions workflows. The workflow is: a user runs the CLI, which discovers nested workflows, checks their root copies and path scoping, then either validates or refreshes copies. The README also documents GitHub’s use of the root workflow directory. The source excerpt omits parts of the implementation, so the graph shows only relationships supported by the excerpt or README.

Main entry points: [`tools/build_ci/build_ci.py`](https://github.com/waterloo-rocketry/universe/blob/main/tools/build_ci/build_ci.py) (Run workflow), [`areas`](https://github.com/waterloo-rocketry/universe/tree/main/areas) (Area workflows), [`.github/workflows`](https://github.com/waterloo-rocketry/universe/tree/main/.github/workflows) (Root workflows), [`tools/build_ci/__main__.py`](https://github.com/waterloo-rocketry/universe/blob/main/tools/build_ci/__main__.py) (Build CI CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI entry"]
  node_cli["Build CI CLI<br/>[__main__.py]"]
  node_orchestrator["Run workflow<br/>[build_ci.py]"]
end

subgraph group_checks["Discovery and checks"]
  node_area_workflows["Area workflows"]
  node_discovery["Workflow discovery<br/>[build_ci.py]"]
  node_scoping["Path-scope check<br/>[build_ci.py]"]
end

subgraph group_copies["Workflow copies"]
  node_copy_status["Copy status check<br/>[build_ci.py]"]
  node_orphan_check["Orphan copy check<br/>[build_ci.py]"]
  node_copy_writer["Copy refresh<br/>[build_ci.py]"]
  node_root_workflows["Root workflows<br/>[workflows]"]
end

node_user(("Repository maintainer"))
node_github_actions["GitHub Actions"]

node_user -->|"runs"| node_cli
node_cli -->|"calls main"| node_orchestrator
node_orchestrator -->|"discovers"| node_discovery
node_discovery -->|"scans"| node_area_workflows
node_orchestrator -->|"checks copies"| node_copy_status
node_copy_status -->|"compares source"| node_area_workflows
node_copy_status -->|"checks copy"| node_root_workflows
node_orchestrator -->|"checks scope"| node_scoping
node_scoping -->|"reads triggers"| node_area_workflows
node_orchestrator -->|"finds orphans"| node_orphan_check
node_orchestrator -->|"refreshes copies"| node_copy_writer
node_copy_writer -->|"copies from"| node_area_workflows
node_copy_writer -->|"writes to"| node_root_workflows
node_root_workflows -->|"discovered by"| node_github_actions

click node_cli "https://github.com/waterloo-rocketry/universe/blob/main/tools/build_ci/__main__.py"
click node_orchestrator "https://github.com/waterloo-rocketry/universe/blob/main/tools/build_ci/build_ci.py"
click node_area_workflows "https://github.com/waterloo-rocketry/universe/tree/main/areas"
click node_discovery "https://github.com/waterloo-rocketry/universe/blob/main/tools/build_ci/build_ci.py"
click node_scoping "https://github.com/waterloo-rocketry/universe/blob/main/tools/build_ci/build_ci.py"
click node_copy_status "https://github.com/waterloo-rocketry/universe/blob/main/tools/build_ci/build_ci.py"
click node_orphan_check "https://github.com/waterloo-rocketry/universe/blob/main/tools/build_ci/build_ci.py"
click node_copy_writer "https://github.com/waterloo-rocketry/universe/blob/main/tools/build_ci/build_ci.py"
click node_root_workflows "https://github.com/waterloo-rocketry/universe/tree/main/.github/workflows"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_orchestrator toneBlue
class node_area_workflows,node_discovery,node_scoping toneAmber
class node_copy_status,node_orphan_check,node_copy_writer,node_root_workflows toneMint
class node_user,node_github_actions toneIndigo
```

## Components

### CLI entry

- [Build CI CLI](https://github.com/waterloo-rocketry/universe/blob/main/tools/build_ci/__main__.py): `tools/build_ci/__main__.py`
- [Run workflow](https://github.com/waterloo-rocketry/universe/blob/main/tools/build_ci/build_ci.py): `tools/build_ci/build_ci.py`

### Discovery and checks

- [Area workflows](https://github.com/waterloo-rocketry/universe/tree/main/areas): `areas`
- [Workflow discovery](https://github.com/waterloo-rocketry/universe/blob/main/tools/build_ci/build_ci.py): `tools/build_ci/build_ci.py`
- [Path-scope check](https://github.com/waterloo-rocketry/universe/blob/main/tools/build_ci/build_ci.py): `tools/build_ci/build_ci.py`

### Workflow copies

- [Copy status check](https://github.com/waterloo-rocketry/universe/blob/main/tools/build_ci/build_ci.py): `tools/build_ci/build_ci.py`
- [Orphan copy check](https://github.com/waterloo-rocketry/universe/blob/main/tools/build_ci/build_ci.py): `tools/build_ci/build_ci.py`
- [Copy refresh](https://github.com/waterloo-rocketry/universe/blob/main/tools/build_ci/build_ci.py): `tools/build_ci/build_ci.py`
- [Root workflows](https://github.com/waterloo-rocketry/universe/tree/main/.github/workflows): `.github/workflows`

### Other components

- **Repository maintainer**
- **GitHub Actions**

## Connections

- Repository maintainer → Build CI CLI: runs (evidence: `README.md`)
- Build CI CLI → Run workflow: calls main (evidence: `tools/build_ci/__main__.py`)
- Run workflow → Workflow discovery: discovers (evidence: `tools/build_ci/build_ci.py`)
- Workflow discovery → Area workflows: scans (evidence: `tools/build_ci/build_ci.py`)
- Run workflow → Copy status check: checks copies (evidence: `tools/build_ci/build_ci.py`)
- Copy status check → Area workflows: compares source (evidence: `tools/build_ci/build_ci.py`)
- Copy status check → Root workflows: checks copy (evidence: `tools/build_ci/build_ci.py`)
- Run workflow → Path-scope check: checks scope (evidence: `tools/build_ci/build_ci.py`)
- Path-scope check → Area workflows: reads triggers (evidence: `tools/build_ci/build_ci.py`)
- Run workflow → Orphan copy check: finds orphans (evidence: `tools/build_ci/build_ci.py`)
- Run workflow → Copy refresh: refreshes copies (evidence: `tools/build_ci/build_ci.py`)
- Copy refresh → Area workflows: copies from (evidence: `tools/build_ci/build_ci.py`)
- Copy refresh → Root workflows: writes to (evidence: `tools/build_ci/build_ci.py`)
- Root workflows → GitHub Actions: discovered by (evidence: `README.md`)