ArchGuard: architecture governance you run against a real codebase

ArchGuard reads architecture at container, component and code level

ArchGuard describes itself as an architecture governance tool for distributed systems, and the scope is broader than a dependency graph. It analyses containers, components and code, it looks at database relationships, and it checks systems against rules and fitness functions rather than only drawing pictures of them. The visualization side is built on the C4 model. The context level gives you an API service map, where producers can be Java, Kotlin or C# and consumers can be TypeScript or JavaScript, Kotlin or Java. The container level adds a database map that understands MyBatis, JDBI and JPA, so you can see which service reaches which table rather than only which service calls which service. Component analysis covers the internals, and the code level goes down to modules, packages, classes and methods. Code analysis also includes CLOCO complexity reporting, SCA analysis, OpenAPI analysis and architecture analysis. The people this is built for are architects and developers who want to see the shape of a running estate and then act on it.

Four entry points, from embedded library to self hosted backend

You can meet ArchGuard in several places, and the choice determines how much you own. There is an ArchGuard library published in Maven Central that you can integrate with your own backend, which is the option for teams that already have a platform and want the analysis inside it. There is a Scanner CLI in the scanner_cli module that scans a codebase and uploads the result either to your backend or to the ArchGuard backend. There is a Gradle plugin for scanning in CI/CD, which is how you make architecture rules a build failure rather than a slide. And there is ArchGuard Web in the server module, the backend that exposes a RESTful API for the frontend. The repository also lists subprojects that are separate: the ArchGuard Frontend, Chapi, which does the source code analysis, and ArchGuard Co-mate, an AI-powered architecture copilot for design and governance. For a first evaluation, the scanner plus a self hosted backend is the path with the least hidden state.

Language support is uneven across the analysis levels

Parsing a language is not the same as understanding its HTTP surface, and the project publishes a table that makes the difference explicit. Languages are parsed by Chapi. Syntax parsing is available across the whole list, from Java and Kotlin through Python, Go, TypeScript, C, C#, Scala and C++. HTTP API declaration support is a different story: it is listed as available for Java, Kotlin, C# and TypeScript, while Python, Go, C, Scala and C++ are marked as newer support for that feature. Function call analysis is available for Java, Go, Kotlin and TypeScript, with Python flagged as newer and no entry for C, C# or Scala. Package or architecture level extraction is available for Java, Kotlin, TypeScript, C# and Scala, with C marked as newer and nothing listed for Python or Go. Real world validation is listed only for Java and TypeScript. The practical consequence is that a polyglot estate gets partial analysis, and the gaps are concentrated in the newer integrations rather than in the JVM core the project was built around.

Architecture metrics carry their own completion status

The metrics section is one of the more useful parts of the documentation because it states where the project is in its own roadmap. Under volume it lists oversize components. Under coupling it lists hub components, too deep calls and circular dependencies. Cohesion covers shotgun modification, redundancy covers redundant elements and overgeneralization, and quality covers test protection. The line that qualifies all of this is the one that marks the single-application metrics as done and the distributed set as still in progress. That is an unusual admission to find in a feature list, and it tells you something concrete: for a monolith you get the full metric set, while in a distributed estate the metrics are incomplete. There is also advanced analysis for instability in modules and, between containers, precise testing and change analysis. The rule based side, meanwhile, is described as plug-in rule customization covering code smell, test code smell, SQL smell, API smell and documentation smell.

The scanner uploads findings over plain HTTP

Communication between the scanner and the backend is a simple REST style protocol, and the documentation lists the endpoints directly:

POST http://127.0.0.1:8765/scanner/:systemId/reporting/class-items

POST http://127.0.0.1:8765/scanner/:systemId/reporting/openapi

POST http://127.0.0.1:8765/scanner/:systemId/reporting/container-services

POST http://127.0.0.1:8765/scanner/:systemId/reporting/datamap-relations

