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 Dokumentationsartefakte 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/architecture/overview.md
  - docs/architecture/context.md
  - docs/architecture/containers.md
  - docs/adr/
  - architecture.yaml
  - docs/api/openapi.yaml

Dadurch bleibt jederzeit nachvollziehbar, woher eine Information stammt.

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 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, zum Beispiel mit MkDocs. Diese Webseite ist primär für Menschen gedacht.

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

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

## 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. Warum MkDocs?

MkDocs eignet sich gut, um aus Markdown eine statische Webseite zu erzeugen.

Vorteile:

  • Markdown-basiert
  • Git-freundlich
  • einfach versionierbar
  • gut automatisierbar
  • gute Suche möglich
  • mit Material for MkDocs sehr gutes UI
  • Diagramme können eingebettet werden
  • CI/CD-kompatibel

AURA könnte MkDocs als erste Portaloberfläche verwenden. Langfristig könnte AURA zusätzlich oder alternativ in Backstage, Roadie, Port oder ein eigenes Developer Portal integriert werden.

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

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

Option C:
AURA wird als Backstage Plugin gebaut.

Option D:
AURA startet mit MkDocs und migriert später teilweise in Backstage.

Für einen pragmatischen Start ist MkDocs vermutlich schneller. Für eine größere Plattformstrategie kann Backstage später interessant werden.

Weiterlesen

← Zurück zur Übersicht

PR Check

KI und MCP