🏗️ Architecture Diagram:gh-aw package structure (2026-05-25)

[github-actions]

Architecture Diagram

Full rebuild — no prior cache found.

┌──────────────────────────────────────────────────────────────────────────────────────────┐
│                                    ENTRY POINTS                                          │
│                                                                                          │
│        ┌─────────────────┐                       ┌─────────────────────┐                │
│        │   cmd/gh-aw     │                       │  cmd/gh-aw-wasm     │                │
│        │  (main binary)  │                       │  (WebAssembly target│                │
│        └────────┬────────┘                       └──────────┬──────────┘                │
│                 │                                            │                           │
├─────────────────┼────────────────────────────────────────────┼───────────────────────────┤
│                 ▼              CORE PACKAGES                 ▼                           │
│                                                                                          │
│   ┌─────────────────────────┐      ┌───────────────────────────────────────┐            │
│   │         cli             │      │              workflow                  │            │
│   │  Command implementations│─────▶│  Compilation engine (MD → YAML)       │            │
│   │  compile, run, audit,   │      │  Frontmatter eval, engine dispatch,   │            │
│   │  mcp, logs, campaigns   │      │  lock file generation                 │            │
│   └──────────┬──────────────┘      └──────────────────┬──────────────────-─┘            │
│              │                            │            │                                 │
│              │              ┌─────────────┘            │                                 │
│              ▼              ▼                          ▼                                 │
│   ┌──────────────────┐  ┌──────────────────────────────────────┐                        │
│   │     console      │  │               parser                 │                        │
│   │  Terminal UI     │  │  Markdown frontmatter + YAML parsing │                        │
│   │  rendering &     │  │  Schema validation, expression       │                        │
│   │  msg formatting  │  │  extraction                          │                        │
│   └────────┬─────────┘  └──────────────────────────────────────┘                        │
│            │                                                                             │
│            ▼                                                                             │
│   ┌──────────────────┐   ┌──────────────────────────────────┐                           │
│   │     types        │◀──│           constants               │                           │
│   │  Shared domain   │   │  Semantic type aliases, engine/   │                           │
│   │  type definitions│   │  job names, feature flags         │                           │
│   └──────────────────┘   └──────────────────────────────────┘                           │
│                                                                                          │
├──────────────────────────────── DOMAIN PACKAGES ─────────────────────────────────────── ┤
│                                                                                          │
│   ┌──────────────────┐  ┌──────────────────┐  ┌────────────┐  ┌────────────┐           │
│   │   actionpins     │  │   agentdrain     │  │  linters   │  │   stats    │           │
│   │  Action pin      │  │  Agent lifecycle │  │  Custom Go │  │  Numerical │           │
│   │  resolution      │  │  & drain helpers │  │  analyzers │  │  statistics│           │
│   └──────────────────┘  └──────────────────┘  └────────────┘  └────────────┘           │
│                                                                                          │
├──────────────────────────────── UTILITY PACKAGES ────────────────────────────────────── ┤
│                                                                                          │
│  ┌──────────┐ ┌──────────┐ ┌────────────┐ ┌─────────┐ ┌─────────┐ ┌──────────┐       │
│  │ fileutil │ │ gitutil  │ │ stringutil │ │  logger │ │ envutil │ │ errorutil│       │
│  └──────────┘ └──────────┘ └────────────┘ └─────────┘ └─────────┘ └──────────┘       │
│                                                                                          │
│  ┌──────────┐ ┌──────────┐ ┌────────────┐ ┌─────────┐ ┌─────────┐ ┌──────────┐       │
│  │ jsonutil │ │ repoutil │ │ semverutil │ │sliceutil│ │ syncutil│ │ timeutil │       │
│  └──────────┘ └──────────┘ └────────────┘ └─────────┘ └─────────┘ └──────────┘       │
│                                                                                          │
│  ┌──────────┐ ┌──────────┐ ┌────────────┐ ┌──────────────────────────────────┐        │
│  │   tty    │ │ typeutil │ │   styles   │ │  testutil  (test helpers only)   │        │
│  └──────────┘ └──────────┘ └────────────┘ └──────────────────────────────────┘        │
└──────────────────────────────────────────────────────────────────────────────────────────┘

Summary

Full rebuild (no prior cache). Analyzed 26 packages across pkg/ and cmd/.

The codebase follows a clean four-layer architecture:

1. Entry points (cmd/gh-aw, cmd/gh-aw-wasm) wire up CLI commands and serve as binary targets.
2. Core packages (cli, workflow, parser, console, types, constants) implement the primary compilation pipeline from markdown to GitHub Actions YAML.
3. Domain packages (actionpins, agentdrain, linters, stats) provide feature-specific services used by core packages.
4. Utility packages (13 leaf packages) provide small, focused primitives with no internal cross-dependencies.

Package Reference

Package	Layer	Description
cli	Core	Command implementations (compile, run, audit, mcp, logs, campaigns)
workflow	Core	Workflow compilation engine — markdown → GitHub Actions YAML
parser	Core	Markdown frontmatter & YAML parsing, schema validation, expression extraction
console	Core	Terminal UI rendering and message formatting
types	Core	Shared domain type definitions
constants	Core	Semantic type aliases, engine/job names, feature flags
actionpins	Domain	GitHub Actions pin resolution and version management
agentdrain	Domain	Agent drain/lifecycle utilities
linters	Domain	Custom Go analysis linters (vet-style checks)
stats	Domain	Numerical statistics for metric collection
fileutil	Util	File path and file operation helpers
gitutil	Util	Git repository helpers
stringutil	Util	String utilities (ANSI stripping, transforms)
logger	Util	Namespace-based debug logging with zero overhead
envutil	Util	Environment variable reading and validation
errorutil	Util	Error classification and inspection helpers
jsonutil	Util	JSON serialization helpers
repoutil	Util	GitHub repository slug and URL utilities
semverutil	Util	Semantic versioning primitives
sliceutil	Util	Generic slice operation helpers
syncutil	Util	Concurrency synchronization helpers
timeutil	Util	Time formatting helpers
tty	Util	TTY detection utilities
typeutil	Util	General-purpose type conversion utilities
styles	Util	Centralized terminal color/style definitions
testutil	Util	Test helpers (test-only, not used in production)

References: §26394747908

Generated by 🏗️ Architecture Diagram Generator · sonnet46 2.2M · ◷

• expires on Jun 1, 2026, 10:11 AM UTC