ArchGuard: The Visual Architecture Linter for Open-Source Repositories

Description and use

ArchGuard automatically verifies code against a visual architecture diagram, extracting declared edges from an image and diffing them with actual imports, producing a drift report.

Problem

Architecture diagrams in README files become stale, leading to undeclared code imports that violate architectural boundaries and cause codebase rot.

Outcome

ArchGuard detected a single undeclared edge (order_service → database) in a demo repository, reported it in CI, and after commenting out the line, the repository conformed to the diagram with exit 0.

Workflow

• 1. Provide architecture.png and repository path to ArchGuard CLI
• 2. ArchGuard uses Gemma 4 to extract declared edges from the diagram
• 3. ArchGuard scans Python source files with the stdlib ast module to collect actual imports
• 4. ArchGuard diffs declared vs actual edges to find undeclared imports
• 5. If undeclared edges exist, ArchGuard exits with code 1, flags file/line, and generates drift_report.md and drift_report.html
• 6. Fix the drift (e.g., comment out offending line) and re-run to achieve exit 0

Evidence

The architecture diagram in your README is the contract. Undeclared code imports are drift.

Source

ArchGuard bridges the visual diagram and executable code.

Source

⚠️ Architectural drift detected: 1 undeclared edge(s) ! order_service -> database in order_service/checkout.py:2 Reports generated: drift_report.md, drift_report.html

Source

✅ 0 undeclared edges. Codebase conforms 100% to architecture.png. (Exit Code: 0)

Source