Can Architecture Be Treated as Code? Exploring ArchGuard’s DSL‑Driven Governance

Architecture as Code

Architecture as Code treats architectural elements, patterns, and decisions as programmable artifacts that are tightly coupled with the system implementation.

Five‑step process to create a DSL

Define presentation patterns (UML, dependency graphs, sequence diagrams, etc.).

Extract domain‑specific terminology (e.g., micro‑kernel style, MVC layering).

Design relationships and syntax that express these elements naturally.

Implement an extensible parser.

Evolve the language through versioned iterations.

ArchGuard PoC – ArchDoc

ArchDoc is a proof‑of‑concept interactive analysis and governance platform built on top of Markdown.

Embedded DSL for describing architecture.

Stores architectural decisions, business architecture, and related documents.

Rich parsing library that supports copy‑and‑paste style customisation.

Customisable rendering pipelines.

Broad editor support.

Explicit Architecture Presentation

A Kotlin‑style DSL can declare layered components and their dependencies:

layered {
  prefixId("org.archguard")
  component("interface") dependentOn component("application")
  component("interface") dependentOn component("infrastructure")
  component("application") dependentOn component("domain")
  component("application") dependentOn component("infrastructure")
  component("domain") dependentOn component("infrastructure")
}

These definitions can be visualised with Mermaid.js:

Architecture‑as‑Document Rules

Documentation is treated as enforceable rules. Sample rule categories include:

SQL restrictions (e.g., disallow SELECT *).

Test‑code smell detection.

RESTful API checks.

Layer analysis (future implementation).

Custom change‑impact constraints (future implementation).

Rules can be toggled via GitHub‑style checklists, providing a linter‑like experience.

Consistent Design, Documentation, and Implementation

ArchGuard analyses multiple repositories to keep design, documentation, and code aligned. Example DSL fragment:

repos {
  repo(name = "Backend", language = "Kotlin", scmUrl = "https://github.com/archguard/archguard")
  repo(name = "Frontend", language = "TypeScript", scmUrl = "https://github.com/archguard/archguard-frontend")
  repo(name = "Scanner", language = "Kotlin", scmUrl = "https://github.com/archguard/scanner")
}

System Architecture of ArchGuard

ArchGuard combines a DSL, a Kotlin REPL, and data visualisation to form an interactive analysis platform. Key components:

Plugin‑based rule extensions allow new languages, custom rules, and data pipelines.

Backend query DSL provides LINQ‑style, type‑safe queries. Example:

database.from(Employees)
  .select(Employees.name)
  .where { (Employees.departmentId eq 1) and (Employees.name like "%vince%") }
  .forEach { row -> println(row[Employees.name]) }

Plugins can be used in CI pipelines to block invalid architectural dependencies.

Exploratory Data‑Centric View

ArchGuard follows an “execute‑explore” model similar to Jupyter or Observable notebooks: analysts probe data, sense patterns, and respond with updated rules or visualisations. Incremental analysis is planned to handle frequent commits and large‑scale visualisation challenges (e.g., OOM).

Future Directions

Planned improvements include richer metadata support, tighter integration with Mermaid/D3/ECharts, and a more polished REPL based on Kotlin‑Jupyter or Kotlin scripting.

Repository Links

https://github.com/archguard/archguard

https://gitee.com/archguard/archguard