[scanner] No architecture or code layout guide for atomic_image_builder.py's 5132-line single-file App class

[danathar-atomic-hive]

Finding

atomic_image_builder.py is a 5,132-line single-file application without a package or module split. Its App class alone spans lines 1208 to 5087 (~3,900 lines) and defines 132 methods encompassing menu handlers, system scan logic, workflow and recipe patchers, GitHub API integration, and config serialization.

While CONTRIBUTING.md explains testing, linting, and PR submission, and MAINTAINER.md covers releases and audit semantics, nowhere in the repository is there an orientation or architecture map of the codebase itself. A contributor or maintainer seeking to modify a specific menu flow or patching routine must read through the entire file or guess search terms across 132 methods.

Steps to Reproduce / Evidence

1. Search for architecture documentation across repo docs:

grep -rli "architecture" README.md CONTRIBUTING.md maintainer_docs/ docs/

Yields 0 results.

2. Inspect atomic_image_builder.py structure:

• Top-level data models and constants (BaseImage, Config, ACTION_PINS, etc.)
• Helper functions (workflow patching: patch_workflow_signing_steps, ensure_workflow_job_env_entries, patch_container_workflow, patch_bluebuild_workflow, etc.)
• Gum CLI wrapper (Gum)
• Monolithic App class spanning ~3,900 lines with 132 methods.

Recommendation

Add an 'Architecture' or 'Code Layout' section to CONTRIBUTING.md (or create docs/architecture.md) mapping the major components of atomic_image_builder.py:

• Top-level models and configuration
• Workflow/template patcher helper functions
• Gum TUI wrapper abstractions
• App class method groupings (menu screens, navigation flows, git/gh operations, config persistence)

---

Filed by scanner agent (ACMM L4 — issues-only mode)

🐝 Hive Agent: scanner | Instance: hive-wild-mole | SHA: fee4d89

— hive: agent=scanner backend=agy model=gemini-3.7-flash-high effort=low agy=1.1.19