Skip to content

[architecture] Update architecture diagram - 2026-05-01 #29488

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
pelikhan merged 1 commit into from
May 1, 2026
+75 −58
Merged

[architecture] Update architecture diagram - 2026-05-01 #29488

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
133 changes: 75 additions & 58 deletions scratchpad/architecture.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,71 +1,88 @@
# Architecture Diagram

> Last updated: 2026-04-30 · Source: [🏗️ Architecture Diagram: Full rebuild — gh-aw package architecture (2026-04-30)](https://github.com/github/gh-aw/issues)
> Last updated: 2026-05-01 · Source: [Architecture Diagram Issue](https://github.com/github/gh-aw/issues)
Copy link

Copilot AI May 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The “Source” link points to the generic issues index rather than the specific architecture diagram issue for this update, which makes it hard to trace the generated diagram back to its source. Please link to the exact issue (or PR/run artifact) that produced this diagram.

Suggested change
> Last updated: 2026-05-01 · Source: [Architecture Diagram Issue](https://github.com/github/gh-aw/issues)
> Last updated: 2026-05-01 · Source: [Architecture Diagram Issue](https://github.com/github/gh-aw/issues/1234)

Copilot uses AI. Check for mistakes.

## Overview

This diagram shows the package structure and dependencies of the `gh-aw` codebase.
This diagram shows the package structure and dependencies of the `gh-aw` codebase, organized in three layers: entry points, core packages, and utility packages.

```
┌────────────────────────────────────────────────────────────────────────────────────────────────┐
│ ENTRY POINTS │
│ ┌─────────────────────────────┐ ┌───────────────────────────────┐ │
│ │ cmd/gh-aw │ │ cmd/gh-aw-wasm │ │
│ │ Main CLI binary / cobra │ │ WebAssembly compilation │ │
│ └──────────────┬──────────────┘ └───────────────────────────────┘ │
│ │ imports: cli, workflow, parser, console, constants │
├──────────────────┼─────────────────────────────────────────────────────────────────────────────┤
│ ▼ CORE PACKAGES │
│ ┌─────────────────────┐ ┌──────────────────────┐ ┌──────────────────────┐ │
│ │ pkg/cli │──▶│ pkg/workflow │──▶│ pkg/parser │ │
│ │ Command impls for │ │ Workflow compilation │ │ Markdown frontmatter│ │
│ │ compile/run/logs │ │ engine (MD→YAML) │ │ parsing & extraction│ │
│ └──────┬───────────────┘ └────────┬─────────────┘ └──────────────────────┘ │
│ │ │ │
│ │ ┌────────▼─────────────┐ ┌──────────────────────┐ │
│ │ │ pkg/actionpins │ │ pkg/agentdrain │ │
│ │ │ Action pin resolution│ │ Agent output drain │ │
│ └──────────────────▶│ (SHA pinning for CI) │ │ (stream multiplexer)│ │
│ └───────────────────────┘ └──────────────────────┘ │
│ │
│ ┌───────────────────────┐ ┌──────────────────────┐ ┌──────────────────────┐ │
│ │ pkg/console │ │ pkg/constants │ │ pkg/stats │ │
│ │ Terminal UI formatting│ │ Shared typed consts │ │ Numerical statistics│ │
│ │ (success/warn/error) │ │ (engines, versions) │ │ for metric tracking │ │
│ └───────────────────────┘ └──────────────────────┘ └──────────────────────┘ │
├─────────────────────────────────────────────────────────────────────────────────────────────────┤
│ UTILITY PACKAGES │
│ ┌────────┐ ┌────────┐ ┌────────┐ ┌──────────┐ ┌─────────┐ ┌──────────┐ ┌────────────┐ │
│ │ logger │ │ tty │ │ styles │ │ fileutil │ │ gitutil │ │stringutil│ │ sliceutil │ │
│ └────────┘ └────────┘ └────────┘ └──────────┘ └─────────┘ └──────────┘ └────────────┘ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ repoutil │ │ envutil │ │ timeutil │ │semverutil│ │ typeutil │ │ types │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
└─────────────────────────────────────────────────────────────────────────────────────────────────┘
┌──────────────────────────────────────────────────────────────────────────────────────────────────┐
│ ENTRY POINTS │
│ │
│ ┌─────────────────────────────────┐ ┌──────────────────────────────────┐ │
│ │ cmd/gh-aw │ │ cmd/gh-aw-wasm │ │
│ │ Main CLI binary (gh extension) │ │ WebAssembly compilation target │ │
│ └────────────┬────────────────────┘ └────────────────────┬─────────────┘ │
│ │ imports cli, workflow, │ │
│ │ parser, console, constants │ │
├───────────────────────┼─────────────────────────────────────────────────┼────────────────────────┤
│ ▼ CORE PACKAGES ▼ │
│ │
│ ┌──────────────────────────┐ ┌──────────────────────────┐ ┌──────────────────────────┐ │
│ │ pkg/cli │──▶│ pkg/workflow │──▶│ pkg/parser │ │
│ │ Command implementations │ │ Workflow compiler engine │ │ Markdown/YAML frontmatter│ │
Copy link

Copilot AI May 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The pkg/parser description in the diagram runs into the right border (frontmatter│), which suggests the text exceeds the box width and breaks the ASCII alignment. Consider shortening/wrapping the text or widening the box so the border characters stay aligned.

Suggested change
│ │ Command implementations │ │ Workflow compiler engine │ │ Markdown/YAML frontmatter│ │
│ │ Command implementations │ │ Workflow compiler engine │ │ Markdown/YAML parsing │ │

Copilot uses AI. Check for mistakes.
│ └───────────┬──────────────┘ └──────────┬───────────────┘ └──────────┬───────────────┘ │
│ │ │ │ │
│ │ ┌──────────────────────┘ │ │
│ │ │ ┌────────────────────────────────────────────┘ │
│ ▼ ▼ ▼ │
│ ┌──────────────────────────┐ ┌──────────────────────────┐ ┌──────────────────────────┐ │
│ │ pkg/console │ │ pkg/agentdrain │ │ pkg/actionpins │ │
│ │ Terminal UI formatting │ │ Agent output streaming │ │ Action pin resolution │ │
│ └───────────┬──────────────┘ └──────────────────────────┘ └──────────────────────────┘ │
│ │ │
│ ┌───────────┴──────────────┐ ┌──────────────────────────┐ │
│ │ pkg/stats │ │ pkg/styles │ │
│ │ Numerical statistics │ │ Terminal color/styles │ │
│ └──────────────────────────┘ └──────────────────────────┘ │
├──────────────────────────────────────────────────────────────────────────────────────────────────┤
│ UTILITY PACKAGES │
│ │
│ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌──────────┐ │
│ │pkg/fileutil│ │pkg/gitutil │ │ pkg/logger │ │pkg/stringut│ │pkg/sliceutil │ pkg/tty │ │
│ │File path & │ │Git repo │ │Namespace │ │String │ │Slice helper│ │TTY detect│ │
│ │operations │ │operations │ │debug logs │ │utilities │ │functions │ │ │ │
│ └────────────┘ └────────────┘ └────────────┘ └────────────┘ └────────────┘ └──────────┘ │
│ │
│ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌──────────┐ │
│ │pkg/constants │pkg/repoutil│ │pkg/semverut│ │ pkg/types │ │pkg/typeutil│ │pkg/envutil │
│ │Shared consts │Repo slug & │ │Semver │ │Shared type │ │Type convert│ │Env var │ │
│ │& type aliases │URL helpers │ │primitives │ │definitions │ │utilities │ │utilities │ │
│ └────────────┘ └────────────┘ └────────────┘ └────────────┘ └────────────┘ └──────────┘ │
Comment on lines +42 to +52
Copy link

Copilot AI May 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In the diagram, the pkg/stringutil label is truncated to pkg/stringut and the row is missing the closing right border character, which breaks the ASCII box formatting and makes the package name inaccurate.

This issue also appears on line 49 of the same file.

Suggested change
│ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌──────────┐ │
│ │pkg/fileutil│ │pkg/gitutil │ │ pkg/logger │ │pkg/stringut│ │pkg/sliceutil │ pkg/tty │ │
│ │File path & │ │Git repo │ │Namespace │ │String │ │Slice helper│ │TTY detect│ │
│ │operations │ │operations │ │debug logs │ │utilities │ │functions │ │ │ │
│ └────────────┘ └────────────┘ └────────────┘ └────────────┘ └────────────┘ └──────────┘ │
│ │
│ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌──────────┐ │
│ │pkg/constants │pkg/repoutil│ │pkg/semverut│ │ pkg/types │ │pkg/typeutil│ │pkg/envutil │
│ │Shared consts │Repo slug & │ │Semver │ │Shared type │ │Type convert│ │Env var │ │
│ │& type aliases │URL helpers │ │primitives │ │definitions │ │utilities │ │utilities │ │
│ └────────────┘ └────────────┘ └────────────┘ └────────────┘ └────────────┘ └──────────┘ │
│ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌─────────────┐ ┌─────────────┐ ┌──────────┐ │
│ │pkg/fileutil│ │pkg/gitutil │ │ pkg/logger │ │pkg/stringutil│ │pkg/sliceutil│ │ pkg/tty │ │
│ │File path & │ │Git repo │ │Namespace │ │String │ │Slice helper │ │TTY detect│ │
│ │operations │ │operations │ │debug logs │ │utilities │ │functions │ │ │ │
│ └────────────┘ └────────────┘ └────────────┘ └─────────────┘ └─────────────┘ └──────────┘ │
│ │
│ ┌──────────────┐ ┌────────────┐ ┌─────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ │
│ │pkg/constants │ │pkg/repoutil│ │pkg/semverutil│ │ pkg/types │ │pkg/typeutil│ │pkg/envutil │ │
│ │Shared consts │ │Repo slug & │ │Semver │ │Shared type │ │Type convert│ │Env var │ │
│ │& type aliases│ │URL helpers │ │primitives │ │definitions │ │utilities │ │utilities │ │
│ └──────────────┘ └────────────┘ └─────────────┘ └────────────┘ └────────────┘ └────────────┘ │

Copilot uses AI. Check for mistakes.
│ │
│ ┌────────────┐ ┌────────────┐ │
│ │pkg/timeutil│ │pkg/testutil│ │
│ │Time helpers│ │Test helpers│ │
│ └────────────┘ └────────────┘ │
└──────────────────────────────────────────────────────────────────────────────────────────────────┘
```

## Package Reference

| Package | Layer | Description |
|---------|-------|-------------|
| cli | Core | Command implementations for compile/run/logs/audit |
| workflow | Core | Workflow compilation engine (Markdown → GitHub Actions YAML) |
| parser | Core | Markdown frontmatter parsing and content extraction |
| actionpins | Core | GitHub Actions pin resolution (SHA pinning for CI) |
| agentdrain | Core | Agent output drain / stream multiplexer |
| console | Core | Terminal UI formatting (success/warn/error messages) |
| constants | Core | Shared typed constants (engines, versions, job names) |
| stats | Core | Numerical statistics for metric tracking |
| logger | Utility | Namespace-based debug logging with zero overhead |
| tty | Utility | TTY (terminal) detection utilities |
| styles | Utility | Centralized style and color definitions for terminal output |
| fileutil | Utility | File path and file operation utilities |
| gitutil | Utility | Git repository utilities |
| stringutil | Utility | String manipulation utilities |
| sliceutil | Utility | Slice operation utilities |
| repoutil | Utility | GitHub repository slug and URL utilities |
| envutil | Utility | Environment variable reading and validation |
| timeutil | Utility | Time utilities |
| semverutil | Utility | Shared semantic versioning primitives |
| typeutil | Utility | General-purpose type conversion utilities |
| types | Utility | Shared type definitions used across packages |
| cmd/gh-aw | Entry Point | Main CLI binary (`gh aw` extension) |
| cmd/gh-aw-wasm | Entry Point | WebAssembly compilation target |
| pkg/cli | Core | Command implementations (compile, run, audit, logs, mcp, etc.) |
| pkg/workflow | Core | Workflow compiler engine — markdown→GitHub Actions YAML |
Copy link

Copilot AI May 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The workflow description uses inconsistent casing/spacing (markdown→GitHub Actions YAML) compared to the rest of the table (e.g., “Markdown …” with spaces). For consistency and readability, consider using “Markdown → GitHub Actions YAML”.

Suggested change
| pkg/workflow | Core | Workflow compiler engine — markdown→GitHub Actions YAML |
| pkg/workflow | Core | Workflow compiler engine — Markdown → GitHub Actions YAML |

Copilot uses AI. Check for mistakes.
| pkg/parser | Core | Markdown frontmatter parsing and content extraction |
| pkg/console | Core | Terminal UI formatting (success/info/warning/error messages) |
| pkg/agentdrain | Core | Agent output streaming and draining |
| pkg/actionpins | Core | GitHub Actions pin resolution (SHA pinning) |
| pkg/stats | Core | Numerical statistics utilities for metric collection |
| pkg/styles | Core | Centralized terminal color/style definitions |
| pkg/constants | Utility | Shared constants and semantic type aliases |
| pkg/envutil | Utility | Environment variable reading and validation |
| pkg/fileutil | Utility | File path and file operation utilities |
| pkg/gitutil | Utility | Git repository operations |
| pkg/logger | Utility | Namespace-based debug logging (zero overhead) |
| pkg/repoutil | Utility | GitHub repository slug and URL helpers |
| pkg/semverutil | Utility | Semantic versioning primitives |
| pkg/sliceutil | Utility | Generic slice helper functions |
| pkg/stringutil | Utility | String manipulation utilities |
| pkg/timeutil | Utility | Time helper utilities |
| pkg/tty | Utility | TTY (terminal) detection |
| pkg/types | Utility | Shared type definitions across packages |
| pkg/typeutil | Utility | General-purpose type conversion utilities |
| pkg/testutil | Utility | Test helper utilities (test-only use) |
Loading