AURA

Rollout

A possible starter stack?

← Back to the overview

1. Possible technical stack

A possible starter stack:

Git repositories
GitHub/GitLab/Bitbucket webhooks
CI/CD pipeline
AURA Ingest Service
Markdown
Mermaid or PlantUML
ADRs
OpenAPI / AsyncAPI
architecture.yaml
MkDocs Material
search index
vector database
graph model
MCP server
Jira integration

Optional later:

Structurizr DSL
Backstage integration
graph database
policy-as-code
LLM-based drift detection
automatic ADR suggestions
automatic diagram suggestions

2. Rollout in phases

AURA should not start with maximum governance. Recommended phases:

Phase 1: Documentation standard

  • define the repo structure
  • introduce architecture.yaml
  • create Markdown templates
  • create an ADR template
  • define the C4 minimum standard

Phase 2: Central website

  • build AURA Ingest
  • generate snapshots
  • generate the MkDocs website
  • display the service catalog
  • create links to repos and Jira

Phase 3: PR checks

  • trigger AURA on pull requests
  • comment on missing documentation
  • detect API/dependency changes
  • raise warnings only at first

Phase 4: AI Context Layer

  • create the search index
  • produce embeddings
  • maintain source metadata
  • connect an AI assistant
  • enable answers with sources

Phase 5: MCP server

  • expose AURA resources
  • expose AURA tools
  • expose standardized prompts
  • connect external AI clients

Phase 6: Governance and gates

  • hard checks for critical services
  • policy-as-code
  • drift detection
  • regular review deadlines
  • quality metrics

3. Minimum Viable AURA

A sensible MVP starts small.

MVP building blocks:

1. architecture.yaml per repository
2. Markdown templates for overview, context, containers, and ADRs
3. C4 context and container as Mermaid or PlantUML
4. AURA Ingest service
5. AURA repository with snapshots
6. MkDocs portal
7. simple PR check for missing documentation changes
8. full-text search
9. simple Jira and repo links

Not yet needed in the MVP:

full MCP server
graph database
automatic drift detection
hard merge gates
complex embeddings
fully automated AI documentation generation

4. Sample MVP flow

1. The repo contains architecture.yaml and docs/architecture/overview.md.
2. The developer opens a PR.
3. AURA checks whether docs/ or architecture.yaml were also changed for relevant code changes.
4. AURA comments on the PR if not.
5. After merge, AURA pulls the documentation.
6. AURA produces a snapshot with the commit ID.
7. The MkDocs portal is rebuilt.
8. Developers can read the central service overview.

5. AURA and DORA

AURA fits well with the findings of DORA in the AI era.

The core idea:

AI increases speed. But without good platforms, clear ownership, small changes, versioning, and accessible internal knowledge, chaos increases too.

AURA strengthens precisely those foundations:

  • versioning
  • small reviewable changes
  • internal platform capability
  • accessible documentation
  • fast feedback loops
  • human control

AURA is therefore not an AI toy but an organizational control and understanding tool for AI-accelerated software development.

6. 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

← Back to the overview

Governance and Drift

Boundaries and Risks