[architecture] Update architecture diagram - 2026-04-18#27001
Conversation
Full rebuild from scratch - analyzed all 24 packages across cmd/ and pkg/, mapping real internal import relationships. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
github-actions
Bot
added
architecture
diagram
documentation
There was a problem hiding this comment.
Pull request overview
Updates scratchpad/architecture.md with a regenerated architecture diagram and refreshed package reference based on current Go import relationships.
Changes:
- Refreshes the ASCII architecture diagram (entry points, core packages, utilities) and removes obsolete
internal/toolsreferences. - Updates the “Last updated” metadata to point to the generating workflow run.
- Revises the package reference table (layers and descriptions), including newly reflected packages like
pkg/stats.
Show a summary per file
| File | Description |
|---|---|
| scratchpad/architecture.md | Regenerates the architecture diagram and updates the package reference table to reflect current imports/dependencies. |
Copilot's findings
Tip
Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comments suppressed due to low confidence (1)
scratchpad/architecture.md:78
- In the package reference table,
pkg/statsis labeled asCore, but the package is a standalone statistics helper (standard-library-only, documented as a utility inpkg/stats/statvar.go/pkg/stats/README.md). Consider changing its layer back toUtilityto keep the table consistent with the actual role of the package.
| pkg/stats | Core | Numerical statistics and metrics collection |
- Files reviewed: 1/1 changed files
- Comments generated: 4
| │ ┌──────────────────────────────────────────┐ ┌────────────────────────────────────┐ │ | ||
| │ │ cmd/gh-aw │ │ cmd/gh-aw-wasm │ │ | ||
| │ │ Main CLI binary │ │ WebAssembly target │ │ | ||
| │ │ imports: cli,console,constants, │ │ imports: parser, workflow │ │ |
There was a problem hiding this comment.
In the diagram’s cmd/gh-aw import list, the commas are missing spaces and the line wrap leaves a trailing comma (cli,console,constants,). This makes the “imports:” list harder to scan and looks like a typo; consider formatting it consistently as cli, console, constants, parser, workflow (either on one line or with a clean wrap without a dangling comma).
| │ │ imports: cli,console,constants, │ │ imports: parser, workflow │ │ | |
| │ │ imports: cli, console, constants, │ │ imports: parser, workflow │ │ |
| │ │ ┌──────────────────────────────────────────┐ │ | ||
| │ └─▶│ pkg/stats │ │ | ||
| │ │ Numerical statistics and metrics │ │ | ||
| │ └──────────────────────────────────────────┘ │ |
There was a problem hiding this comment.
pkg/stats is shown as a CORE package in the diagram, but the package itself is described as a general-purpose statistics utility (see pkg/stats/statvar.go package comment). To avoid misrepresenting layering, consider placing pkg/stats in the UTILITY PACKAGES section (and adjusting arrows/placement accordingly).
This issue also appears on line 78 of the same file.
| │ │ stringutil │ │ sliceutil│ │ typeutil │ │ semverutil │ │ tty │ │ styles │ │ | ||
| │ └────────────┘ └──────────┘ └──────────┘ └────────────┘ └───────┘ └────────┘ │ | ||
| │ ┌──────────┐ ┌──────────┐ │ | ||
| │ │ timeutil │ │ testutil │ (consumed by all core packages above) │ |
There was a problem hiding this comment.
The note (consumed by all core packages above) in the UTILITY PACKAGES section is inaccurate: at least pkg/testutil is only imported from _test.go files (per pkg/testutil/README.md and repo-wide imports). Consider rephrasing this note to avoid implying production dependencies, or exclude test-only packages from the “consumed by” statement.
| │ │ timeutil │ │ testutil │ (consumed by all core packages above) │ | |
| │ │ timeutil │ │ testutil │ (shared utilities used across core packages; includes test-only helpers) │ |
| | pkg/tty | Utility | TTY (terminal) detection utilities | | ||
| | pkg/styles | Utility | Terminal style definitions (no-op for WASM builds) | | ||
| | pkg/timeutil | Utility | Time formatting and duration utilities | | ||
| | pkg/testutil | Utility | Shared test helper utilities | |
There was a problem hiding this comment.
pkg/testutil is described as “Shared test helper utilities”, but the package is explicitly test-only (imported from _test.go files per pkg/testutil/README.md). Consider updating the description to make the test-only constraint explicit (e.g., “test-only helpers” / “imported only by tests”).
| | pkg/testutil | Utility | Shared test helper utilities | | |
| | pkg/testutil | Utility | Test-only helper utilities imported only by `_test.go` files | |
Updates
scratchpad/architecture.mdwith a fresh full-rebuild architecture diagram generated on 2026-04-18.What changed
cmd/andpkg/grepon Go source filesinternal/toolsreferences that no longer exist)pkg/agentdrain,pkg/stats,pkg/actionpinscorrectly placed in core layerinternal/toolsreferences from package tableKey dependency flows captured
cmd/gh-aw→ cli, console, constants, parser, workflowcmd/gh-aw-wasm→ parser, workflowpkg/cli→ workflow, parser, console, agentdrain, stats (+ all utilities)pkg/workflow→ parser, console, actionpins (+ utilities)pkg/parser→ console (+ utilities)pkg/console→ logger, styles, ttyReferences: §24601274706