Skip to content

[architecture] Update architecture diagram - 2026-04-25 #28412

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 25, 2026
+69 −0
Merged

[architecture] Update architecture diagram - 2026-04-25 #28412

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

> Last updated: 2026-04-25 · Source: [Issue #28411](https://github.com/github/gh-aw/issues)
Copy link

Copilot AI Apr 25, 2026

Choose a reason for hiding this comment

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

The "Source: Issue #28411" link currently points to the repository issues index (https://github.com/github/gh-aw/issues) rather than the specific issue. Update the URL to include the issue number (or adjust the link text if you intentionally don’t want to deep-link).

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

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 binary) │ │ (WebAssembly target)│ │
│ └────────┬─────────┘ └──────────┬───────────┘ │
│ │ │ │
├────────────┼──────────────────────────────────────────────────────────┼──────────────────────────┤
│ ▼ CORE PACKAGES ▼ │
│ ┌─────────────────┐ ┌──────────────────┐ ┌────────────────────────┐ │
│ │ cli │───▶│ workflow │───▶│ parser │ │
│ │ CLI commands │ │ Workflow compiler │ │ Markdown/YAML parsing │ │
│ └────────┬────────┘ └────────┬─────────┘ └───────────┬────────────┘ │
│ │ │ │ │
│ │ ┌────────▼─────────┐ ┌───────────▼────────────┐ │
│ └────────────▶│ console │ │ actionpins │ │
│ │ Terminal UI │ │ Action pin resolver │ │
│ └──────────────────┘ └────────────────────────┘ │
│ │
│ ┌──────────────────┐ ┌──────────────────┐ │
│ │ agentdrain │ │ stats │ │
│ │ Agent draining │ │ Numeric stats │ │
│ └──────────────────┘ └──────────────────┘ │
│ │
├──────────────────────────────────────────────────────────────────────────────────────────────────┤
│ UTILITY PACKAGES │
│ ┌─────────┐ ┌─────────┐ ┌──────────┐ ┌──────────┐ ┌───────────┐ ┌──────────┐ ┌──────────┐ │
│ │ logger │ │ styles │ │ tty │ │constants │ │ types │ │ fileutil │ │ gitutil │ │
│ └─────────┘ └─────────┘ └──────────┘ └──────────┘ └───────────┘ └──────────┘ └──────────┘ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
Comment on lines +20 to +39
Copy link

Copilot AI Apr 25, 2026

Choose a reason for hiding this comment

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

The new diagram labels core packages as cli, workflow, etc., but in this repo these live under pkg/ (e.g., pkg/cli, pkg/workflow) and the older sections in this same document use the pkg/... form. To avoid confusion, use consistent package/path naming (either prefix with pkg/ in the diagram/table, or explicitly state that names refer to pkg/<name>).

This issue also appears in the following locations of the same file:

  • line 35
  • line 45
Suggested change
│ │ cli │───▶│ workflow │───▶│ parser │ │
│ │ CLI commands │ │ Workflow compiler │ │ Markdown/YAML parsing │ │
│ └────────┬────────┘ └────────┬─────────┘ └───────────┬────────────┘ │
│ │ │ │ │
│ │ ┌────────▼─────────┐ ┌───────────▼────────────┐ │
│ └────────────▶│ console │ │ actionpins │ │
│ │ Terminal UI │ │ Action pin resolver │ │
│ └──────────────────┘ └────────────────────────┘ │
│ │
│ ┌──────────────────┐ ┌──────────────────┐ │
│ │ agentdrain │ │ stats │ │
│ │ Agent draining │ │ Numeric stats │ │
│ └──────────────────┘ └──────────────────┘ │
│ │
├──────────────────────────────────────────────────────────────────────────────────────────────────┤
│ UTILITY PACKAGES │
│ ┌─────────┐ ┌─────────┐ ┌──────────┐ ┌──────────┐ ┌───────────┐ ┌──────────┐ ┌──────────┐ │
│ │ logger │ │ styles │ │ tty │ │constants │ │ types │ │ fileutil │ │ gitutil │ │
│ └─────────┘ └─────────┘ └──────────┘ └──────────┘ └───────────┘ └──────────┘ └──────────┘ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ pkg/cli │───▶│ pkg/workflow │───▶│ pkg/parser │ │
│ │ CLI commands │ │ Workflow compiler │ │ Markdown/YAML parsing │ │
│ └────────┬────────┘ └────────┬─────────┘ └───────────┬────────────┘ │
│ │ │ │ │
│ │ ┌────────▼─────────┐ ┌───────────▼────────────┐ │
│ └────────────▶│ pkg/console │ │ pkg/actionpins │ │
│ │ Terminal UI │ │ Action pin resolver │ │
│ └──────────────────┘ └────────────────────────┘ │
│ │
│ ┌──────────────────┐ ┌──────────────────┐ │
│ │ pkg/agentdrain │ │ pkg/stats │ │
│ │ Agent draining │ │ Numeric stats │ │
│ └──────────────────┘ └──────────────────┘ │
│ │
├──────────────────────────────────────────────────────────────────────────────────────────────────┤
│ UTILITY PACKAGES │
│ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ │
│ │ pkg/logger │ │ pkg/styles │ │ pkg/tty │ │pkg/constants│ │ pkg/types │ │pkg/fileutil│ │
│ └────────────┘ └────────────┘ └────────────┘ └────────────┘ └────────────┘ └────────────┘ │
│ ┌────────────┐ ┌────────────┐ │

Copilot uses AI. Check for mistakes.
│ │stringutil│ │ sliceutil│ │ repoutil │ │semverutil│ │ envutil │ │ typeutil │ │ timeutil │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
└──────────────────────────────────────────────────────────────────────────────────────────────────┘
```

## Package Reference

| Package | Layer | Description |
|---------|-------|-------------|
| `cli` | Core | Command-line interface implementations |
| `workflow` | Core | Workflow compilation engine (Markdown → GitHub Actions YAML) |
| `parser` | Core | Markdown frontmatter and YAML parsing |
| `console` | Core | Terminal UI rendering and output formatting |
| `actionpins` | Core | GitHub Actions action pin resolution |
| `agentdrain` | Core | Agent output draining utilities |
| `stats` | Core | Numerical statistics utilities |
| `logger` | Utility | Namespace-based debug logging with zero overhead |
| `styles` | Utility | Terminal color and style theme definitions |
| `tty` | Utility | TTY detection utilities |
| `constants` | Utility | Shared constants and semantic type aliases |
| `types` | Utility | Shared type definitions across packages |
| `fileutil` | Utility | File path and file operation utilities |
| `gitutil` | Utility | Git operation utilities |
| `stringutil` | Utility | String manipulation utilities (incl. ANSI stripping) |
| `sliceutil` | Utility | Generic slice operation utilities |
| `repoutil` | Utility | GitHub repository slug/URL utilities |
| `semverutil` | Utility | Semantic versioning primitives |
| `envutil` | Utility | Environment variable reading/validation utilities |
| `typeutil` | Utility | General-purpose type conversion utilities |
| `timeutil` | Utility | Time utilities |
| `testutil` | Utility | Test helpers and shared test utilities |

> Last updated: 2026-04-24 · Source: [🏗️ Architecture Diagram: gh-aw Repository Architecture Diagram (2026-04-24)](https://github.com/github/gh-aw/issues)

## Overview
Comment on lines +70 to 74
Copy link

Copilot AI Apr 25, 2026

Choose a reason for hiding this comment

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

This update appends the new 2026-04-25 diagram above the existing 2026-04-24/2026-04-23 sections, leaving multiple full diagrams and duplicate "Overview"/"Package Reference" sections in the same file. If the intent is to keep only the latest diagram, remove the older dated sections to avoid confusing/contradictory documentation.

See below for a potential fix:

Copilot uses AI. Check for mistakes.
Expand Down
Loading