← Back to the overview

Summary

Core summary

AURA is a repo-sourced architecture knowledge system.

Every repository contains normalized, versioned technical documentation with C4 diagrams, ADRs, metadata, and interface descriptions.

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

After the merge, AURA produces a traceable architecture snapshot from the validated repository artifacts and updates from it:

central MkDocs website
service catalog
dependency graph
search index
embedding index
AI context layer
MCP server

Via the MCP server, AURA provides verified context and curated tools to AI assistants.

This allows feature analysis, architecture understanding, ticket creation, pull request review, and code exploration to be grounded in verified, versioned architecture information.

The single most important sentence

AURA is the architecture context layer between code, people, and AI.

Or in more detail:

AURA turns repo-native, versioned, and human-reviewed architecture documentation into a central, searchable, and AI-usable architecture overview.

The ten key statements

1. The repo is the source of truth — the truth lives in the repository, not in the portal.
2. Documentation is part of the code — versioned, reviewable, CI-validated.
3. AURA checks in the PR — architecturally relevant changes need documentation.
4. Snapshots instead of loose texts — every central statement is traceable to a commit, PR, and owner.
5. C4 as the diagram standard — at least C1 and C2, sources versioned.
6. ADRs explain the why — structured and findable.
7. AI gets verified context — with sources, not just embeddings.
8. MCP as the interface — resources, tools, and prompts for AI assistants.
9. Humans decide, AI supports — human-in-the-loop remains non-negotiable.
10. Roll out in stages — first hints, then warnings, then hard gates.

The next sensible step

The next step is not the technical implementation right away, but the definition of the standard.

Concretely, the following should be defined next:

1. Which repository types exist?
2. Which documentation files are mandatory per repo type?
3. What does architecture.yaml look like exactly?
4. Which C4 diagrams are mandatory?
5. What does an ADR template look like?
6. Which PR rules apply initially?
7. What information does the first MkDocs prototype need?
8. Which MCP resources and tools are needed for the first AI use case?

Only after that should an MVP be built.

Continue reading

• Read from the beginning: The Problem — re-read every chapter in order
• The Idea — concept and architectural principle
• Rollout — phases and MVP
• Templates and CLI — everything for the phase-1 start

← Back to the overview