Skip to content

[architecture] Update architecture diagram - 2026-04-23 #28017

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.

Sign up for GitHub

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 from
Apr 23, 2026
Merged

[architecture] Update architecture diagram - 2026-04-23 #28017

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
143 changes: 77 additions & 66 deletions scratchpad/architecture.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,82 +1,93 @@
# 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)
Copy link

Copilot AI Apr 23, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The updated source reference is no longer a clickable link. Consider linking Issue #28016 directly (e.g. to /issues/28016) to match how issue references are typically navigated from docs.

Suggested change
> Last updated: 2026-04-23 · Source: Issue #28016 (Architecture Diagram)
> Last updated: 2026-04-23 · Source: [Issue #28016](/issues/28016) (Architecture Diagram)

Copilot uses AI. Check for mistakes.

## 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 / 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 │ │
Copy link

Copilot AI Apr 23, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The entry-point dependency list under cmd/gh-aw omits pkg/constants, and cmd/gh-aw-wasm's imports aren’t shown at all. In the code, cmd/gh-aw/main.go imports pkg/constants, and cmd/gh-aw-wasm/main.go imports pkg/parser and pkg/workflow. Please adjust the entry-point dependency line(s) so the diagram reflects these actual imports.

Suggested change
│ │ cli, workflow, parser, console │ │
│ │ cli, workflow, parser, console, constants │ parser, workflow │

Copilot uses AI. Check for mistakes.
└────────────────────┼──────────────────────────────────────────┼───────────────────────────────┘
│ │
┌────────────────────▼──────────────────────────────────────────▼───────────────────────────────┐
│ 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 │◀────────────┘ │ │
Comment on lines +32 to +36
Copy link

Copilot AI Apr 23, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The dependency arrow into pkg/parser appears to indicate pkg/actionpins depends on pkg/parser, but in the codebase pkg/workflow imports both pkg/parser and pkg/actionpins (e.g. pkg/workflow/compiler_types.go), while pkg/actionpins does not import pkg/parser (see pkg/actionpins/actionpins.go). Please update the diagram arrows to reflect the actual import direction (workflow → parser, workflow → actionpins) and remove the implied actionpins → parser dependency.

Suggested change
│ └──────┬─────┘ └──────────────────────┘ └────────┬────────┘ └──────────┬───────────┘ │
│ │ │ │ │
│ ▼ │ │ │
│ ┌─────────────────────────────────────┐ │ │ │
│ │ pkg/parser │◀────────────┘ │ │
│ └──────┬─────┘ └──────────────────────┘ └────────▲────────┘ └──────────┬───────────┘ │
│ │ │ │ │
│ ├───────────────────────────────────────────┘ │ │
│ ▼ │ │
│ ┌─────────────────────────────────────┐ │ │
│ │ pkg/parser │ │ │

Copilot uses AI. Check for mistakes.
│ │ 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) |
Loading