Skip to content

[architecture] Update architecture diagram - 2026-05-04 #30117

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
May 4, 2026
+72 −59
Merged

[architecture] Update architecture diagram - 2026-05-04 #30117

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
131 changes: 72 additions & 59 deletions scratchpad/architecture.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,78 +1,91 @@
# Architecture Diagram

> Last updated: 2026-05-03 · Source: [Issue created by workflow run §25275056556](https://github.com/github/gh-aw/actions/runs/25275056556)
> Last updated: 2026-05-04 · Source: [Issue created by workflow run §25311481444](https://github.com/github/gh-aw/actions/runs/25311481444)

## Overview

This diagram shows the package structure and dependencies of the `gh-aw` codebase. The project is organized into three layers: entry points (CLI binaries), core packages (main business logic), and utility packages (shared helpers).

```
┌─────────────────────────────────────────────────────────────────────────────────────────────────┐
│ ENTRY POINTS │
│ ┌──────────────────────────┐ ┌──────────────────────────┐ │
│ │ cmd/gh-aw │ │ cmd/gh-aw-wasm │ │
│ │ (main CLI binary) │ │ (WebAssembly target) │ │
│ └──────┬───────────────────┘ └────────────┬─────────────┘ │
│ │ │ │
├─────────────────┼──────────────────────────────────────────────┼─────────────────────────────────┤
│ ▼ CORE PACKAGES ▼ │
│ ┌────────────────────────┐ ┌─────────────────────────────────┐ │
│ │ pkg/cli │────────▶│ pkg/workflow │ │
│ │ Command implementations│ │ Workflow compilation engine │ │
│ └────┬──────────┬────────┘ └──────────────┬──────────────────┘ │
│ │ │ │ │
│ │ └───────────────────┐ ┌─────────┘ │
│ │ ▼ ▼ │
│ │ ┌─────────────────────┐ ┌──────────────────────┐ │
│ │ │ pkg/parser │ │ pkg/actionpins │ │
│ │ │ MD/YAML parsing │ │ Pin resolution & │ │
│ │ └──────────┬───────────┘ │ version pinning │ │
│ │ │ └──────────────────────┘ │
│ ▼ ▼ │
│ ┌──────────────────┐ ┌─────────────────────────────────────────────────────────────┐ │
│ │ pkg/agentdrain │ │ pkg/console │ │
│ │ Log streaming │ │ Terminal UI rendering and message formatting │ │
│ └──────────────────┘ │ (used by cli, workflow, parser, actionpins) │ │
│ └─────────────────────────────────────────────────────────────┘ │
├─────────────────────────────────────────────────────────────────────────────────────────────────┤
│ UTILITY PACKAGES │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ logger │ │constants │ │ types │ │ typeutil │ │stringutil│ │sliceutil │ │ fileutil │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ gitutil │ │ styles │ │ tty │ │semverutil│ │ repoutil │ │ envutil │ │ timeutil │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
│ ┌──────────┐ ┌──────────┐ │
│ │ stats │ │ testutil │ │
│ └──────────┘ └──────────┘ │
└─────────────────────────────────────────────────────────────────────────────────────────────────┘
┌──────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ ENTRY POINTS │
│ │
│ ┌─────────────────────────┐ ┌───────────────────────────┐ │
│ │ cmd/gh-aw │ │ cmd/gh-aw-wasm │ │
│ │ Main CLI binary │ │ WebAssembly build target │ │
│ └────────────┬────────────┘ └─────────────┬─────────────┘ │
│ │ imports: cli, workflow, parser, console, │ │
│ │ constants │ │
├───────────────────────┼───────────────────────────────────────────────┼──────────────────────────────┤
│ ▼ CORE PACKAGES ▼ │
│ │
│ ┌──────────────────────────────┐ ┌───────────────────────────┐ ┌──────────────────────────┐ │
│ │ pkg/cli │──▶│ pkg/workflow │──▶│ pkg/parser │ │
│ │ Command implementations │ │ Workflow compilation │ │ Markdown frontmatter │ │
│ │ (compile, run, audit, logs, │ │ engine (Markdown → │ │ parsing & content │ │
│ │ mcp, stats) │ │ GitHub Actions YAML) │ │ extraction │ │
│ └──────────────────────────────┘ └───────────────────────────┘ └──────────────────────────┘ │
│ │ also uses: │ also uses: │ │
│ │ parser, agentdrain, │ actionpins, console │ │
│ │ stats, repoutil │ │ │
│ │ │ │ │
│ ┌────────▼──────────┐ ┌────────────────────▼────────────────────────────────▼──────────────────┐ │
│ │ pkg/agentdrain │ │ pkg/console │ │
│ │ Agent log drain │ │ Terminal UI formatting, rendering, and style management │ │
│ └───────────────────┘ └────────────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌───────────────────────────────────────────────────────────────────────────────────────────────┐ │
│ │ pkg/actionpins — GitHub Actions pin resolution pkg/stats — Metrics & statistics │ │
│ └───────────────────────────────────────────────────────────────────────────────────────────────┘ │
Comment on lines +37 to +39
│ │
├──────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ UTILITY PACKAGES │
│ │
│ ┌───────────────┐ ┌──────────────┐ ┌──────────────┐ ┌────────────┐ ┌──────────────────────┐ │
│ │ pkg/constants │ │ pkg/types │ │ pkg/logger │ │pkg/styles │ │ pkg/stringutil │ │
│ │ Shared consts │ │ Shared type │ │ Debug logging│ │Terminal │ │ String utilities │ │
│ │ & type aliases│ │ definitions │ │ (zero-cost) │ │colors/styles│ │ │ │
│ └───────────────┘ └──────────────┘ └──────────────┘ └────────────┘ └──────────────────────┘ │
│ │
│ ┌───────────────┐ ┌──────────────┐ ┌──────────────┐ ┌────────────┐ ┌──────────────────────┐ │
│ │ pkg/fileutil │ │ pkg/gitutil │ │ pkg/repoutil │ │pkg/envutil │ │ pkg/sliceutil │ │
│ │ File path & │ │ Git repo │ │ GitHub repo │ │ Env var │ │ Generic slice │ │
│ │ I/O utilities │ │ utilities │ │ slug/URL util │ │ utilities │ │ utilities │ │
│ └───────────────┘ └──────────────┘ └──────────────┘ └────────────┘ └──────────────────────┘ │
│ │
│ ┌───────────────┐ ┌──────────────┐ ┌──────────────┐ ┌────────────┐ ┌──────────────────────┐ │
│ │ pkg/typeutil │ │pkg/semverutil│ │ pkg/timeutil │ │ pkg/tty │ │ pkg/testutil │ │
│ │ Type conversion│ │ Semantic │ │ Time helpers │ │TTY detect │ │ Test helpers │ │
│ │ utilities │ │ versioning │ │ │ │ │ │ (test builds only) │ │
│ └───────────────┘ └──────────────┘ └──────────────┘ └────────────┘ └──────────────────────┘ │
Comment on lines +56 to +60
└──────────────────────────────────────────────────────────────────────────────────────────────────────┘
```

## Package Reference

| Package | Layer | Description |
|---------|-------|-------------|
| `cmd/gh-aw` | Entry Point | Main CLI binary |
| `cmd/gh-aw-wasm` | Entry Point | WebAssembly compilation target |
| `pkg/cli` | Core | Command implementations for all `gh aw` subcommands |
| `pkg/workflow` | Core | Workflow compilation engine (markdown → GitHub Actions YAML) |
| `cmd/gh-aw-wasm` | Entry Point | WebAssembly build target |
| `pkg/cli` | Core | Command implementations (compile, run, audit, logs, mcp, stats) |
| `pkg/workflow` | Core | Workflow compilation engine (Markdown → GitHub Actions YAML) |
| `pkg/parser` | Core | Markdown frontmatter parsing and content extraction |
| `pkg/console` | Core | Terminal UI components and formatted output (widely used) |
| `pkg/agentdrain` | Core | Agent output streaming and log draining |
| `pkg/actionpins` | Core | GitHub Actions pin resolution and version management |
| `pkg/console` | Core | Terminal UI formatting, rendering, and style management |
| `pkg/agentdrain` | Core | Agent log draining and streaming |
| `pkg/actionpins` | Core | GitHub Actions pin resolution |
| `pkg/stats` | Core | Numerical statistics for metric collection |
| `pkg/constants` | Utility | Shared constants and semantic type aliases |
| `pkg/envutil` | Utility | Environment variable reading and validation |
| `pkg/fileutil` | Utility | File path and file operation helpers |
| `pkg/types` | Utility | Shared type definitions |
| `pkg/logger` | Utility | Namespace-based debug logging (zero overhead) |
| `pkg/styles` | Utility | Centralized terminal style/color definitions |
| `pkg/stringutil` | Utility | String utility functions |
| `pkg/fileutil` | Utility | File path and I/O operation utilities |
| `pkg/gitutil` | Utility | Git repository utilities |
| `pkg/logger` | Utility | Namespace-based debug logging with zero overhead |
| `pkg/repoutil` | Utility | GitHub repository slug and URL utilities |
| `pkg/semverutil` | Utility | Semantic versioning primitives |
| `pkg/sliceutil` | Utility | Generic slice helper functions |
| `pkg/stats` | Utility | Numerical statistics for metric collection |
| `pkg/stringutil` | Utility | String manipulation helpers |
| `pkg/styles` | Utility | Centralized terminal color/style definitions |
| `pkg/testutil` | Utility | Shared test helpers |
| `pkg/timeutil` | Utility | Time formatting and duration utilities |
| `pkg/tty` | Utility | TTY (terminal) detection utilities |
| `pkg/types` | Utility | Shared type definitions used across packages |
| `pkg/repoutil` | Utility | GitHub repository slug/URL utilities |
| `pkg/envutil` | Utility | Environment variable reading/validation |
| `pkg/sliceutil` | Utility | Generic slice utilities |
| `pkg/typeutil` | Utility | General-purpose type conversion utilities |
| `pkg/semverutil` | Utility | Semantic versioning primitives |
| `pkg/timeutil` | Utility | Time helper utilities |
| `pkg/tty` | Utility | TTY detection utilities |
| `pkg/testutil` | Utility | Test helper utilities (test builds only) |
Loading