How ArchGuard’s Architecture Analyzer Turns Code into AI‑Generated Knowledge

Generative AI‑Driven Knowledge Extraction

ArchGuard, an open‑source architecture governance platform initiated by Thoughtworks, now includes an Architecture Analyzer that consolidates the capabilities of existing analysers (code, Git, OpenAI, Estimate) and adds new functions. By feeding the analyzer with rich inputs such as API call chains, database dependencies, and message‑queue links, AI can generate corresponding knowledge assets instead of merely visualising raw data.

Scenario 1: Domain Knowledge from Models

The core of backend knowledge lies in domain models expressed through DDD, MVC, or Protobuf IDL files. ArchGuard can parse class, method, and field names to produce domain descriptions, for example:

上报播放数据，包括应用、客户端、版本、渠道、位置、查询ID、设备ID、会话ID、总时长、播放时长、数据类型、页面和模块。

These outputs can be combined with user queries to locate matching code.

Scenario 2: Business Knowledge from Call Chains

Previously, ArchGuard generated visual maps (e.g., feat-datamap) that required manual interpretation. Now the analyzer can turn call‑chain data into readable business logic, such as extracting SQL statements and summarising them:

查询未删除的告警组详情，涉及字段包括：ID、名称、接收者、告警间隔、创建时间及更新时间。

Prompt tuning can refine these descriptions further.

ArchGuard Architecture Model

ArchGuard adopts a four‑layer architecture inspired by "Practical Software Architecture":

Conceptual architecture – domain‑specific components

Module architecture – systems, subsystems, modules, layers

Execution architecture – processes, tasks, threads, clients, servers, buffers, message queues

Physical architecture – files, directories, libraries, packages

Additional fields such as outboundService and architectureStyle are under evaluation.

Code‑Review Strategy Example

Using the physical architecture, ArchGuard can suggest review policies based on change frequency, line count, and code complexity.

Data Sources and Evolution

Version 1.0 – basic architecture metrics

Version 1.4 – code‑to‑database call mapping

Version 1.6 – software dependency analysis

Version 2.0.0 – code complexity analysis

Version 2.0.3 – OpenAPI analysis

Version 2.2.2 – Protobuf parsing and service map generation

Adoption by more companies continuously enriches these sources.

How to Use the Architecture Analyzer

Step 1: Run the CLI

Download the latest scanner_cli-2.2.8-all.jar from GitHub or install via shell:

curl -fsSL https://archguard.org/install-cli.sh | bash

Execute the analyzer with:

archguard --language=go --type=architecture --output=json --path=.

For the JAR version, use:

java -jar scanner_cli-2.2.8-all.jar --language=go --type=architecture --output=json --path=.

The command produces a 0_architecture.json file containing the architecture data.

Step 2: Implement the Server

By default, the analyzer expects a POST endpoint at /api/scanner/1/reporting. Upload the JSON with:

curl -X POST -H "Content-Type: application/json" -d @0_architecture.json http://localhost:3000/api/scanner/1/reporting

Implement the corresponding server‑side handler to receive and process the data.

Conclusion

ArchGuard’s Architecture Analyzer demonstrates a practical attempt to let AI understand and generate software architecture knowledge, moving beyond traditional manual documentation toward automated, AI‑enhanced knowledge assets.