architecture_viewer

Positioning and Purpose

Architecture Viewer is an incremental architecture acceptance gate after AI code changes, not a full-scale architecture governance platform. The problem it solves is this: an AI coding session changes dozens of files at once, and before merging it is hard to explain exactly what changed architecturally—which widely depended-upon type was deleted, whether there are cross-layer calls, which third-party packages were newly introduced, and who will be affected. At the end of a session, it provides a Before/After architecture comparison and risk grading, and key conclusions need to be verified against the source code.

It does not judge the correctness of business logic, and does not replace testing, type checking, security review, or manual Code Review; it does not perform full-scale architecture governance (when organization-level architecture dashboards, Git history hotspots, or multi-repository aggregation are needed, Sonargraph / CodeScene are recommended); it does not perform broad AI review—it does not review code style, performance, or security vulnerabilities, and only deals with verifiable structural facts: which entities were changed in this round, whether there are cross-layer violations, and who is affected.

Main Capabilities

• Risk discovery (lib/risk-rules.js): cross-layer dependency violations, layer penetration (controller directly connected to storage), type deletion (upgraded or downgraded by number of downstream consumers), newly added external dependencies, high-fan-out changes, orphaned new entities.
• Impact analysis (lib/impact.js): starting from the changed entities, reverse BFS along wiring edges such as import/extends/implements/calls (the reverse edges of base and head are unioned, penetrating the cluster of changed entities), reporting direct/indirect victims outside the cluster boundary. Ownership edges (declared-in) do not participate.
• Cross-layer violation detection depends on "which layer each file belongs to." Since 0.9, layering is inferred by cross-referencing four signals, without the need for handwritten configuration: .av/layers.json user configuration (highest priority); import framework semantics (such as sqlalchemy/gorm/JpaRepository → storage, flask/express/gin/@RestController → controller, @Entity → domain, etc.); directory name/file name conventions (services/, *Controller.java, data_collection/, etc.); structural position fallback (depended on by many modules and itself depends on no others → domain, only outgoing and no incoming → controller). After each session report / extract, the inference results are written to .av/layers.suggested.json (aggregated by directory, including confidence and the basis for the decision; files where the import signal conflicts with the directory name are listed separately). If the review looks fine, you don't need to do anything; if you want to lock it in or correct it, just copy it to .av/layers.json — it always takes priority and will never be overwritten. In an actual test, the layering coverage of a 246-file Python crawler repo increased from 57% to 92%.

How to Use

One-Click Integration with AI Tools (Recommended · Cursor / Claude / DeepSeek)

Automatically detects installed AI programming tools (Cursor, Claude, DeepSeek Harness) and writes to MCP. After that, just tell the AI "check it with the architecture gate when you're done." The Agent should call av_guard; reply with at most a 3-line verdict in the conversation. When git is available, compare against HEAD; a commit means accepting the current structure. No need to take a snapshot first, and no need to open HTML by default. To upgrade: first uninstall (with --npm if needed), then after installing the new version run setup / setup . --project.

CLI Structure Gate (Scripts / CI / No MCP)

There is no need for session start in daily use. For repos without git, av_guard / session guard will automatically add a snapshot. The full Before/After HTML (.av/session-report.html) is an optional deep dive. The exit code is 1 for high risk. session report / check / diff share the same exit codes: 0 pass · 1 architecture gate not passed · 2 parameter configuration error · 3 scan parsing failed · 4 baseline does not exist or is invalid.

PR Auto-Comment (GitHub Actions)

Each PR automatically gets one architecture impact comment; repeated pushes to the same PR only update the original comment, without spamming. The comment content includes: a change count table, a list of added/removed third-party dependencies, 🔴🟠 risk findings, and Top N impact surface (reverse dependencies). For this repo's dogfood workflow, see .github/workflows/architecture-diff.yml.

Quick Start (30 seconds): install once, then just talk. Then tell the AI: "check it with the architecture gate when you're done." Treat the verdict in the conversation (at most 3 lines) as acceptance: green light → git commit (i.e., accept); red light → fix first or explain, and you can use av_explain_finding. Terminology: baseline = the reference object (with git, it is HEAD); verdict = those few lines of lights in the conversation; red light = something may have been broken, green light = structurally there is no problem.

Installation requires Node.js ≥ 18. Supported languages: JavaScript / TypeScript (including Vue, Svelte), Python, Go, Java (tree-sitter parsing, with built-in prebuilds for six platforms, no compilation needed for installation). For integration, please pin arch-viewer@0.12.2-rc.7 or @next, and do not mix it with workspace source code or latest.

CI Drift Gate

CI fails when new modules / services / entry points are not drawn into the six views, so bad diagrams cannot enter the main branch (the granularity is directories and deployment units, not every new file; for file-level changes, see the session report). Related workflows: drift red light .github/workflows/architecture-check.yml; drift + standards + PR comments .github/workflows/architecture-drift.yml (for the Gitee equivalent, see .gitee/workflows/). For how to write rules, see architecture-rules.example.yaml: just copy it to architecture-rules.yaml at the repo root or in the suite directory; when check is not passed --rules, it will automatically read that file.

Local Edition Delivery Boundaries

This round covers structure change reports, a structure overview with locatable source code, and manually verified risk alerts. The six views are downgraded to a compatibility feature and are no longer the default deliverable or selling point. A green light does not guarantee there are no missed reports; incomplete analysis is not a pass. For the support scope, offline mode, and known limitations, see the "Initial Delivery Scope" delivered with the package. AI refinement, extensions, multi-repo, and SaaS are not within the initial quality commitment.

Applicable Scenarios

• Structural acceptance after an AI programming session: check structural changes after modifying codeand risk alerts, submitted after engineer confirmation.
• Architecture impact hints at the PR stage: automatically comment change counts, dependency changes, and risk findings in GitHub PRs.
• Architecture drift interception in CI: fail when new modules / services / entry points are not included in the structural view.

Limitations and Notes

• Does not judge business logic correctness, and does not replace testing, type checking, security review, or manual Code Review.
• Does not perform full architecture governance, and does not perform AI general review.
• A green light does not guarantee there are no missed detections; incomplete analysis is not a pass.
• Positioned as a local pilot candidate, not a stable commercial version; AI refinement, extensions, multi-repo, and SaaS are not within the first-release quality commitment.
• The following figures are validation-period pricing and are not supported by paid data (see COMMERCIAL.md for details).
• CLI telemetry is off by default, enterprise-friendly. When enabled, it only records: event name (CLI command name), duration (milliseconds), exit code, CLI version, operating system type. It does not record: file paths, code content, repository name/URL, user email. Data is stored locally at ~/.config/arch-viewer/telemetry.log (JSONL), and can be viewed or deleted at any time.
• On first login, a 7-day Pro trial is automatically created. The token is stored at ~/.config/arch-viewer/auth.json (permissions 0600), and you remain logged in after restarting the terminal. generate / check / session / --refine (bring your own Key) are Community features and never require login.

Other

• Landing page: local npm run web → http://127.0.0.1:3847/ ; for deployment, see docs/commercial/landing-deploy.md.
• Finished video: docs/demos/demo.mp4. Documentation master index: docs/README.md.
• English README: README.en.md.
• Beginner onboarding: beginner illustrated guide; Quickstart.
• Release records and source commits: docs/commercial/npm-publish.md.
• License: Apache-2.0.