Boundaries and Risks
A classic wiki often has these problems:
Boundaries and Risks
1. Why AURA is not a classic wiki
A classic wiki often has these problems:
- information is maintained manually
- documentation is decoupled from the code
- freshness is unclear
- ownership is unclear
- diagrams are often outdated
- AI can hardly tell which information is trustworthy
- changes are not cleanly tied to PRs, commits, and releases
AURA differs in:
repo-native
versioned
reviewable
CI-validated
source-based
centrally findable
machine-readable
AI-usable
with ownership
with trust status
2. Why AURA is not just a developer portal
A developer portal or service catalog is an important part of AURA, but AURA goes further.
A classic developer portal often shows:
services
teams
APIs
documentation
links
ownership
AURA adds:
PR-based architecture review
documentation duty for architectural changes
architecture snapshots
AI context layer
MCP server
feature impact analysis
architectural drift detection
trust status
human-reviewed AI documentation
3. AURA and Jira
AURA should not replace Jira.
| Tool | Answers |
|---|---|
| Jira | What should happen functionally? Why is it planned? When will it be implemented? Who is working on it? |
| AURA | Which systems are affected? What architecture changes? Which decisions were made? Which risks emerge? Which repositories are relevant? Which documentation and diagrams were updated? |
| Git | code and change context |
Together you get:
Jira = work and product context
AURA = architecture and system context
Git = code and change context
4. Risks for AURA
AURA itself can fail if certain risks are not addressed.
Risk 1: too much bureaucracy
If AURA is too strict too early, teams will route around the system.
Counter-measure:
- staged rollout
- warnings before errors
- good templates
- automatic suggestions
- clear rules
- fast feedback loops
Risk 2: AI generates pretty but wrong documentation
Counter-measure:
- human review
- mandatory sources
- trust status
- CI checks
- never mark unchecked AI texts as "validated"
Risk 3: central documentation becomes the new truth
Counter-measure:
- the repo remains the source of truth
- AURA always shows source, commit, and snapshot
- no manual edits only in the portal
Risk 4: diagrams age
Counter-measure:
- version diagram sources
- C4 minimum standard
- PR checks on dependency changes
- drift detection
Risk 5: security issues from AI access
Counter-measure:
- permission model
- audit logs
- no secrets
- targeted code context instead of full repo access
- roles and visibilities
5. Open decisions
Several decisions still need to be made for AURA.
Documentation standard
- Which files are mandatory?
- Which files are optional?
- Which structure applies to all repos?
- How do we differentiate service, library, frontend, and infrastructure repos?
Diagram standard
- Mermaid, PlantUML, or Structurizr?
- Which C4 levels are mandatory?
- How are central system landscapes generated?
Metadata model
- What does
architecture.yamllook like exactly? - Which fields are mandatory?
- How are products, systems, services, and teams modeled?
PR governance
- When does AURA only comment?
- When does AURA block?
- Who can approve exceptions?
- How are false positives handled?
AI context
- Which content is embedded?
- Which content is only retrievable through tools?
- How are sources cited?
- How are permissions verified?
MCP
- Which resources does AURA expose?
- Which tools may an AI assistant use?
- Which tools are read-only?
- Which tools may trigger actions?
Continue reading
- Next page: Templates and CLI — templates and CLI for the practical start
- Rollout — how risks are mitigated by phases
- Governance and drift — security, trust, policies
- Summary — key statements in brief