Skip to content

[architecture] Update architecture diagram - 2026-04-21 #27521

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 21, 2026
Merged

[architecture] Update architecture diagram - 2026-04-21 #27521

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
52 changes: 23 additions & 29 deletions scratchpad/architecture.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Architecture Diagram

> Last updated: 2026-04-20 · Source: [Issue #27296](https://github.com/github/gh-aw/issues) · [Run §24658621102](https://github.com/github/gh-aw/actions/runs/24658621102)
> Last updated: 2026-04-21 · [Run §24714109908](https://github.com/github/gh-aw/actions/runs/24714109908)

## Overview

Expand All @@ -9,40 +9,34 @@ 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 target) │ │
│ └───┬────────┬─────────────┘ └──────────┬─────────┬────────┘ │
│ │ │ │ │ │
│ └───┬──────────────────────┘ └──────────┬──────────────────┘ │
├──────────────────────────────────────────────────────────────────────────────────────────────────┤
│ ▼ ▼ CORE PACKAGES ▼ ▼ │
│ │
│ ┌──────────────────┐ ┌───────────────────────┐ ┌────────────────────────────┐ │
│ │ pkg/cli │──▶│ pkg/workflow │──▶│ pkg/parser │ │
│ │ CLI commands & │ │ workflow compilation │ │ markdown/YAML frontmatter │ │
│ │ dispatch layer │ │ & Actions generation │ │ parsing & validation │ │
│ └──────┬───────────┘ └──────┬─────────────────┘ └────────────────────────────┘ │
│ │ │ │
│ ▼ 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 │ │
│ │ terminal UI & │ │ log streaming & │ │ action pin │ │
│ │ spinner/render │ │ drain mgmt │ │ resolution │ │
│ └──────────────────┘ └──────────────────┘ └──────────────────┘ │
│ also shared: pkg/stats · pkg/types · pkg/constants │
│ ┌─────────────────┐ ┌──────────────────────┐ ┌──────────────────────┐ ┌─────────────────┐ │
│ │ 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 │
Copy link

Copilot AI Apr 21, 2026

Choose a reason for hiding this comment

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

In the diagram, pkg/semverutil is called out as "also shared" even though it’s already listed in the Utility Packages section below. This makes the diagram’s layering/legend ambiguous (is semverutil Shared or Utility?). Consider choosing one representation (e.g., move semverutil to the shared callout and remove it from the utility list, or keep it in utilities and drop it from the shared callout / reword the callout to clarify it’s a shared utility dependency).

This issue also appears on line 58 of the same file.

Suggested change
│ also shared: pkg/stats · pkg/types · pkg/semverutil │
│ also shared: pkg/stats · pkg/types │

Copilot uses AI. Check for mistakes.
├──────────────────────────────────────────────────────────────────────────────────────────────────┤
│ UTILITY PACKAGES │
│ │
│ ┌────────┐ ┌────────┐ ┌─────┐ ┌──────────┐ ┌─────────┐ ┌──────────┐ ┌──────────┐ │
│ │ logger │ │ styles │ │ tty │ │ fileutil │ │ gitutil │ │ repoutil │ │ sliceutil│ │
│ └────────┘ └────────┘ └─────┘ └──────────┘ └─────────┘ └──────────┘ └──────────┘ │
│ │
│ ┌──────────┐ ┌─────────┐ ┌───────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ typeutil │ │ envutil │ │ semverutil│ │stringutil│ │ timeutil │ │ testutil │ │
│ │ typeutil │ │ envutil │ │ semverutil│ │stringutil│ │ timeutil │ │ testutil*│ │
Copy link

Copilot AI Apr 21, 2026

Choose a reason for hiding this comment

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

The utility package row has inconsistent padding (semverutil and stringutil don’t have the same surrounding spaces as the other boxes), which makes the ASCII grid look slightly misaligned. Consider normalizing spacing (e.g., │ semverutil │ and │ stringutil │) to keep column widths consistent.

Suggested change
│ │ typeutil │ │ envutil │ │ semverutil│ │stringutil│ │ timeutil │ │ testutil*│ │
│ │ typeutil │ │ envutil │ │ semverutil │ │ stringutil │ │ timeutil │ │ testutil*│ │

Copilot uses AI. Check for mistakes.
│ └──────────┘ └─────────┘ └───────────┘ └──────────┘ └──────────┘ └──────────┘ │
│ │
│ (* test-only: pkg/testutil) │
└──────────────────────────────────────────────────────────────────────────────────────────────────┘
```

Expand All @@ -55,22 +49,22 @@ This diagram shows the package structure and dependencies of the `gh-aw` codebas
| 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, spinners, and formatted output |
| pkg/agentdrain | Core | Agent log streaming and drain management |
| 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/stats | Shared | Numerical statistics utilities for metric collection |
| pkg/types | Shared | Shared type definitions used across packages |
| 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 definitions (no-op for Wasm) |
| pkg/styles | Utility | Terminal style and color definitions |
| pkg/tty | Utility | TTY terminal detection utilities |
| pkg/fileutil | Utility | File path and 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/semverutil | Utility | Shared semantic versioning primitives |
| pkg/stringutil | Utility | String manipulation utilities |
| pkg/timeutil | Utility | Time-related utilities |
| pkg/testutil | Utility | Test helper utilities |
| pkg/testutil | Utility | Test helper utilities (test-only) |
Loading