Skip to content

[architecture] Update architecture diagram - 2026-10-05 #65824

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
Oct 5, 2026
Merged

[architecture] Update architecture diagram - 2026-10-05 #65824

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

> Last updated: 2026-08-17 · Source: Architecture Diagram issue
> Last updated: 2026-10-05 · Source: [Architecture diagram issue](https://github.com/github/gh-aw/issues?q=is%3Aissue+%22Architecture+diagram+%E2%80%94+2026-10-05%22)

## Overview

This diagram shows the package structure and dependencies of the `gh-aw` codebase.
This diagram shows the package structure and dependencies of the `gh-aw` Go codebase. Arrows point from an importing package to an imported package.

```
================================================================================================
ENTRY POINTS
================================================================================================

cmd/gh-aw cmd/gh-aw-wasm cmd/linters
(CLI binary) (WASM target) (analysis binary)
| | |
v v v
------------------------------------------------------------------------------------------------
CORE PACKAGES
------------------------------------------------------------------------------------------------

pkg/cli ────────▶ pkg/workflow ────────▶ pkg/parser
(400 files) (478 files) (markdown/YAML
commands: run, compiles workflow frontmatter parsing)
compile, audit, markdown -> GH Actions |
mcp, trial YAML |
| | | | \ |
| | | | \ v
| | v v v pkg/github / pkg/githubapi
| | pkg/console pkg/agentdrain (GitHub API client,
| | (terminal UI) (agent log mining/ model registry)
| | drain pipeline)
| v
| pkg/linters (custom Go static-analysis rules, used by cmd/linters)
v
pkg/intent, pkg/modelsdev, pkg/actionpins, pkg/importinpututil
(intent detection, model metadata, action-pin resolution, import inputs)

------------------------------------------------------------------------------------------------
UTILITIES
------------------------------------------------------------------------------------------------

pkg/logger pkg/gitutil pkg/fileutil pkg/stringutil pkg/repoutil
pkg/typeutil pkg/sliceutil pkg/setutil pkg/syncutil pkg/jsonutil
pkg/semverutil pkg/ctxutil pkg/envutil pkg/errorutil pkg/tty
pkg/colorwriter pkg/styles pkg/timeutil pkg/stats pkg/testutil
pkg/types pkg/constants

Legend: ──▶ / | = "depends on / imports" (arrow points from dependent to dependency)
```text
┌──────────────────────────────────────────────────────────────────────────────────────────────┐
│ ENTRY POINTS │
│ cmd/gh-aw ─▶ cli cmd/gh-aw-wasm ─▶ workflow, parser cmd/linters ─▶ linters │
│ cmd/gh-aw-security-model (standalone security conformance runner) │
├──────────────────────────────────────────────────────────────────────────────────────────────┤
│ CORE PACKAGES │
│ cli (commands) ─▶ workflow (compiler) ─▶ parser (frontmatter) ─▶ console (terminal UI) │
│ cli ─▶ actionpins (pinning), agentdrain (logs), intent (policy), workqueue (queue) │
│ cli ─▶ github (labels), githubapi (API options), modelsdev (model IDs), scanfindings (scans) │
│ workflow ─▶ actionpins, scanfindings, console parser ─▶ console │
│ parser/workflow ─▶ importinpututil (import inputs) cmd/linters ─▶ linters │
├──────────────────────────────────────────────────────────────────────────────────────────────┤
│ UTILITIES — arrows point from importer to imported package │
│ cli/workflow/parser ─▶ fileutil, gitutil, logger, stringutil, types, constants │
│ parser/workflow ─▶ jsonutil, setutil, sliceutil, syncutil, typeutil │
│ workflow ─▶ repoutil, semverutil, validationerror, ctxutil, tty │
│ cli ─▶ envutil, errorutil, stats, timeutil │
│ console ─▶ colorwriter, logger, stringutil, styles, tty │
│ logger ─▶ colorwriter, styles, timeutil tests: testutil, workflowcontract │
└──────────────────────────────────────────────────────────────────────────────────────────────┘
```

## Package Reference

| Package | Layer | Description |
|---------|-------|--------------|
| cli | Core | Command-line interface implementations (run, compile, audit, mcp, trial, etc.) |
| workflow | Core | Workflow compilation engine — compiles markdown+frontmatter into GitHub Actions YAML |
| parser | Core | Markdown/YAML frontmatter parsing and content extraction |
| console | Core | Terminal UI components and formatted output |
| agentdrain | Core | Agent log mining / drain pipeline |
| github | Core | GitHub API mapping/client helpers |
| githubapi | Core | GitHub API client wrapper |
| linters | Core | Custom Go static-analysis linters (used by cmd/linters) |
| intent | Core | Intent detection helpers |
| modelsdev | Core | AI model metadata/registry |
| actionpins | Core | Action pin resolution (SHA pinning for GitHub Actions) |
| importinpututil | Core | Import input utilities used by parser/workflow |
| logger | Utility | Namespace-based debug logging |
| gitutil | Utility | Git repository helper utilities |
| fileutil | Utility | File path and file operation helpers |
| stringutil | Utility | String manipulation utilities |
| repoutil | Utility | GitHub repository slug/URL utilities |
| typeutil | Utility | Untyped value conversion/extraction helpers |
| sliceutil | Utility | Slice manipulation utilities |
| setutil | Utility | Set data structure utilities |
| syncutil | Utility | Concurrency helpers (e.g., OnceLoader) |
| jsonutil | Utility | JSON helper utilities |
| semverutil | Utility | Semantic versioning primitives |
| ctxutil | Utility | context.Context handling helpers |
| envutil | Utility | Environment variable reading/validation |
| errorutil | Utility | Error classification/inspection helpers |
| tty | Utility | TTY (terminal) detection |
| colorwriter | Utility | Low-level color-aware writer (used by logger) |
| styles | Utility | Centralized terminal style/color definitions |
| timeutil | Utility | Time-related utilities |
| stats | Utility | Numerical statistics utilities |
| testutil | Utility | Shared test helpers |
| types | Utility | Shared type definitions |
| constants | Utility | Shared constant definitions |
|---------|-------|-------------|
| `cmd/gh-aw` | Entry | Main gh aw CLI binary |
| `cmd/gh-aw-wasm` | Entry | WebAssembly compile target |
| `cmd/gh-aw-security-model` | Entry | Standalone workflow security conformance runner |
| `cmd/linters` | Entry | Custom Go linter binary |
| `actionpins` | Core | GitHub Actions reference and SHA pin resolution |
| `agentdrain` | Core | Agent log mining and drain pipeline |
| `cli` | Core | CLI command implementations |
| `console` | Core | Terminal UI rendering and formatting |
| `github` | Core | GitHub label to objective mapping |
| `githubapi` | Core | go-gh API client options |
| `intent` | Core | Intent and governance policy resolution |
| `linters` | Core | Custom Go analysis linters |
| `modelsdev` | Core | Model provider and ID normalization |
| `parser` | Core | Workflow markdown and YAML frontmatter parsing |
| `scanfindings` | Core | Shared scan finding data model |
| `workflow` | Core | GitHub Actions workflow compilation and generation |
| `workqueue` | Core | Work queue transaction and selection model |
| `colorwriter` | Utility | Color aware writer for terminal output |
| `constants` | Utility | Shared constants and defaults |
| `ctxutil` | Utility | Context handling helpers |
| `envutil` | Utility | Environment variable reading and validation |
| `errorutil` | Utility | Error classification helpers |
| `fileutil` | Utility | File path and operation helpers |
| `gitutil` | Utility | Git repository helpers |
| `importinpututil` | Utility | Workflow import input helpers |
| `jsonutil` | Utility | JSON handling helpers |
| `logger` | Utility | Namespace based debug logging |
| `repoutil` | Utility | GitHub repository slug and URL helpers |
| `semverutil` | Utility | Semantic version helpers |
| `setutil` | Utility | Set helpers |
| `sliceutil` | Utility | Slice helpers |
| `stats` | Utility | Numerical statistics helpers |
| `stringutil` | Utility | String helpers |
| `styles` | Utility | Terminal style definitions |
| `syncutil` | Utility | Concurrency helpers |
| `testutil` | Utility | Shared test helpers |
| `timeutil` | Utility | Time helpers |
| `tty` | Utility | Terminal detection |
| `types` | Utility | Shared data types |
| `typeutil` | Utility | Untyped value conversion helpers |
| `validationerror` | Utility | Shared validation error payloads |
| `workflowcontract` | Utility | Workflow contract tests only |
Loading