From d9f7577515cbf9a46e1cad24aa18a1c3197528f4 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Thu, 23 Apr 2026 09:23:24 +0000 Subject: [PATCH] docs: update architecture diagram - 2026-04-23 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- scratchpad/architecture.md | 143 ++++++++++++++++++++----------------- 1 file changed, 77 insertions(+), 66 deletions(-) diff --git a/scratchpad/architecture.md b/scratchpad/architecture.md index ea29f2366af..868697e68a5 100644 --- a/scratchpad/architecture.md +++ b/scratchpad/architecture.md @@ -1,6 +1,6 @@ # Architecture Diagram -> Last updated: 2026-04-22 · Source: [Issue #27791](https://github.com/github/gh-aw/issues) +> Last updated: 2026-04-23 · Source: Issue #28016 (Architecture Diagram) ## Overview @@ -8,75 +8,86 @@ This diagram shows the package structure and dependencies of the `gh-aw` codebas ``` ┌──────────────────────────────────────────────────────────────────────────────────────────────┐ -│ 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 │ │ -│ └─────────┘ └─────────┘ └──────────┘ └──────────┘ └──────────┘ │ -└──────────────────────────────────────────────────────────────────────────────────────────────┘ +│ ENTRY POINTS │ +│ │ +│ ┌─────────────────────┐ ┌─────────────────────┐ │ +│ │ cmd/gh-aw │ │ cmd/gh-aw-wasm │ │ +│ │ (CLI binary) │ │ (WASM target) │ │ +│ └──────────┬──────────┘ └──────────┬──────────┘ │ +│ │ cli, workflow, parser, console │ │ +└────────────────────┼──────────────────────────────────────────┼───────────────────────────────┘ + │ │ +┌────────────────────▼──────────────────────────────────────────▼───────────────────────────────┐ +│ CORE PACKAGES │ +│ │ +│ ┌──────────────────────────────────────────────────────────────────────────────────────┐ │ +│ │ pkg/cli · Command implementations (compile, audit, add, mcp, logs, upgrade, ...) │ │ +│ └──────┬──────────┬──────────────────────────────┬──────────────────────────┬──────────┘ │ +│ │ │ │ │ │ +│ ▼ ▼ ▼ ▼ │ +│ ┌────────────┐ ┌──────────────────────┐ ┌─────────────────┐ ┌──────────────────────┐ │ +│ │pkg/workflow│ │ pkg/agentdrain │ │ pkg/actionpins │ │ pkg/console │ │ +│ │ Compilation│ │ Log analysis/anomaly │ │ Pin resolution │ │ Terminal UI/format │ │ +│ │ engine │ │ detection/clustering │ │ & versioning │ │ │ │ +│ └──────┬─────┘ └──────────────────────┘ └────────┬────────┘ └──────────┬───────────┘ │ +│ │ │ │ │ +│ ▼ │ │ │ +│ ┌─────────────────────────────────────┐ │ │ │ +│ │ pkg/parser │◀────────────┘ │ │ +│ │ Markdown frontmatter parsing & │ │ │ +│ │ YAML content extraction │ │ │ +│ └─────────────────────────────────────┘ │ │ +│ │ │ +└───────────────────────────────────────────────────────────────────────────────┼───────────────┘ + │ +┌───────────────────────────────────────────────────────────────────────────────▼───────────────┐ +│ UTILITY PACKAGES │ +│ │ +│ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ │ +│ │pkg/constants│ │ pkg/types │ │pkg/typeutil│ │pkg/fileutil│ │ pkg/gitutil│ │ +│ │ Typed const │ │ Shared type│ │ Type conv. │ │ File/path │ │ Git repo │ │ +│ │ & flags │ │ definitions│ │ utilities │ │ operations │ │ utilities │ │ +│ └────────────┘ └────────────┘ └────────────┘ └────────────┘ └────────────┘ │ +│ │ +│ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ │ +│ │pkg/stringutil│ │pkg/sliceutil│ │ pkg/logger │ │ pkg/styles │ │ pkg/tty │ │ +│ │ String ops │ │ Generic │ │ Namespace │ │ Terminal │ │ Terminal │ │ +│ │ & ANSI strip│ │ slice utils│ │ debug log │ │ colors │ │ detection │ │ +│ └────────────┘ └────────────┘ └────────────┘ └────────────┘ └────────────┘ │ +│ │ +│ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ │ +│ │pkg/semverutil│ │ pkg/envutil│ │pkg/repoutil│ │ pkg/stats │ │pkg/timeutil│ │ +│ │ Semver ops │ │ Env var │ │ Repo slug │ │ Numerical │ │ Time/dur. │ │ +│ │ & parsing │ │ validation │ │ & URL utils│ │ statistics │ │ formatting │ │ +│ └────────────┘ └────────────┘ └────────────┘ └────────────┘ └────────────┘ │ +└───────────────────────────────────────────────────────────────────────────────────────────────┘ ``` ## Package Reference | Package | Layer | Description | |---------|-------|-------------| -| cmd/gh-aw | Entry | Main CLI binary — imports cli, console, constants, parser, workflow | -| 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/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 | +| cmd/gh-aw | Entry | Main CLI binary | +| cmd/gh-aw-wasm | Entry | WebAssembly compilation target | +| pkg/cli | Core | Command implementations: compile, audit, add, mcp, logs, upgrade, codemod, checks, etc. | +| pkg/workflow | Core | Workflow compilation engine — transforms markdown frontmatter into GitHub Actions YAML | +| pkg/parser | Core | Markdown frontmatter parsing and content extraction | +| pkg/console | Core | Terminal UI components and user-facing formatting utilities | +| pkg/actionpins | Core | GitHub Actions pin resolution and version pinning | +| pkg/agentdrain | Core | Log analysis, anomaly detection, and clustering for workflow audit | +| pkg/constants | Utility | Shared typed constants: versions, URLs, feature flags, engine/job names | +| pkg/types | Utility | Shared type definitions used across packages | | 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) | +| pkg/fileutil | Utility | File path and file operation helpers | +| pkg/gitutil | Utility | Git repository interaction utilities | +| pkg/stringutil | Utility | String manipulation utilities (ANSI stripping, normalization) | +| pkg/sliceutil | Utility | Generic slice operation utilities | +| pkg/logger | Utility | Namespace-based debug logging with zero overhead when disabled | +| pkg/styles | Utility | Centralized terminal style and color definitions (used by console) | +| pkg/tty | Utility | TTY (terminal) detection and width utilities | +| pkg/semverutil | Utility | Semantic versioning primitives | +| pkg/envutil | Utility | Environment variable reading and validation | +| pkg/repoutil | Utility | GitHub repository slug and URL parsing utilities | +| pkg/stats | Utility | Numerical statistics for metric collection (used by agentdrain) | +| pkg/timeutil | Utility | Time formatting and duration utilities | +| pkg/testutil | Utility | Testing helpers (test builds only) |