DEV Community

Viswanath Maharam
Viswanath Maharam

Posted on

ArchGuard: The Visual Architecture Linter for Open-Source Repositories

#opensource #hacktoberfest #python #ai

Hacktoberfest: Maintainer Spotlight

ArchGuard — Visual Architecture Conformance Engine

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

Built for Hacktoberfest Hack Day Coimbatore 2026 (hosted by INIT Club × iDEA Club × MLH).

  • GitHub Repository: Quantum_Coders-Hacktober-
  • Team: Quantum_Coders (Raghunathan B K, Kaevin P, Viswanath A G, Sanjay Siddhakumar)

The Problem: Architecture Diagrams Are Dead Pixels

In software engineering, architecture diagrams are drawn once and rarely updated. A team draws a clean 4-tier system in Figma or Excalidraw (API Gateway → Orders → Inventory → Database), exports it as architecture.png, and drops it into the README.md.

Then features ship and pull requests merge.

Inside order_service/checkout.py, an engineer lazily writes:

from database.connection import raw_sql_query
Enter fullscreen mode Exit fullscreen mode

The app still runs. The tests still pass. But the boundary is destroyed—Order Service is now talking directly to Database, bypassing Inventory. Nobody notices until the codebase rots into an undocumented monolith.

Existing tools like Tach and import-linter exist, but they require developers to manually maintain tedious, 100-line YAML/TOML configuration files that almost nobody updates. The PNG diagram is the only contract the repository actually has.

What ArchGuard Does

ArchGuard bridges the visual diagram and executable code.

Instead of letting documentation rot, ArchGuard turns your visual diagram into an automated, executable test in your CI/CD pipeline:

  1. Multimodal Visual Extraction: Google DeepMind's Gemma 4 inspects architecture.png and extracts the declared directed dependency arrows into a structured graph schema.
  2. Deterministic AST Import Scanner: A Python standard library scanner parses actual cross-module imports across all files without executing code or needing virtualenvs.
  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. 
architecture.png
      │
      ▼  Gemma 4 (multimodal visual extraction)
declared edges  (or --edges declared_edges.json offline)

Python source files
      │
      ▼  Python AST scanner (stdlib ast only)
actual imports  (file + line)

actual imports − declared edges
      │
      ▼
drift
      ├── terminal: file + line, exit 1 (drift) or exit 0 (clean)
      ├── drift_report.md   — Mermaid diagram (works offline in VS Code)
      └── drift_report.html — red/green visual summary
Enter fullscreen mode Exit fullscreen mode

How It Works in Action (The Demo)

We built a 4-service mock repository (api_gateway, order_service, inventory_service, database) with a single planted drift on line 2 of checkout.py.

1. Running the Audit 

python -m archguard.cli check \
  --diagram demo_repo/architecture.png \
  --repo ./demo_repo \
  --edges demo_repo/declared_edges.json
Enter fullscreen mode Exit fullscreen mode

Terminal Output (Exit Code 1):

⚠️  Architectural drift detected: 1 undeclared edge(s)
   ! order_service -> database in order_service/checkout.py:2

Reports generated: drift_report.md, drift_report.html
Enter fullscreen mode Exit fullscreen mode

2. The Generated Mermaid Drift Report

ArchGuard dynamically renders the drift in VS Code Markdown Preview:

flowchart TD
    api_gateway --> order_service
    order_service --> inventory_service
    inventory_service --> database
    order_service -.->|DRIFT: line 2| database
    linkStyle 3 stroke:#ff0000,stroke-width:3px,stroke-dasharray: 5 5;

3. The Fix

Comment out line 2 in checkout.py and re-run:

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

Under the Hood & Tech Stack

  • Language: Python 3.11+
  • Vision Model: Google DeepMind Gemma 4 (via Google GenAI SDK)
  • Scanner: Python standard library ast module (zero external dependencies)
  • Visuals: Mermaid.js & Pillow
  • Standards: Agent Skill Open Standard (SKILL.md)
  • Test Suite: 5 automated integration tests running in 0.108s (test_archguard.py)

What We Learned

We learned how to harness multimodal open-weights models like Gemma 4 for structured geometric reasoning rather than conversational text, how to extract cross-module package dependencies deterministically via ASTs, and how to build resilient developer tools with offline fallbacks.

Check out our code and give it a star on GitHub:

👉 github.com/Raghu17012009/Quantum_Coders-Hacktober-

Top comments (0)