-
Notifications
You must be signed in to change notification settings - Fork 366
[architecture] Update architecture diagram - 2026-04-19 #27163
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.
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
main
from
architecture/update-diagram-2026-04-19-901fa9ee0dcd2af3
Apr 19, 2026
+65
−72
Merged
Changes from all commits
Commits
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -1,66 +1,59 @@ | ||||||
| # Architecture Diagram | ||||||
|
|
||||||
| > Last updated: 2026-04-18 · Source: [Run §24601274706](https://github.com/github/gh-aw/actions/runs/24601274706) | ||||||
| > Last updated: 2026-04-19 · Source: [Run §24625358414](https://github.com/github/gh-aw/actions/runs/24625358414) | ||||||
|
|
||||||
| ## Overview | ||||||
|
|
||||||
| This diagram shows the package structure and dependencies of the `gh-aw` codebase. | ||||||
|
|
||||||
| ``` | ||||||
| ┌────────────────────────────────────────────────────────────────────────────────────────────┐ | ||||||
| │ ENTRY POINTS │ | ||||||
| │ │ | ||||||
| │ ┌──────────────────────────────────────────┐ ┌────────────────────────────────────┐ │ | ||||||
| │ │ cmd/gh-aw │ │ cmd/gh-aw-wasm │ │ | ||||||
| │ │ Main CLI binary │ │ WebAssembly target │ │ | ||||||
| │ │ imports: cli,console,constants, │ │ imports: parser, workflow │ │ | ||||||
| │ │ parser, workflow │ │ │ │ | ||||||
| │ └────────────┬─────────────────────────────┘ └──────────────┬─────────────────────┘ │ | ||||||
| │ │ │ │ | ||||||
| ├─────────────────┼─────────────────────────────────────────────────┼─────────────────────────┤ | ||||||
| │ │ CORE PACKAGES │ │ | ||||||
| │ ▼ ▼ │ | ||||||
| │ ┌──────────────────────────────────┐ ┌────────────────────────────────────────────┐ │ | ||||||
| │ │ pkg/cli │ │ pkg/workflow │ │ | ||||||
| │ │ Command dispatch, flag handling,│────▶│ Workflow compilation and GitHub Actions │ │ | ||||||
| │ │ and CLI command execution │ │ YAML generation │ │ | ||||||
| │ └───┬───────────────────────────┬──┘ └───────────────────┬────────────────┬───────┘ │ | ||||||
| │ │ │ │ │ │ | ||||||
| │ │ │ ▼ ▼ │ | ||||||
| │ │ │ ┌─────────────────┐ ┌──────────────────┐ │ | ||||||
| │ │ │ │ pkg/parser │ │ pkg/actionpins │ │ | ||||||
| │ │ │ │ Markdown/YAML │ │ GitHub Actions │ │ | ||||||
| │ │ │ │ frontmatter & │ │ pin version │ │ | ||||||
| │ │ │ │ schema parsing │ │ resolution │ │ | ||||||
| │ │ │ └────────┬────────┘ └──────────┬───────┘ │ | ||||||
| │ │ ┌──────────────────────┼──────────────────────┘ │ │ | ||||||
| │ │ │ │ │ │ | ||||||
| │ │ ▼ ▼ ▼ │ | ||||||
| │ │ ┌──────────────────────────────────────────────────────────────────────────┐ │ | ||||||
| │ ├─▶│ pkg/console │ │ | ||||||
| │ │ │ Terminal UI: spinners, message formatting, styled output rendering │ │ | ||||||
| │ │ └──────────────────────────────────────────────────────────────────────────┘ │ | ||||||
| │ │ │ | ||||||
| │ │ ┌──────────────────────────────────────────┐ │ | ||||||
| │ ├─▶│ pkg/agentdrain │ │ | ||||||
| │ │ │ Agent log streaming and drain for CI │ │ | ||||||
| │ │ └──────────────────────────────────────────┘ │ | ||||||
| │ │ ┌──────────────────────────────────────────┐ │ | ||||||
| │ └─▶│ pkg/stats │ │ | ||||||
| │ │ Numerical statistics and metrics │ │ | ||||||
| │ └──────────────────────────────────────────┘ │ | ||||||
| ├────────────────────────────────────────────────────────────────────────────────────────────┤ | ||||||
| │ UTILITY PACKAGES │ | ||||||
| │ ┌──────────┐ ┌────────┐ ┌────────┐ ┌──────────┐ ┌─────────┐ ┌──────────┐ ┌──────┐ │ | ||||||
| │ │constants │ │ types │ │ logger │ │ fileutil │ │ gitutil │ │ repoutil │ │envutil│ │ | ||||||
| │ └──────────┘ └────────┘ └────────┘ └──────────┘ └─────────┘ └──────────┘ └──────┘ │ | ||||||
| │ ┌────────────┐ ┌──────────┐ ┌──────────┐ ┌────────────┐ ┌───────┐ ┌────────┐ │ | ||||||
| │ │ stringutil │ │ sliceutil│ │ typeutil │ │ semverutil │ │ tty │ │ styles │ │ | ||||||
| │ └────────────┘ └──────────┘ └──────────┘ └────────────┘ └───────┘ └────────┘ │ | ||||||
| │ ┌──────────┐ ┌──────────┐ │ | ||||||
| │ │ timeutil │ │ testutil │ (consumed by all core packages above) │ | ||||||
| │ └──────────┘ └──────────┘ │ | ||||||
| └────────────────────────────────────────────────────────────────────────────────────────────┘ | ||||||
| ┌──────────────────────────────────────────────────────────────────────────────────────────────────┐ | ||||||
| │ ENTRY POINTS │ | ||||||
| │ │ | ||||||
| │ ┌─────────────────────────┐ ┌───────────────────────────┐ │ | ||||||
| │ │ cmd/gh-aw │ │ cmd/gh-aw-wasm │ │ | ||||||
| │ │ (main CLI binary) │ │ (WebAssembly target) │ │ | ||||||
| │ └─────────────┬───────────┘ └─────────────┬─────────────┘ │ | ||||||
| │ │ │ │ | ||||||
| ├─────────────────────┼───────────────────────────────────────────────┼────────────────────────────┤ | ||||||
| │ CORE PACKAGES ▼ ▼ │ | ||||||
| │ │ | ||||||
| │ ┌─────────────────────────┐ ┌─────────────────────────┐ ┌──────────────────────────┐ │ | ||||||
| │ │ pkg/cli │───▶│ pkg/workflow │───▶│ pkg/parser │ │ | ||||||
| │ │ Command implementations │ │ Workflow compile engine │ │ Markdown/YAML parsing │ │ | ||||||
| │ └──────────┬───────────────┘ └───────────┬─────────────┘ └──────────────────────────┘ │ | ||||||
| │ │ │ │ | ||||||
| │ ┌──────────▼──────────────┐ ┌────────────▼────────────┐ │ | ||||||
| │ │ pkg/agentdrain │ │ pkg/actionpins │ │ | ||||||
| │ │ Agent log drain/cluster│ │ Action pin resolution │ │ | ||||||
| │ └─────────────────────────┘ └─────────────────────────┘ │ | ||||||
| │ │ │ │ | ||||||
| │ └──────────────────┬─────────────┘ │ | ||||||
| │ ▼ │ | ||||||
| │ ┌──────────────────────────────────────────────┐ │ | ||||||
| │ │ pkg/console │ │ | ||||||
| │ │ Terminal UI & message formatting │ │ | ||||||
| │ └──────────────────────────────────────────────┘ │ | ||||||
|
Comment on lines
+26
to
+36
|
||||||
| │ │ │ | ||||||
| ├────────────────────────────────┼──────────────────────────────────────────────────────────────────┤ | ||||||
| │ UTILITY PACKAGES ▼ │ | ||||||
| │ │ | ||||||
| │ Rendering: ┌──────────┐ ┌──────────┐ ┌──────────┐ │ | ||||||
| │ │ logger │ │ styles │ │ tty │ │ | ||||||
| │ └──────────┘ └──────────┘ └──────────┘ │ | ||||||
| │ │ | ||||||
| │ Data: ┌──────────┐ ┌──────────┐ ┌───────────┐ ┌───────────┐ ┌─────────┐ │ | ||||||
| │ │ types │ │ typeutil │ │ constants │ │ sliceutil │ │ stats │ │ | ||||||
| │ └──────────┘ └──────────┘ └───────────┘ └───────────┘ └─────────┘ │ | ||||||
| │ │ | ||||||
| │ Files/Git: ┌──────────┐ ┌──────────┐ ┌───────────┐ ┌───────────┐ ┌───────────┐ │ | ||||||
| │ │ fileutil │ │ gitutil │ │ repoutil │ │ semverutil│ │ stringutil│ │ | ||||||
| │ └──────────┘ └──────────┘ └───────────┘ └───────────┘ └───────────┘ │ | ||||||
| │ │ | ||||||
| │ Others: ┌──────────┐ ┌──────────┐ ┌───────────┐ │ | ||||||
| │ │ envutil │ │ timeutil │ │ testutil │ │ | ||||||
| │ └──────────┘ └──────────┘ └───────────┘ │ | ||||||
| └──────────────────────────────────────────────────────────────────────────────────────────────────┘ | ||||||
| ``` | ||||||
|
|
||||||
| ## Package Reference | ||||||
|
|
@@ -69,25 +62,25 @@ This diagram shows the package structure and dependencies of the `gh-aw` codebas | |||||
| |---------|-------|-------------| | ||||||
| | cmd/gh-aw | Entry | Main CLI binary — imports cli, console, constants, parser, workflow | | ||||||
| | cmd/gh-aw-wasm | Entry | WebAssembly compilation target — imports parser, workflow | | ||||||
| | pkg/cli | Core | Command dispatch, flag handling, and CLI command execution | | ||||||
| | pkg/workflow | Core | Workflow compilation and GitHub Actions YAML generation | | ||||||
| | pkg/parser | Core | Markdown/YAML/frontmatter parsing and schema validation | | ||||||
| | pkg/console | Core | Terminal UI: spinners, message formatting, styled output rendering | | ||||||
| | pkg/agentdrain | Core | Agent log streaming and drain for CI workflows | | ||||||
| | pkg/actionpins | Core | GitHub Actions pin version resolution | | ||||||
| | pkg/stats | Core | Numerical statistics and metrics collection | | ||||||
| | pkg/cli | Core | Command implementations for all gh-aw CLI commands | | ||||||
| | pkg/workflow | Core | Workflow compilation engine (markdown → GitHub Actions YAML) | | ||||||
| | pkg/parser | Core | Markdown frontmatter parsing and content extraction | | ||||||
|
||||||
| | pkg/parser | Core | Markdown frontmatter parsing and content extraction | | |
| | pkg/parser | Core | Markdown frontmatter parsing, content extraction, and YAML parsing/validation helpers | |
Copilot
AI
Apr 19, 2026
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The table claims pkg/logger has “zero overhead”, but constructing a logger and calling Print/Printf still incurs some overhead even when disabled (early return avoids formatting/output, but not the call itself). Consider rewording to something like “minimal overhead when disabled” or restoring the previous phrasing to avoid overstating the guarantee.
Suggested change
| | pkg/logger | Utility | Namespace-based debug logging with zero overhead | | |
| | pkg/logger | Utility | Namespace-based debug logging with minimal overhead when disabled | |
Copilot
AI
Apr 19, 2026
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
pkg/gitutil is described as “Git and GitHub API utility functions”, but the package appears to focus on git CLI helpers plus GitHub-related string/error parsing (no GitHub API client calls). Consider rewording to “Git and GitHub-related utilities” (or similar) to avoid implying it wraps the GitHub API.
Suggested change
| | pkg/gitutil | Utility | Git and GitHub API utility functions | | |
| | pkg/gitutil | Utility | Git and GitHub-related utility functions | |
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The diagram implies
pkg/parseris only reached viapkg/workflow(pkg/cli → pkg/workflow → pkg/parser), butpkg/clidirectly importspkg/parserin many files (e.g.,pkg/cli/commands.go). Consider adding a directpkg/cli → pkg/parseredge (or otherwise adjusting the diagram) so direct dependencies are accurately represented.