AURA

Governance and Drift

AURA needs a clear permissions and security model. Not every person and not every AI may see everything.

← Back to the overview

1. Security and permissions model

AURA must be able to answer:

  • Who is allowed to see which services?
  • Which repositories are confidential?
  • Which documents contain security details?
  • May an AI assistant only read?
  • May an AI assistant retrieve code?
  • May an AI assistant comment on PRs?
  • May an AI assistant create tickets?
  • May an AI assistant create documentation suggestions?

This is particularly important for:

  • security documentation
  • infrastructure information
  • customer data
  • secrets
  • internal interfaces
  • product-critical services
  • code context retrieval by AI

2. Architectural drift

AURA should detect architectural drift in the long run.

Architectural drift means: the code behaves differently from what the documented architecture describes.

Examples:

  • The code imports a service that is not documented as a dependency.
  • A new API endpoint exists, but OpenAPI was not updated.
  • A new event is published, but AsyncAPI is missing.
  • Deployment uses a new database, but the architecture documentation does not mention it.
  • An ADR says direct calls are forbidden, but the code introduces direct calls.

AURA can detect drift through:

  • static code analysis
  • dependency scans
  • API diffing
  • event contract diffing
  • infrastructure diffing
  • comparison with architecture.yaml
  • AI-supported analysis
  • PR diff analysis

3. Human control

AURA should use AI but not hand over control to AI.

AI may suggest, summarize, and check. Humans decide and are accountable.

AI may help with:

  • summaries
  • documentation drafts
  • ADR drafts
  • diagram suggestions
  • inconsistency detection
  • PR comments
  • feature impact analysis
  • architectural drift detection

Humans remain accountable for:

  • architectural decisions
  • approvals
  • review
  • ownership
  • prioritization
  • quality assessment
  • exceptions
  • governance

4. AI-generated documentation

AURA should support AI-generated documentation but not accept it uncritically.

Better than:

Every repo gets AI-generated documentation.

is:

Every repo gets normalized, versioned architecture documentation that AI may create or update, but which is reviewed by humans and CI rules.

Quality criteria for documentation are not that it is AI-generated. The quality criteria are:

  • versioned
  • reviewable
  • standardized
  • understandable
  • machine-readable
  • up to date
  • owned by an accountable owner
  • validated by CI
  • source-based

5. Service graph

AURA should build a service graph in the long run.

Nodes:

products
systems
services
teams
APIs
events
databases
queues
Jira epics
ADRs
repositories
deployment environments

Edges:

owns
belongs_to
depends_on
provides_api
consumes_api
publishes_event
consumes_event
deployed_to
decided_by
implemented_by
related_to_ticket

This graph is valuable for both humans and AI.

Example

team-payments
  owns -> billing-service

billing-service
  belongs_to -> commerce-platform
  depends_on -> user-service
  depends_on -> payment-provider-adapter
  provides_api -> billing-api
  publishes_event -> invoice-created
  documented_by -> docs/architecture/overview.md
  decided_by -> ADR-0002
  changed_by -> PR-847
  related_to_ticket -> PAY-123

6. Policies and rules

AURA needs rules that define when something is valid.

Examples:

  • Every production service needs an owner.
  • Every critical service needs at least C1 and C2 diagrams.
  • Every public API needs OpenAPI.
  • Every event needs AsyncAPI or event documentation.
  • Every new external dependency needs an ADR.
  • Every change to security/auth needs review by the security team.
  • Every change to data storage needs a documentation update.
  • Every critical document must be reviewed at least every 90 days.

These rules can be introduced step by step.

7. Policy-as-code

In the long run, AURA rules can be maintained as policy-as-code:

rules:
  - id: productive-service-requires-owner
    severity: error
    when:
      lifecycle: production
    require:
      - owner

  - id: critical-service-requires-c4
    severity: error
    when:
      criticality: high
    require:
      - documentation.c4_context
      - documentation.c4_container

  - id: public-api-requires-openapi
    severity: error
    when:
      provides_public_api: true
    require:
      - contracts.openapi

  - id: external-dependency-requires-adr
    severity: warning
    when:
      dependency_added: external
    require:
      - adr

8. Metrics

AURA can deliver quality metrics in the long run:

  • number of services with validated documentation
  • number of services without owners
  • number of critical services without a C4 diagram
  • number of PRs with architecturally relevant changes
  • number of PRs with missing documentation updates
  • average age of documentation
  • number of ADRs per product area
  • number of detected drift cases
  • number of feature analyses by AURA

These metrics should not be used to punish individual developers, but to improve overall system quality.

Continue reading

← Back to the overview

AI and MCP

Rollout