Skip to content

[architecture] Update architecture diagram - 2026-04-03 #24264

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
Apr 3, 2026
+32 −34
Merged

[architecture] Update architecture diagram - 2026-04-03 #24264

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
66 changes: 32 additions & 34 deletions scratchpad/architecture.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,45 +1,41 @@
# Architecture Diagram

> Last updated: 2026-03-31 · Source: [Run §23789178746](https://github.com/github/gh-aw/actions/runs/23789178746)
> Last updated: 2026-04-03 · Source: [Issue #aw_arch01](https://github.com/github/gh-aw/issues)
Copy link

Copilot AI Apr 3, 2026

Choose a reason for hiding this comment

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

The "Source" link text and URL look incorrect: it references "Issue #aw_arch01" but links to the generic issues list (…/gh-aw/issues) rather than a specific issue or the workflow run that generated the diagram (as described in the PR). Please update this to the correct source (e.g., link directly to the generating run or a real issue URL).

Copilot uses AI. Check for mistakes.

## Overview

This diagram shows the package structure and dependencies of the `gh-aw` codebase.

```
┌─────────────────────────────────────────────────────────────────────────────────────────────────┐
│ ENTRY POINTS │
│ ┌──────────────────────────────────────────┐ ┌─────────────────────────────────────────┐ │
│ │ cmd/gh-aw │ │ cmd/gh-aw-wasm │ │
│ │ GitHub CLI extension binary │ │ WebAssembly target │ │
│ └──────┬──────────────────────┬────────────┘ └──────────────────┬──────────────────────┘ │
│ │ │ │ │
├─────────┼──────────────────────┼────────────────────────────────────┼────────────────────────────┤
│ │ CORE PACKAGES │ │ │
│ ▼ ▼ ▼ │
│ ┌──────────────┐ ┌──────────────────────┐ ┌──────────────────────┐ ┌────────────────┐ │
│ │ pkg/cli │──▶ │ pkg/workflow │──▶ │ pkg/parser │ │ pkg/console │ │
│ │ Command │ │ Workflow compilation │ │ Markdown/YAML │ ◀─│ Terminal UI │ │
│ │ impls │ │ engine │ │ parsing │ │ rendering │ │
│ └──────────────┘ └──────────────────────┘ └──────────────────────┘ └────────────────┘ │
│ │
│ ↕ all core packages also use constants, types, and utilities ↕ │
│ │
│ ┌────────────────────────────────────────────────────────────────────────────┐ │
│ │ pkg/constants · pkg/types (shared primitives, no dependencies) │ │
│ └────────────────────────────────────────────────────────────────────────────┘ │
├─────────────────────────────────────────────────────────────────────────────────────────────────┤
│ UTILITIES │
│ ┌──────────┐ ┌─────────────┐ ┌────────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │pkg/logger│ │pkg/stringutil│ │pkg/fileutil│ │pkg/gitutil│ │pkg/styles│ │ pkg/tty │ │
│ └──────────┘ └─────────────┘ └────────────┘ └──────────┘ └──────────┘ └──────────┘ │
│ ┌──────────┐ ┌─────────────┐ ┌────────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │pkg/envutil│ │pkg/repoutil │ │pkg/sliceutil│ │pkg/semver│ │pkg/timeutil│ │pkg/mathutil│ │
│ └──────────┘ └─────────────┘ └────────────┘ └──────────┘ └──────────┘ └──────────┘ │
│ ┌─────────────┐ │
│ │ pkg/testutil│ (test support only) │
│ └─────────────┘ │
└─────────────────────────────────────────────────────────────────────────────────────────────────┘
┌────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ ENTRY POINTS │
│ ┌────────────────────────────┐ ┌────────────────────────┐ ┌────────────────────────────────┐ │
│ │ cmd/gh-aw │ │ cmd/gh-aw-wasm │ │ internal/tools/ (×2) │ │
│ │ GitHub CLI extension bin │ │ WebAssembly target │ │ actions-build, gen-metadata │ │
│ └────────────┬───────────────┘ └────────────┬───────────┘ └──────────────┬─────────────────┘ │
Comment on lines +12 to +15
Copy link

Copilot AI Apr 3, 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 internal tool is abbreviated as "gen-metadata", but elsewhere (and in the package reference table) it's named "generate-action-metadata". Consider using the full tool name here (or a consistently used abbreviation) to avoid confusion when cross-referencing packages.

Suggested change
│ ┌────────────────────────────┐ ┌────────────────────────┐ ┌────────────────────────────────┐ │
│ │ cmd/gh-aw │ │ cmd/gh-aw-wasm │ │ internal/tools/ (×2) │ │
│ │ GitHub CLI extension bin │ │ WebAssembly target │ │ actions-build, gen-metadata │ │
│ └────────────┬───────────────┘ └────────────┬───────────┘ └──────────────┬─────────────────┘ │
│ ┌────────────────────────────┐ ┌────────────────────────┐ ┌──────────────────────────────────────────────┐ │
│ │ cmd/gh-aw │ │ cmd/gh-aw-wasm │ │ internal/tools/ (×2) │ │
│ │ GitHub CLI extension bin │ │ WebAssembly target │ │ actions-build, generate-action-metadata │ │
│ └────────────┬───────────────┘ └────────────┬───────────┘ └─────────────────────┬────────────────────────┘ │

Copilot uses AI. Check for mistakes.
│ │ │ │ │
├───────────────┼─────────────────────────────────┼──────────────────────────────┼───────────────────┤
│ ▼ CORE PACKAGES ▼ ▼ │
│ ┌──────────────────┐ ┌──────────────────────┐ ┌────────────────────┐ ┌───────────────────┐ │
│ │ pkg/cli │──▶│ pkg/workflow │──▶│ pkg/parser │ │ pkg/console │ │
│ │ Command impls │ │ Workflow compilation │ │ MD/YAML parsing │◀──│ Terminal UI │ │
│ └──────────────────┘ └──────────────────────┘ └────────────────────┘ └───────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────────────────────────────┐ │
│ │ pkg/constants · pkg/types (shared primitives, no deps) │ │
│ └──────────────────────────────────────────────────────────────────────────────┘ │
├─────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ UTILITIES │
│ ┌──────────┐ ┌──────────────┐ ┌────────────┐ ┌───────────┐ ┌──────────┐ ┌──────────┐ │
│ │pkg/logger│ │pkg/stringutil│ │pkg/fileutil│ │pkg/gitutil│ │pkg/styles│ │ pkg/tty │ │
│ └──────────┘ └──────────────┘ └────────────┘ └───────────┘ └──────────┘ └──────────┘ │
│ ┌───────────┐ ┌─────────────┐ ┌─────────────┐ ┌──────────────┐ ┌────────────┐ ┌────────────┐ │
│ │pkg/envutil│ │pkg/repoutil │ │pkg/sliceutil│ │pkg/semverutil│ │pkg/timeutil│ │pkg/mathutil│ │
│ └───────────┘ └─────────────┘ └─────────────┘ └──────────────┘ └────────────┘ └────────────┘ │
│ ┌──────────────┐ │
│ │ pkg/testutil │ (test support only) │
│ └──────────────┘ │
└─────────────────────────────────────────────────────────────────────────────────────────────────────┘
```

## Package Reference
Expand All @@ -48,6 +44,8 @@ This diagram shows the package structure and dependencies of the `gh-aw` codebas
|---------|-------|-------------|
| `cmd/gh-aw` | Entry | GitHub CLI extension binary |
| `cmd/gh-aw-wasm` | Entry | WebAssembly target |
| `internal/tools/actions-build` | Internal | Build/validate custom GitHub Actions |
| `internal/tools/generate-action-metadata` | Internal | Generate action.yml and README.md for JS modules |
| `pkg/cli` | Core | Command implementations (cobra commands) |
| `pkg/workflow` | Core | Workflow compilation engine (MD → GitHub Actions YAML) |
| `pkg/parser` | Core | Markdown frontmatter and YAML parsing |
Expand Down
Loading