From a1a7990c44fceece3b6b7c75cbe028c2092dc362 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Wed, 22 Apr 2026 09:18:10 +0000 Subject: [PATCH] docs: update architecture diagram 2026-04-22 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Full rebuild of architecture diagram reflecting actual package dependency graph as of commit 27e6b35. Improved diagram layout shows clear three-layer structure with real dependency arrows between cli → workflow → parser → console chain. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- scratchpad/architecture.md | 114 ++++++++++++++++++++----------------- 1 file changed, 63 insertions(+), 51 deletions(-) diff --git a/scratchpad/architecture.md b/scratchpad/architecture.md index 417e86e6a85..ea29f2366af 100644 --- a/scratchpad/architecture.md +++ b/scratchpad/architecture.md @@ -1,43 +1,55 @@ # Architecture Diagram -> Last updated: 2026-04-21 · [Run §24714109908](https://github.com/github/gh-aw/actions/runs/24714109908) +> Last updated: 2026-04-22 · Source: [Issue #27791](https://github.com/github/gh-aw/issues) ## 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) │ │ -│ └───┬──────────────────────┘ └──────────┬──────────────────┘ │ -├──────────────────────────────────────────────────────────────────────────────────────────────────┤ -│ ▼ CORE PACKAGES ▼ │ -│ ┌──────────────────┐ ┌───────────────────────┐ ┌──────────────────────────────┐ │ -│ │ pkg/cli │──▶│ pkg/workflow │──▶│ pkg/parser │ │ -│ │ CLI commands & │ │ workflow compilation │ │ markdown/YAML frontmatter │ │ -│ │ dispatch layer │ │ & Actions generation │ │ parsing & validation │ │ -│ └──────┬───────────┘ └──────┬─────────────────┘ └──────────────────────────────┘ │ -│ └─────────────┐ ┌─────┘ │ -│ ▼ ▼ │ -│ ┌─────────────────┐ ┌──────────────────────┐ ┌──────────────────────┐ ┌─────────────────┐ │ -│ │ pkg/console │ │ pkg/agentdrain │ │ pkg/actionpins │ │ pkg/constants │ │ -│ │ terminal UI & │ │ Drain log anomaly │ │ action pin │ │ constants & │ │ -│ │ formatted output│ │ detection │ │ resolution │ │ type aliases │ │ -│ └─────────────────┘ └──────────────────────┘ └──────────────────────┘ └─────────────────┘ │ -│ also shared: pkg/stats · pkg/types · pkg/semverutil │ -├──────────────────────────────────────────────────────────────────────────────────────────────────┤ -│ UTILITY PACKAGES │ -│ ┌────────┐ ┌────────┐ ┌─────┐ ┌──────────┐ ┌─────────┐ ┌──────────┐ ┌──────────┐ │ -│ │ logger │ │ styles │ │ tty │ │ fileutil │ │ gitutil │ │ repoutil │ │ sliceutil│ │ -│ └────────┘ └────────┘ └─────┘ └──────────┘ └─────────┘ └──────────┘ └──────────┘ │ -│ ┌──────────┐ ┌─────────┐ ┌───────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ -│ │ typeutil │ │ envutil │ │ semverutil│ │stringutil│ │ timeutil │ │ testutil*│ │ -│ └──────────┘ └─────────┘ └───────────┘ └──────────┘ └──────────┘ └──────────┘ │ -│ (* test-only: pkg/testutil) │ -└──────────────────────────────────────────────────────────────────────────────────────────────────┘ +┌──────────────────────────────────────────────────────────────────────────────────────────────┐ +│ ENTRY POINTS │ +│ ┌──────────────────────────────┐ ┌──────────────────────────────┐ │ +│ │ cmd/gh-aw │ │ cmd/gh-aw-wasm │ │ +│ │ Main CLI binary │ │ WebAssembly / JS target │ │ +│ └──────────────────────┬───────┘ └────────┬─────────────────────┘ │ +│ (cli,workflow,parser,│console,constants) (parser, │workflow) │ +├───────────────────────────▼──────────────────────────────▼──────────────────────────────────┤ +│ CORE PACKAGES │ +│ │ +│ ┌─────────────────────┐ ┌──────────────────────────┐ ┌──────────────────────┐ │ +│ │ pkg/cli │──▶│ pkg/workflow │──▶│ pkg/parser │ │ +│ │ Command routing & │ │ MD→YAML compilation │ │ Markdown/YAML │ │ +│ │ implementations │ │ engine │ │ frontmatter parsing │ │ +│ └──────────┬───────────┘ └──────────┬──────┬──────────┘ └──────────┬───────────┘ │ +│ │ │ │ │ │ +│ │ │ └──▶ pkg/actionpins │ │ +│ │ │ (Action SHA pinning) │ │ +│ ▼ ▼ ▼ │ +│ ┌──────────────────────────────────────────────────────────────────┐ │ +│ │ pkg/console │ │ +│ │ Terminal UI rendering & message formatting │ │ +│ └──────────────┬──────────────────┬───────────────────┬────────────┘ │ +│ ▼ ▼ ▼ │ +│ pkg/styles pkg/tty pkg/logger │ +│ (color/style (TTY detection) (debug logging) │ +│ definitions) │ +│ │ +│ ┌─────────────────────┐ ┌──────────────────────────┐ ┌──────────────────────┐ │ +│ │ pkg/agentdrain │ │ pkg/constants │ │ pkg/types │ │ +│ │ Agent output │ │ Semantic type aliases │ │ Shared type defs │ │ +│ │ drain & streaming │ │ & shared constants │ │ │ │ +│ └─────────────────────┘ └──────────────────────────┘ └──────────────────────┘ │ +├──────────────────────────────────────────────────────────────────────────────────────────────┤ +│ UTILITY PACKAGES │ +│ │ +│ ┌─────────┐ ┌─────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ +│ │fileutil │ │ gitutil │ │stringutil│ │ repoutil │ │semverutil│ │sliceutil │ │ +│ └─────────┘ └─────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ +│ ┌─────────┐ ┌─────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ +│ │ typeutil│ │ envutil │ │ timeutil │ │ stats │ │ testutil │ │ +│ └─────────┘ └─────────┘ └──────────┘ └──────────┘ └──────────┘ │ +└──────────────────────────────────────────────────────────────────────────────────────────────┘ ``` ## Package Reference @@ -45,26 +57,26 @@ This diagram shows the package structure and dependencies of the `gh-aw` codebas | Package | Layer | Description | |---------|-------|-------------| | 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 | CLI command implementations and dispatch layer | -| pkg/workflow | Core | Workflow compilation and GitHub Actions YAML generation | -| pkg/parser | Core | Markdown/YAML frontmatter parsing and validation | -| pkg/console | Core | Terminal UI rendering and formatted output | -| pkg/agentdrain | Core | Drain log-based anomaly detection for agentic pipeline runs | -| pkg/actionpins | Core | GitHub Actions pin resolution | -| pkg/constants | Shared | Shared constants and semantic type aliases | -| pkg/types | Shared | Shared type definitions used across packages | -| pkg/stats | Shared | Numerical statistics utilities for metric collection | -| pkg/semverutil | Utility | Semantic versioning primitives | -| pkg/logger | Utility | Namespace-based debug logging with zero overhead | -| pkg/styles | Utility | Terminal style and color definitions | -| pkg/tty | Utility | TTY terminal detection utilities | -| pkg/fileutil | Utility | File path and file operation utilities | +| cmd/gh-aw-wasm | Entry | WebAssembly / JS compilation target — imports parser, workflow | +| pkg/cli | Core | Command routing & implementations | +| pkg/workflow | Core | MD→YAML workflow compilation engine | +| pkg/parser | Core | Markdown/YAML frontmatter parsing & extraction | +| pkg/console | Core | Terminal UI rendering & message formatting | +| pkg/actionpins | Core | GitHub Actions pin resolution (SHA pinning) | +| pkg/agentdrain | Core | Agent output drain & streaming | +| pkg/constants | Core | Semantic type aliases & shared constants | +| pkg/types | Core | Shared type definitions | +| pkg/fileutil | Utility | File path & file operation utilities | | pkg/gitutil | Utility | Git operation utilities | -| pkg/repoutil | Utility | GitHub repository slug and URL utilities | -| pkg/sliceutil | Utility | Generic slice utilities | -| pkg/typeutil | Utility | General-purpose type conversion utilities | -| pkg/envutil | Utility | Environment variable reading and validation | | pkg/stringutil | Utility | String manipulation utilities | +| pkg/logger | Utility | Namespace-based debug logging with zero overhead | +| pkg/repoutil | Utility | GitHub repository slug & URL utilities | +| pkg/semverutil | Utility | Semantic versioning primitives | +| pkg/sliceutil | Utility | Slice operation utilities | +| pkg/styles | Utility | Centralized style & color definitions for terminal | +| pkg/tty | Utility | TTY (terminal) detection utilities | +| pkg/typeutil | Utility | General-purpose type conversion utilities | +| pkg/envutil | Utility | Environment variable reading & validation utilities | | pkg/timeutil | Utility | Time-related utilities | +| pkg/stats | Utility | Numerical statistics utilities for metric collection | | pkg/testutil | Utility | Test helper utilities (test-only) |