ArchGuard — Visual Architecture Linter & Conformance Engine

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

The Problem

Architecture diagrams are dead pixels. Teams draw clean system designs in Figma, Excalidraw, or on whiteboards, drop architecture.png into their README, and celebrate. But as pull requests merge, code quietly drifts: developers import database connections directly inside controllers, bypassing service boundaries.

Existing tools like Tach or import-linter exist, but they require tedious, hand-written 100-line YAML/TOML contracts that almost nobody maintains. The PNG is the only contract the repository actually has.

What ArchGuard Does

ArchGuard turns visual architecture diagrams into executable compiler tests:

1. Multimodal Visual Extraction: Gemma 4 inspects architecture.png and extracts declared dependency arrows into a structured graph schema.
2. Deterministic AST Scanner: A zero-dependency Python standard library scanner parses actual cross-module imports across all files without executing code.
3. Graph Diff Engine: Calculates Undeclared Edges = Actual Imports − Declared Diagram Edges.
4. Actionable Diagnostics: Flags the exact file and line of the violation, exits with code 1 in CI, and outputs an interactive Mermaid drift diagram with red dashed drift arrows.
5. Agent Skill Open Standard: Fully packaged under skills/archguard/SKILL.md compliant with the Agent Skill Open Standard for autonomous coding agents.

How We Built It & Testing

Built with Python 3.11+, Gemma 4 (via Google GenAI SDK), Python stdlib ast, and Mermaid.js. Includes an automated integration test suite with 5 passing tests running in 0.1s, plus a complete offline fallback (--edges) for zero-connectivity environments.