Architecture
The basic structure looks like this:
Architecture
1. Target picture
The basic structure looks like this:
Jira ticket / feature request
|
v
Pull request in the repository
|
v
AURA PR Check
|
| checks:
| - Was relevant documentation updated?
| - Was a C4 diagram updated?
| - Is an ADR required?
| - Did APIs or events change?
| - Did dependencies change?
| - Is ownership clear?
| - Is there architectural drift?
v
Merge to main
|
v
AURA Ingest
|
| produces an architecture snapshot
| including repo, commit, PR, owner, status
v
AURA Knowledge Store
|
+--> MkDocs website
+--> search index / embeddings
+--> service graph
+--> MCP server
+--> AI assistant
2. Core building blocks
AURA consists of several clearly separated building blocks.
Repository Documentation Standard
|
v
AURA PR Check
|
v
AURA Ingest Service
|
v
AURA Knowledge Store
|
+--> AURA Web Portal
+--> AURA Search Index
+--> AURA Service Graph
+--> AURA AI Context Layer
+--> AURA MCP Server
| Building block | Responsibility | Detail page |
|---|---|---|
| Repository Documentation Standard | Standardized documentation structure in every repo | Repository Standard |
| AURA PR Check | Verifies architecturally relevant documentation changes | PR Check |
| AURA Ingest Service | Pulls artifacts after a merge to main | Ingest and portal |
| AURA Knowledge Store | Versioned knowledge base (Git, index, graph) | Ingest and portal |
| AURA Web Portal | Human-facing view (MkDocs) | Ingest and portal |
| AURA Search Index | Full-text and vector search | AI and MCP |
| AURA Service Graph | Model of service dependencies | Governance and drift |
| AURA AI Context Layer | AI-suitable, citable context | AI and MCP |
| AURA MCP Server | Interface for AI assistants | AI and MCP |
3. AURA as an architecture compiler
AURA can be understood as a kind of compiler.
Input
Repo documentation
architecture.yaml
C4 diagram sources
ADRs
OpenAPI/AsyncAPI
Jira links
PR/commit metadata
ownership data
Processing
validation
normalization
snapshot creation
indexing
graph building
AI context preparation
drift detection
Output
MkDocs website
service catalog
architecture map
dependency graph
ADR index
API/event index
AI context layer
MCP resources
MCP tools
quality reports
PR comments
4. AURA repository
AURA can have its own repository. This repository does not contain the primary truth but the aggregated, generated, and versioned central view.
Possible structure:
aura-repository/
/snapshots
/payment-service
snapshot.yaml
overview.md
context.md
containers.md
adr-index.md
/user-service
snapshot.yaml
overview.md
context.md
/generated
/mkdocs
/service-graph
/search-index
mkdocs.yml
It is important to clearly distinguish between source repositories and AURA snapshots.
Continue reading
- Next page: Repository Standard — the compiler's input in detail
- Ingest and portal — the processing and outputs
- AI and MCP — the AI-related output