AURA

Vorlagen und CLI

Diese Seite sammelt alle Vorlagen, Beispiele und CLI-Befehle für den praktischen Start mit AURA.

← Zurück zur Übersicht

Vorlagen und CLI

Diese Seite sammelt alle Vorlagen, Beispiele und CLI-Befehle für den praktischen Start mit AURA.

1. architecture.yaml

Die zentrale Metadatendatei jedes Repositories.

apiVersion: aura/v1
kind: Service
metadata:
  name: billing-service
  description: Handles invoice creation and billing status updates.
  owner: team-payments
  product: commerce-platform
  domain: payments
  lifecycle: production
  criticality: high

repository:
  provider: github
  url: https://github.example.com/commerce/billing-service
  defaultBranch: main

jira:
  projectKey: PAY
  component: Billing

runtime:
  type: service
  language: java
  framework: spring-boot
  deployment: kubernetes

relationships:
  dependsOn:
    - user-service
    - payment-provider-adapter
  providesApis:
    - billing-api
  publishesEvents:
    - invoice-created
  consumesEvents:
    - user-profile-updated

contracts:
  openapi: docs/api/openapi.yaml
  asyncapi: docs/api/asyncapi.yaml

documentation:
  overview: docs/architecture/overview.md
  context: docs/architecture/context.md
  containers: docs/architecture/containers.md
  components: docs/architecture/components.md
  runtime: docs/architecture/runtime.md
  deployment: docs/architecture/deployment.md
  adrFolder: docs/adr
  qualityGoals: docs/quality/quality-goals.md
  knownRisks: docs/quality/known-risks.md

diagrams:
  c4Context: docs/architecture/context.mmd
  c4Container: docs/architecture/container.mmd

review:
  requiredReviewers:
    - team-payments
    - architecture-board
  reviewIntervalDays: 90

2. Markdown-Template: overview.md

# Service Overview

## Purpose
What is this service responsible for?

## Scope
What belongs to this service?

## Non-Scope
What explicitly does not belong to this service?

## Owner
Which team owns this service?

## Business Context
Which product, domain or business process does this service support?

## Main Responsibilities
- Responsibility 1
- Responsibility 2
- Responsibility 3

## Important Dependencies
- Dependency 1
- Dependency 2

## Provided Interfaces
- API 1
- Event 1

## Operational Notes
What should developers know before changing this service?

## Links
- Repository
- Jira component
- Dashboards
- Runbooks

3. Markdown-Template: context.md

# System Context

## Summary
Describe how this system fits into the broader product landscape.

## Users and External Systems
- User or system 1
- User or system 2

## Context Diagram

```mermaid
C4Context
  title System Context diagram for Billing Service
  Person(customer, "Customer")
  System(billing, "Billing Service")
  System_Ext(paymentProvider, "Payment Provider")
  Rel(customer, billing, "Views invoices")
  Rel(billing, paymentProvider, "Processes payments")
```

## Notes

Important context decisions or assumptions.

4. ADR-Template

# ADR-0001: Title

## Status
Proposed | Accepted | Deprecated | Superseded

## Context
What is the problem or decision context?

## Decision
What has been decided?

## Alternatives Considered
What alternatives were considered?

## Consequences
What are the positive and negative consequences?

## Related Artifacts
- Jira:
- Pull Request:
- C4 Diagram:
- Services:

5. PR-Check-Regeln

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

7. AURA CLI

Langfristig könnte AURA eine CLI anbieten.

Initialisierung

aura init service

Erzeugt Templates und architecture.yaml.

Lokale Validierung

aura validate

Prüft lokale Dokumentation.

PR-Check lokal

aura check-pr --base main --head feature-branch

Führt PR-Check lokal oder in CI aus.

Snapshot erzeugen

aura ingest --repo payment-service --commit a81f3c2

Erzeugt Snapshot.

Webseite rendern

aura render-site

Generiert MkDocs-Seite.

KI-Frage an AURA

aura ask "Which services are affected by invoice changes?"

Fragt AURA-Kontext ab.

8. Service-Snapshot (Beispiel)

So sieht ein generierter Snapshot im AURA-Repository aus:

repo: payment-service
repository_url: https://git.example.com/commerce/payment-service
branch: main
commit: a81f3c2
pr: 847
owner: team-payments
product: commerce-platform
documentation_status: validated
last_ingested: 2026-05-09T14:30:00Z
source_paths:
  - docs/architecture/overview.md
  - docs/architecture/context.md
  - docs/architecture/containers.md
  - docs/adr/
  - architecture.yaml
  - docs/api/openapi.yaml

Weiterlesen

← Zurück zur Übersicht

Abgrenzung und Risiken

Zusammenfassung