← Back to the overview

1. Core idea

On pull requests, AURA checks whether architecturally relevant changes were also documented correctly.

After the merge to main, AURA pulls the validated documentation artifacts from the repository, produces traceable architecture snapshots, and updates a central architecture website as well as an AI-usable context layer.

AURA thereby serves three audiences:

1. People who need to understand architecture, systems, dependencies, and decisions.
2. Engineering teams who must know during feature planning and implementation which systems are affected.
3. AI assistants that need verified, versioned, source-based context for analysis, ticket creation, code exploration, and architecture reviews.

2. The most important architectural principle

The central AURA documentation is not the primary source of truth.

The primary truth stays in each repository:

Repository
  ├─ Code
  ├─ versioned architecture documentation
  ├─ C4 diagram sources
  ├─ ADRs
  ├─ API and event specifications
  ├─ ownership metadata
  └─ quality and risk information

From this, AURA produces a central, versioned, and traceable read model.

The truth lives in the repo. AURA derives the central view, the search index, and the AI context from it.

This principle prevents AURA itself from becoming yet another outdated wiki.

3. Name and meaning

AURA — Architecture Understanding & Retrieval Assistant

The name captures three core functions:

• Understanding — making architecture comprehensible
• Retrieval — making relevant architecture information findable on demand
• Assistant — supporting humans and AI assistants in planning, analysis, and implementation

A possible product description:

AURA is a repository-sourced, human-reviewed architecture context layer that makes systems, decisions, diagrams and dependencies understandable for engineers and usable by AI assistants.

4. Positioning as best practice

AURA does not reinvent every building block. The core architecture is a modern combination of established best practices:

• Docs-as-Code
• Architecture-as-Code
• C4 Model
• Architecture Decision Records (ADRs)
• structured architecture documentation, e.g. following arc42
• Service Catalog / Internal Developer Portal
• CI/CD quality gates
• review-based governance
• human-in-the-loop AI review
• AI context layer
• MCP server for AI integration

What is new — and particularly modern — is the consistent combination of these building blocks in the context of heavily AI-assisted software development:

• AI-generated or AI-assisted documentation updates
• AI-supported detection of documentation drift
• central aggregation across many repositories
• AI-readable architecture context
• MCP interface for external AI assistants
• feature and ticket analysis based on verified architecture information

AURA is therefore not a naive home-grown idea, but an evolution of existing best practices for the AI era.

Continue reading

• Next page: Architecture — target picture and core building blocks
• Repository Standard — what an AURA-compliant repo looks like
• Boundaries and risks — what AURA is not

← Back to the overview