Skip to content

[architecture] Update architecture diagram 2026-05-02 #29713

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

[architecture] Update architecture diagram 2026-05-02 #29713

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

> Last updated: 2026-05-01 · Source: [Architecture Diagram Issue](https://github.com/github/gh-aw/issues)
> Last updated: 2026-05-02 · Source: Issue created by workflow run [§25248432943](https://github.com/github/gh-aw/actions/runs/25248432943)

## Overview

This diagram shows the package structure and dependencies of the `gh-aw` codebase, organized in three layers: entry points, core packages, and utility packages.
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 (gh extension) │ │ WebAssembly compilation target │ │
│ └────────────┬────────────────────┘ └────────────────────┬─────────────┘ │
│ │ imports cli, workflow, │ │
│ │ parser, console, constants │ │
├───────────────────────┼─────────────────────────────────────────────────┼────────────────────────┤
│ ▼ CORE PACKAGES ▼ │
│ │
│ ┌──────────────────────────┐ ┌──────────────────────────┐ ┌──────────────────────────┐ │
│ │ pkg/cli │──▶│ pkg/workflow │──▶│ pkg/parser │ │
│ │ Command implementations │ │ Workflow compiler engine │ │ Markdown/YAML frontmatter│ │
│ └───────────┬──────────────┘ └──────────┬───────────────┘ └──────────┬───────────────┘ │
│ │ │ │ │
│ │ ┌──────────────────────┘ │ │
│ │ │ ┌────────────────────────────────────────────┘ │
│ ▼ ▼ ▼ │
│ ┌──────────────────────────┐ ┌──────────────────────────┐ ┌──────────────────────────┐ │
│ │ pkg/console │ │ pkg/agentdrain │ │ pkg/actionpins │ │
│ │ Terminal UI formatting │ │ Agent output streaming │ │ Action pin resolution │ │
│ └───────────┬──────────────┘ └──────────────────────────┘ └──────────────────────────┘ │
│ │ │
│ ┌───────────┴──────────────┐ ┌──────────────────────────┐ │
│ │ pkg/stats │ │ pkg/styles │ │
│ │ Numerical statistics │ │ Terminal color/styles │ │
│ └──────────────────────────┘ └──────────────────────────┘ │
┌─────────────────────────────────────────────────────────────────────────────────────────────────┐
│ 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 │◀──┘ │
│ │ Markdown/YAML parsing│ │
Comment on lines +20 to +27
│ └──────────┬────────────┘ │
│ │ │
│ ┌─────────────────────────────┐ │ │
│ │ pkg/console │◀──┘ │
│ │ Terminal UI & formatting │ │
│ └──────────────┬──────────────┘ │
│ │ │
│ ┌──────────────┴────────────┐ │
│ │ pkg/agentdrain │ │
│ │ Agent output streaming │ │
│ └───────────────────────────┘ │
├──────────────────────────────────────────────────────────────────────────────────────────────────┤
│ UTILITY PACKAGES │
│ │
│ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌──────────┐ │
│ │pkg/fileutil│ │pkg/gitutil │ │ pkg/logger │ │pkg/stringut│ │pkg/sliceutil │ pkg/tty │ │
│ │File path & │ │Git repo │ │Namespace │ │String │ │Slice helper│ │TTY detect│ │
│ │operations │ │operations │ │debug logs │ │utilities │ │functions │ │ │ │
│ └────────────┘ └────────────┘ └────────────┘ └────────────┘ └────────────┘ └──────────┘ │
│ │
│ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌──────────┐ │
│ │pkg/constants │pkg/repoutil│ │pkg/semverut│ │ pkg/types │ │pkg/typeutil│ │pkg/envutil │
│ │Shared consts │Repo slug & │ │Semver │ │Shared type │ │Type convert│ │Env var │ │
│ │& type aliases │URL helpers │ │primitives │ │definitions │ │utilities │ │utilities │ │
│ └────────────┘ └────────────┘ └────────────┘ └────────────┘ └────────────┘ └──────────┘ │
│ │
│ ┌────────────┐ ┌────────────┐ │
│ │pkg/timeutil│ │pkg/testutil│ │
│ │Time helpers│ │Test helpers│ │
│ └────────────┘ └────────────┘ │
└──────────────────────────────────────────────────────────────────────────────────────────────────┘
│ UTILITY PACKAGES │
│ │
│ ┌────────────┐ ┌────────────┐ ┌─────────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────────┐ │
│ │ pkg/logger │ │pkg/fileutil│ │ pkg/gitutil │ │pkg/types │ │pkg/const-│ │ pkg/stringutil │ │
│ │Debug logger│ │File ops │ │Git utilities │ │ Shared │ │ ants │ │ String helpers │ │
│ └────────────┘ └────────────┘ └─────────────┘ │ types │ │Constants │ └──────────────────┘ │
│ └──────────┘ └──────────┘ │
│ ┌────────────┐ ┌────────────┐ ┌─────────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────────┐ │
│ │pkg/sliceutil│ │pkg/typeutil│ │pkg/repoutil │ │pkg/envutil│ │pkg/styles│ │ pkg/actionpins │ │
│ │Slice helpers│ │Type conv. │ │Repo URL util│ │Env vars │ │UI styles │ │Action pin resolver│ │
│ └────────────┘ └────────────┘ └─────────────┘ └──────────┘ └──────────┘ └──────────────────┘ │
│ │
│ ┌────────────┐ ┌────────────┐ ┌─────────────┐ ┌──────────┐ ┌──────────┐ │
│ │ pkg/tty │ │ pkg/stats │ │pkg/semverutil│ │pkg/time- │ │pkg/test- │ │
│ │TTY detect │ │Statistics │ │Semver primit.│ │ util │ │ util │ │
│ └────────────┘ └────────────┘ └─────────────┘ └──────────┘ └──────────┘ │
└─────────────────────────────────────────────────────────────────────────────────────────────────┘
```

## Package Reference

| Package | Layer | Description |
|---------|-------|-------------|
| cmd/gh-aw | Entry Point | Main CLI binary (`gh aw` extension) |
| cmd/gh-aw-wasm | Entry Point | WebAssembly compilation target |
| pkg/cli | Core | Command implementations (compile, run, audit, logs, mcp, etc.) |
| pkg/workflow | Core | Workflow compiler engine — markdown→GitHub Actions YAML |
| pkg/parser | Core | Markdown frontmatter parsing and content extraction |
| pkg/console | Core | Terminal UI formatting (success/info/warning/error messages) |
| pkg/agentdrain | Core | Agent output streaming and draining |
| pkg/actionpins | Core | GitHub Actions pin resolution (SHA pinning) |
| pkg/stats | Core | Numerical statistics utilities for metric collection |
| pkg/styles | Core | Centralized terminal color/style definitions |
| 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 utilities |
| pkg/gitutil | Utility | Git repository operations |
| pkg/logger | Utility | Namespace-based debug logging (zero overhead) |
| pkg/repoutil | Utility | GitHub repository slug and URL helpers |
| pkg/semverutil | Utility | Semantic versioning primitives |
| pkg/sliceutil | Utility | Generic slice helper functions |
| pkg/stringutil | Utility | String manipulation utilities |
| pkg/timeutil | Utility | Time helper utilities |
| pkg/tty | Utility | TTY (terminal) detection |
| pkg/types | Utility | Shared type definitions across packages |
| pkg/typeutil | Utility | General-purpose type conversion utilities |
| pkg/testutil | Utility | Test helper utilities (test-only use) |
| `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) |
| `pkg/parser` | Core | Markdown frontmatter parsing and content extraction |
| `pkg/console` | Core | Terminal UI components and formatted output |
| `pkg/agentdrain` | Core | Agent output streaming and log draining |
| `pkg/actionpins` | Utility | GitHub Actions pin resolution |
| `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/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/typeutil` | Utility | General-purpose type conversion utilities |
Loading