From d838a583963de0908f09f86f7799cc7f06766b59 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Sun, 19 Apr 2026 09:06:57 +0000 Subject: [PATCH] docs: update architecture diagram scratchpad (2026-04-19) Full rebuild of architecture diagram from commit f7e3992. Clarifies layer boundaries and dependency flow with updated ASCII art. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- scratchpad/architecture.md | 137 ++++++++++++++++++------------------- 1 file changed, 65 insertions(+), 72 deletions(-) diff --git a/scratchpad/architecture.md b/scratchpad/architecture.md index 6e96021780..d50ecd0a07 100644 --- a/scratchpad/architecture.md +++ b/scratchpad/architecture.md @@ -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 │ │ +│ └──────────────────────────────────────────────┘ │ +│ │ │ +├────────────────────────────────┼──────────────────────────────────────────────────────────────────┤ +│ 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/console | Core | Terminal UI rendering and message formatting | +| pkg/agentdrain | Core | Agent log drain and cluster template detection | +| pkg/actionpins | Core | GitHub Actions version pin resolution | +| pkg/logger | Utility | Namespace-based debug logging with zero overhead | +| pkg/styles | Utility | Centralized style and color definitions for terminal output | +| pkg/tty | Utility | TTY (terminal) detection utilities | +| pkg/types | Utility | Shared type definitions used across gh-aw packages | +| pkg/typeutil | Utility | General-purpose type conversion utilities | | pkg/constants | Utility | Shared constants and semantic type aliases | -| pkg/types | Utility | Shared type definitions used across packages | -| pkg/logger | Utility | Namespace-based debug logging with zero overhead when disabled | +| pkg/sliceutil | Utility | Utility functions for working with slices | +| pkg/stats | Utility | Numerical statistics utilities for metric collection | | pkg/fileutil | Utility | File path and file operation utilities | -| pkg/gitutil | Utility | Git repository utility functions | +| pkg/gitutil | Utility | Git and GitHub API utility functions | +| pkg/stringutil | Utility | String manipulation utility functions | | pkg/repoutil | Utility | GitHub repository slug and URL utilities | +| pkg/semverutil | Utility | Semantic versioning primitives | | pkg/envutil | Utility | Environment variable reading and validation utilities | -| pkg/stringutil | Utility | String manipulation utilities including ANSI stripping | -| pkg/sliceutil | Utility | Generic slice operation utilities | -| pkg/typeutil | Utility | General-purpose type conversion utilities | -| pkg/semverutil | Utility | Shared semantic versioning primitives | -| 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/timeutil | Utility | Duration and time formatting utilities | | pkg/testutil | Utility | Shared test helper utilities |