How to Govern Enterprise Architecture: Patterns, Standards, and Rules with ArchGuard

Pattern: Bad Smells and Good Solutions

In software engineering, widely shared design patterns represent best practices, while "bad smells" indicate suboptimal solutions. Code smells refer to poor code constructs, and architectural smells refer to flawed architectural decisions. Organizations often inherit consistent patterns due to staff turnover, custom frameworks, and company‑level guidelines, but these can be diluted over time.

The first step in governance is surfacing these smells, either through manual code review or by using expert systems like ArchGuard that analyze abstract syntax trees (AST) to automatically detect and visualize them.

Standard: Documenting Architectural Decisions

Standards are the documented conventions that capture a series of architectural decisions, such as API design, data handling, and quality safeguards. A lightweight architectural decision record (ADR) should be formatted and stored to guide developers.

Effective standards recommend best‑practice guidelines, explaining the rationale (WHY), the goal (WHAT), and the implementation steps (HOW). Large IT organizations sometimes enforce standards through testing or "exam"‑style checks.

Rule: Tool‑Based Formalization of Standards

Rules operationalize standards, typically via linters that analyze syntax trees. Examples include Checkstyle for Java and ESLint for TypeScript, which encode language‑level grammar rules into automated detection tools.

Governance Process: Matching Patterns, Visualizing Issues, and Evolving Rules

The governance workflow consists of:

Design and locate corresponding standards (best practices).

Manually identify patterns in code and encode them as rules.

Visualize and analyze identified problems.

Formalize standards into rule sets with measurable metrics.

Define fitness functions to guide system evolution.

Example: ArchGuard's SQL rule check.

override fun getById(systemId: Long): SystemInfo? {
    val sql = "select * from system_info where id=:systemId"
    return jdbi.withHandle<Long, Nothing> {
        it.createQuery(sql)
            .bind("systemId", systemId)
            .mapTo(SystemInfo::class.java)
            .firstOrNull()
    }
}

The query uses select *, which is discouraged for performance reasons. Detecting this pattern requires recognizing the createQuery call and its bound parameters, then extracting the SQL string from the AST.

Identify a generic SQL standard.

Manually find an easily implementable case from the standard.

Write code to extract SQL from the syntax tree and apply the rule.

Aggregate and display all detected issues.

A major challenge is "pattern escape": developers may modify code to avoid detection, rendering metrics ineffective, which raises further questions about improving measurement.

Other Considerations

Architectural governance can be enjoyable and collaborative; interested readers are encouraged to join discussions on the ArchGuard platform.