Each call carries a system identifier and one kind of finding: class level items, OpenAPI definitions, container services or database map relations. Because the protocol is plain HTTP, you can point the scanner at your own backend instead of the hosted one, and the documentation points at the ArchGuardHttpClient class in the scanner_cli module as the place to look for the details. A custom backend example is given in the form of the co-unit project, written in Rust, which shows that the backend contract is not tied to the Kotlin server shipped here. That is the interesting part of the design. The scanner produces findings, and whether you store them in the bundled server, in your own service or somewhere else is your choice.

The Docker Compose stack runs frontend, backend, MySQL and InfluxDB

Running ArchGuard locally means running four containers on a shared network named dependence_network. The compose file is short enough to read as a map of the system:

version: '3.8'
services:
  archguard-frontend:
    image: "archguard/archguard-frontend:latest"
    container_name: archguard-frontend
    depends_on:
      - archguard-backend
    ports:
      - "11080:80"
    networks:
      - dependence_network

The backend listens on 11081 mapped to 8080 and depends on a healthy MySQL 8.3 instance on 13306, and there is an InfluxDB 1.8 container on 8086 for the time series side. The backend container mounts the local Maven and Gradle caches and a local project repository into the image, which is what lets the scanner resolve dependencies during a scan. The backend also has a health check that curls the actuator health endpoint. The image itself is built from openjdk:12-jdk-alpine, and it is worth reading the Dockerfile because it shows that the scanning capability ships inside the server image:

FROM openjdk:12-jdk-alpine

RUN apk add --no-cache tzdata git curl && \
	cp /usr/share/zoneinfo/Asia/Shanghai /etc/localtime && \
	echo "Asia/Shanghai" > /etc/timezone && \
	apk del tzdata

The same Dockerfile copies the server jar and the scanner jar into the image, and copies the analyser modules, one per language and feature, into a dependencies directory. The container runs as a non-root spring user, and the scanner version is pinned through a build argument. That arrangement is unusual for a governance tool and it is convenient: one image carries both the web application and the code analysis engine.

Design time modelling and scan time facts are two different tools

ArchGuard covers the design state as well as the development state. In the design state it offers an architecture design, analysis and governance DSL, and points at Feakin and its fklang language as a separate project for that purpose. The difference in approach is the point worth understanding. A DSL describes the architecture you intend, so violations are found when the description and the code disagree. Scanning works the other way round: it reads the code and tells you what the architecture actually is, then compares that against rules you configure. If your team wants a reviewed architecture model, the Feakin route is the relevant one. If you want to know that a circular dependency appeared in a pull request, the scanner plus the Gradle plugin is the relevant one. The two can be used separately. Neither replaces the other, and the documentation does not present them as one workflow.

Recent releases trail the commit history, and some features are still proposals

The repository is not archived and the last push was on 2026-10-02, so work continues on the master branch. The tagged releases are older than that: v2.3.0 on 2025-02-19, v2.2.9 on 2025-02-18 and v2.2.8 on 2024-11-15. If you consume the released artifacts rather than building from source, that gap between the tags and the branch is the thing to plan around. Two more entries in the documentation are explicitly unfinished. The running state section lists APM as a to-do, and the MCP server section is titled a new feature proposal to expose the architecture linter as a Model Context Protocol server, so AI assistants could query the linting rules. The repository tree does contain an mcp-server directory, which suggests work has started, but the documentation presents it as a proposal rather than a shipped feature. The project is MIT licensed, which means no commercial restriction on running it in a company.

Editorial conclusion

ArchGuard suits teams that already run a JVM-heavy service estate and want architecture rules such as circular dependency or SQL smell checks enforced from a Gradle plugin, since the scanners and the backend both live in one MIT licensed repository. It is the wrong tool for a small codebase with no container boundaries, and for teams that want design-time modelling instead of scan-time facts. Before adopting it, read the language support table for your stack, because HTTP API declaration support is uneven across the listed languages, and check the architecture metrics status line, which marks the distributed metrics set as still in progress.

Frequently asked questions

Official sources

1. archguard/archguard on GitHub
2. License: MIT
3. Project website
4. README
5. Releases