AURA

Ingest und Portal

Nach dem Merge nach main läuft der AURA Ingest. Der Ingest zieht die validierten Dokumentationsartefakte aus dem Repository und erzeugt daraus einen versionierten Snapshot.

← Zurück zur Übersicht

Ingest und Portal

1. AURA Ingest

Nach dem Merge nach main läuft der AURA Ingest. Der Ingest zieht die validierten Artefakte aus docs/aura/ und ergänzende Metadaten aus dem Repository und erzeugt daraus einen versionierten Snapshot.

AURA kopiert nicht einfach lose Texte, sondern erzeugt nachvollziehbare Architecture Snapshots.

Ein Snapshot enthält mindestens:

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/aura/README.md
  - docs/aura/01-overview/system-description.md
  - docs/aura/02-architecture/overview.md
  - docs/aura/02-architecture/components.md
  - docs/aura/02-architecture/decisions/
  - docs/aura/03-integrations/
  - architecture.yaml

Dadurch bleibt jederzeit nachvollziehbar, woher eine Information stammt.

Der Ingest behandelt die zentrale Website nicht als neue Quelle der Wahrheit. Die Website zeigt nur, was aus validierten Repository-Quellen gelesen wurde.

2. AURA Knowledge Store

Der AURA Knowledge Store ist die interne Wissensbasis von AURA. Er kann aus mehreren Speichern bestehen:

Git Repository für Snapshots
Dateisystem oder Objekt-Storage für docs/aura-Artefakte
Suchindex für Volltextsuche
Vektorindex für Embeddings
Graphdatenbank oder Graphstruktur für Service-Abhängigkeiten
Metadatenbank für Owner, Status, Quellen und Zeitpunkte

Der Knowledge Store dient als Grundlage für:

  • zentrale Webseite
  • Suche
  • Architekturgraph
  • KI-Kontext
  • MCP Server
  • Qualitätsberichte
  • Drift-Erkennung

3. AURA Webseite

AURA generiert eine zentrale Webseite aus den Snapshot-Daten. Diese Webseite ist primär für Menschen gedacht und zeigt normalisierte Sichten auf viele docs/aura/-Quellen.

Sie zeigt:

Produktübersicht
Systemübersicht
Service-Katalog
Team-/Owner-Übersicht
C4-Systemlandschaft
Service-Abhängigkeiten
API-/Event-Übersicht
Architekturentscheidungen
Risiken und technische Schulden
Änderungen seit letztem Stand
Links zu Repos, PRs und Jira-Tickets
Downloadbare Standards und Skills

Die Webseite soll schnell beantworten:

  • Welche Systeme gibt es?
  • Welches Team besitzt was?
  • Welche Services hängen zusammen?
  • Welche APIs und Events existieren?
  • Welche Architekturentscheidungen gelten?
  • Welche Änderungen gab es zuletzt?
  • Wo muss ich für Feature X vermutlich ran?

4. Mögliche Webseitenstruktur

AURA Portal
  ├─ Home
  ├─ Products
  │   ├─ Commerce Platform
  │   ├─ Identity Platform
  │   └─ Reporting Platform
  ├─ Systems
  │   ├─ Billing System
  │   ├─ User Management
  │   └─ Notification System
  ├─ Services
  │   ├─ billing-service
  │   ├─ user-service
  │   └─ notification-service
  ├─ Architecture Decisions
  ├─ APIs & Events
  ├─ Teams & Ownership
  ├─ Quality & Risks
  ├─ Recent Architecture Changes
  └─ AI Context / MCP

5. Service-Seite im AURA Portal

Eine Service-Seite könnte enthalten:

Service Name
Kurzbeschreibung
Owner
Produkt / Domäne
Lifecycle
Criticality
Repository-Link
Jira-Projekt
Letzter Snapshot
Dokumentationsstatus
C4 Context Diagram
C4 Container Diagram
API Contracts
Events
Abhängigkeiten
ADRs
Qualitätsziele
Risiken
Letzte architekturrelevante Änderungen

Beispiel: billing-service

# billing-service

Owner: team-payments
Product: commerce-platform
Criticality: high
Lifecycle: production
Repository: git.example.com/commerce/billing-service
Last Snapshot: commit `a81f3c2`
Documentation Status: validated
Aura Source: docs/aura/

## Purpose
The billing-service is responsible for invoice creation, payment status tracking and billing events.

## Dependencies
- user-service
- payment-provider-adapter
- notification-service

## Provides
- Billing REST API
- invoice-created events

## Architecture Decisions
- ADR-0001: Use event-driven billing
- ADR-0002: Introduce payment provider adapter

## Risks
- Payment provider coupling
- Eventual consistency in invoice status

6. Portal-Rendering

Für den Start eignet sich ein statisches oder hybrid gerendertes Portal gut, weil Aura-Dokumentation bereits als Markdown und strukturierte Content Source vorliegt.

Vorteile:

  • Markdown-basiert
  • Git-freundlich
  • einfach versionierbar
  • gut automatisierbar
  • gute Suche möglich
  • Diagramme können eingebettet werden
  • CI/CD-kompatibel

AURA kann mit Nuxt Content, MkDocs oder einem eigenen Portal gerendert werden. Wichtig ist nicht das Tool, sondern dass die Website aus validierten docs/aura/-Quellen entsteht.

7. AURA und Backstage

AURA kann unabhängig von Backstage funktionieren. Es gibt aber eine starke konzeptionelle Nähe zu Backstage:

  • Service Catalog
  • TechDocs
  • Ownership
  • zentrale Sicht auf verteilte Repos
  • Developer Portal

Mögliche Optionen:

Option A:
AURA erzeugt eigenes Content-Portal.

Option B:
AURA erzeugt Daten und Artefakte für Backstage.

Option C:
AURA wird als Backstage Plugin gebaut.

Option D:
AURA startet mit einer einfachen Content-Website und migriert später teilweise in Backstage.

Für einen pragmatischen Start ist eine statische Content-Website meist schneller. Für eine größere Plattformstrategie kann Backstage später interessant werden.

Weiterlesen

← Zurück zur Übersicht

PR Check

KI und MCP