Skip to content

[architecture] Update architecture diagram - 2026-04-22 #27792

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 22, 2026
+63 −51
Merged

[architecture] Update architecture diagram - 2026-04-22 #27792

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
114 changes: 63 additions & 51 deletions scratchpad/architecture.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,70 +1,82 @@
# 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)
Copy link

Copilot AI Apr 22, 2026

Choose a reason for hiding this comment

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

The Issue link text indicates a specific issue (#27791), but the URL points to the generic issues list (.../issues) instead of the issue itself. Update the link target to include the issue number (or adjust the link text if the intent is to link to the list).

Suggested change
> Last updated: 2026-04-22 · Source: [Issue #27791](https://github.com/github/gh-aw/issues)
> Last updated: 2026-04-22 · Source: [Issue #27791](https://github.com/github/gh-aw/issues/27791)

Copilot uses AI. Check for mistakes.
Copy link

Copilot AI Apr 22, 2026

Choose a reason for hiding this comment

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

PR description cites the architecture diagram source as workflow run §24769989505, but the document header now cites an issue as the source. Align the header with the stated source (e.g., reference the workflow run, or update the PR description if the issue is the actual source).

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 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) │
Copy link

Copilot AI Apr 22, 2026

Choose a reason for hiding this comment

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

The diagram line listing entry-point imports includes box-border characters (│) inside the parenthesized text, which breaks readability and appears to be an alignment artifact (e.g., parser,│console,constants and parser, │workflow). Remove the stray border characters and reflow spacing so the import lists render cleanly within the diagram.

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

Copilot uses AI. Check for mistakes.
├───────────────────────────▼──────────────────────────────▼──────────────────────────────────┤
│ 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

| 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) |
Loading