AURA

PR Check

On every pull request, AURA is triggered. AURA analyzes the PR and verifies whether relevant architecture information was updated.

← Back to the overview

PR Check

1. What does AURA check on a pull request?

On every pull request, AURA is triggered. AURA analyzes the PR and verifies whether relevant architecture information was updated.

The PR check should verify, among other things:

Which files were changed?
Which services are affected?
Are there API changes?
Are there new dependencies?
Was infrastructure changed?
Was deployment changed?
Was security/auth changed?
Was data storage changed?
Was eventing/messaging changed?
Was the architecture documentation updated?
Was an ADR added?
Were C4 diagrams updated?
Were ownership or metadata changed?

2. When is documentation mandatory?

AURA should not require documentation for every small code change. That would be too annoying and would destroy acceptance.

But AURA should require documentation when architecturally relevant changes are detected:

  • A public API changes.
  • An event or topic changes.
  • A new dependency is introduced.
  • A dependency is removed.
  • A new service is integrated.
  • Deployment or runtime changes.
  • Security or authentication changes.
  • Data storage or data flow changes.
  • A new technical pattern is introduced.
  • An existing architectural principle is violated.
  • A critical quality goal is touched.

When such a change is detected, at least one of the following artifacts should be updated:

architecture.yaml
C4 diagram
ADR
OpenAPI/AsyncAPI
service documentation
deployment documentation
security/risk documentation
quality goals

3. Behavior when documentation is missing

When AURA detects that an architecturally relevant change has not been documented, several escalation levels exist:

Soft:
  AURA comments on the PR.

Medium:
  AURA raises a warning and notifies the owner.

Hard:
  AURA blocks the merge as a required check.

Recommended rollout:

Phase 1: hints only
Phase 2: warnings with owner notification
Phase 3: hard gates for critical repos, APIs, and architectural changes

This way, AURA can be introduced without immediately blocking teams.

4. Example: AURA PR comment

An AURA comment on a PR could look something like this:

## AURA Architecture Check

AURA detected architecture-relevant changes in this PR.

### Detected changes
- New dependency added: `payment-provider-adapter`
- OpenAPI contract changed: `POST /invoices`
- Deployment configuration changed: new environment variable `PAYMENT_TIMEOUT_MS`

### Required documentation updates
- Update `docs/architecture/containers.md`
- Update `docs/api/openapi.yaml`
- Consider adding an ADR for the new payment provider integration

### Status
Warning: Documentation update incomplete.

Owner: team-payments
Related Jira: PAY-123

5. Example rules (policy-as-code)

The PR rules can be maintained as a configuration file:

checks:
  - id: docs-updated-for-api-change
    description: API changes require OpenAPI and architecture documentation updates.
    trigger:
      changedFiles:
        - "src/**/controller/**"
        - "src/**/api/**"
    requireOneOf:
      - "docs/api/openapi.yaml"
      - "docs/architecture/**"
    severity: warning

  - id: adr-required-for-new-external-dependency
    description: New external dependencies require an ADR.
    trigger:
      dependencyAdded:
        type: external
    require:
      - "docs/adr/*.md"
    severity: warning

  - id: c4-required-for-critical-service
    description: Critical services require context and container diagrams.
    trigger:
      metadata:
        criticality: high
    require:
      - "docs/architecture/context.*"
      - "docs/architecture/container.*"
    severity: error

6. Commit, PR, or merge?

AURA should not treat every single commit as central truth. A commit can be an intermediate state.

Better:

Feature branch:
  developers and AI change code and local documentation

Pull request:
  AURA checks code, tests, documentation, diagrams, ADRs, and contracts

Merge to main:
  AURA updates the central architecture overview

Release:
  optionally a versioned architecture state is frozen

The central AURA state should display verified states, not arbitrary intermediate ones.

7. Detailed flow

1. The developer creates a Jira ticket or receives a feature request.
2. The developer asks AURA which systems and repositories are affected.
3. AURA analyzes the feature description against the architecture context.
4. The developer or AI agent implements the change in the appropriate repository.
5. If needed, the developer or AI agent updates docs, ADRs, C4 diagrams, and API specs.
6. A pull request is opened.
7. AURA PR check is triggered.
8. AURA analyzes diff, metadata, and documentation changes.
9. AURA comments on missing or inconsistent documentation.
10. A human reviewer reviews code and AURA hints.
11. The PR is merged.
12. AURA Ingest pulls validated artifacts from main.
13. AURA produces an architecture snapshot.
14. AURA updates the website, search index, embeddings, and service graph.
15. AI assistants can access the updated context via MCP.

Continue reading

← Back to the overview

Documentation

Ingest and Portal