AURA

Templates and CLI

This page collects all templates, examples, and CLI commands for getting started with AURA in practice.

← Back to the overview

Templates and CLI

This page collects all templates, examples, and CLI commands for getting started with AURA in practice.

1. architecture.yaml

The central metadata file of every repository.

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 rules

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

In the long run, AURA could provide a CLI.

Initialization

aura init service

Generates templates and architecture.yaml.

Local validation

aura validate

Validates local documentation.

Local PR check

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

Runs the PR check locally or in CI.

Produce a snapshot

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

Produces a snapshot.

Render the site

aura render-site

Generates the MkDocs site.

Ask AURA a question

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

Queries the AURA context.

8. Service snapshot (example)

This is what a generated snapshot in the AURA repository looks like:

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

Continue reading

← Back to the overview

Boundaries and Risks

Summary