Referenzen

Die Architecture Graph Method (AGM) in der Praxis — Methodik, Optionen und anonymisierte Ergebnisse aus konkreten Analyseprojekten.

AGMWRK-002Anonymisiert

referenzen · projektgraph

Kontext

Vom Verfahren zur belastbaren Entscheidungsgrundlage

Die referenzierten Projekte folgen demselben Grundprinzip: Architekturwissen wird aus dem Quellcode extrahiert, in einem traversierbaren Dokumentationsgraphen strukturiert und durch gezielte Analyse-Arbeiten vertieft. Jede Aussage ist auf Code, Konfiguration oder dokumentierte Evidenz zurückführbar.

Die Beispiele reichen von Analyse- und Migrationsprojekten bis zu KI-gestützter Umsetzung und funktionaler Erweiterung bestehender Plattformen — jeweils mit Bootstrap, vertiefender Architektur-Arbeit und belastbarer Ergebnisdokumentation.

Verfahren · Blueprint Pattern

Architecture Graph Method (AGM)

Repo-lokaler Markdown-Linkgraph unter `docs/architecture/`, orchestriert über `blueprint.md` und gepflegt durch KI-Agenten mit menschlicher Validierung. OKF-konforme Artefakte, deterministische Graph-Traversierung statt RAG — Architekturdokumentation als API für strukturierte KI-Konversation. Anschlussfähig an Googles Knowledge Catalog und Open Knowledge Format.

Optionen

Dokumentations-Template: arc42 (Standard), lean-service, c4-light, adr-first oder custom
Artefaktformat: Open Knowledge Format (OKF) — Markdown + YAML-Frontmatter, index.md, log.md
Fokus-Bereiche wählbar: Implementation, Schnittstellen, Persistenz, Security, Deployment, Domain
Golden Path: Install → Adopt → Continue → Maintain → Review (Verify in frischem Chat)
Fünf Tracks: Build, Evolve, Architect, Domain, Verify — modular kombinierbar
Werkzeugwahl: Copy-Paste-Prompts, MCP/CLI (`agm`) oder IDE-Regeln (Cursor, Claude, Copilot)

Vorgehen

Install: Scaffold mit Prompts, Rollen und Template-Stubs im Ziel-Repository
Adopt: Erstsession erzeugt blueprint.md, entry-point.md, always-on.md und erste evidenzbasierte Sektion
Continue: Kapitelweise Befüllung des gewählten Templates (arc42, C4, ADRs)
Architect Work: Gezielte Analysen (Security, Modernisierung, Domain Map, Tech Debt) als work/WRK-Items
Maintain: Dokumentation synchron zu git diff — nur betroffene Abschnitte
Review: Report-only-Verifikation in separatem Chat — Link-Integrität, Vollständigkeit, Evidenz

Ergebnis

Traversierbarer Architektur-Graph mit 30–40+ verlinkten Dokumenten pro Projekt
blueprint.md als persistenter Fortschritts- und WRK-Register über Sessions hinweg
Strukturierte work/-Reports (Security, Migration, Domain, Debt) mit Evidenz-Links
Risiko- und Schuldregister als priorisierte Entscheidungsgrundlage
CI-fähige Link-Integritätsprüfung — broken links blockieren PRs

Praxis

Anonymisierte Projektbeispiele

Optionen, Vorgehen und messbare Ergebnisse — dokumentiert im AGM-Graph.

work/headless-commerce.md

Java · Spring Boot · Reverse Engineering & Security Assessment

Headless E-Commerce Monolith

JavaSpring BootSecurityarc42Tech DebtDDD

WRK highlightDie Risikoanalyse (WRK-002) deckte 3 kritische Sicherheitslücken auf, die ohne Reverse Engineering und gezielte Security-Arbeit im Architektur-Graph unsichtbar geblieben wären — darunter ein Default-JWT-Secret, fehlerhafte Token-Refresh-Logik und Auth-Bypass über URL-Matcher-Lücken.

Ein gewachsener Java-Monolith (5 Maven-Module, 64 REST-Controller, ~186 JPA-Entities) als Headless-Commerce-API ohne verlässliche Architekturdokumentation. Produktionsreife unklar — strategische Entscheidung zwischen Modernisierung und Neuschreibung stand an.

Auslöser: Fehlende Ist-Transparenz, parallele API-Versionen (v0/v1/v2), duplizierte Facade-Implementierungen und unbekannter Security-Status vor einem geplanten Go-Live.

Optionen

Option A: Evolutionärer Java-Pfad — Spring Boot 2.5 → 3.x, Jakarta-Migration, Facade-Konsolidierung
Option B: Python-Greenfield — modularer Monolith mit funktionaler API-Äquivalenz, Greenfield-Datenbank
Dokumentation: arc42 via AGM, 7 Analyse-Workstreams (WRK-001 bis WRK-007)
Scope bewusst ohne Code-Remediation — Entscheidungsgrundlage, nicht Implementierung

Vorgehen

Bootstrap + 14 arc42-Phasen in ~15 Sessions (2 Tage) — 35+ verlinkte Architektur-Dokumente
WRK-001: Refactoring-Analyse — 10 priorisierte Kandidaten (RF-01 bis RF-10)
WRK-002: Security-Analyse — Spring Security, JWT-Lifecycle, URL-Matcher, Default-Configs
WRK-003/004: Modernisierungs-Roadmap und Python-Greenfield-Bewertung (Stakeholder-Interview)
WRK-005/006/007: Cross-Layer-Analyse, DDD Context Map (13 Bounded Contexts), Tech-Debt-Register (30 Items)
Milestone Review: PASS WITH NOTES — 339/341 Links valide

Ergebnis

3 kritische + 7 high-severity Security-Findings — u.a. Default-JWT-Secret, Auth-Bypass via URL-Matcher, unauthentifizierte DELETE-Endpunkte
18 Risiken (R-01–R-17) und 30 Tech-Debt-Items (TD-01–TD-30) mit Paydown-Sequenz
13 Bounded Contexts mit Integrationsmustern dokumentiert
Zwei strategische Roadmaps: 6-Phasen-Java-Modernisierung und konditionierter Python-Pfad
Klare Go/No-Go-Aussage: Default-Config nicht produktionsreif — P0-Security vor Strukturarbeit

work/cms-platform.md

PHP · Joomla CMS 5.x · Architektur-Dokumentation & Event-System-Analyse

Open-Source CMS-Kernplattform

PHPCMSarc42DDDPlugin-ArchitekturTech Debt

WRK highlightDie Deep-Dive-Analyse des Plugin-/Event-Systems (WRK-001) identifizierte drei koexistierende Dispatch-Stile und ~50 Legacy-Call-Sites — mit konkreter Empfehlung für Registry-Erweiterung und triggerEvent-Abbau vor dem Joomla-7.0-Release.

Eine große, extensionsgetriebene PHP-CMS-Kernplattform (PHP 8.1+, Multi-App: Site, Admin, JSON:API, CLI) mit ~76 Datenbanktabellen und komplexem Plugin-/Event-System. Ziel: System verständlich, wartbar und governierbar dokumentieren — nicht Neudesign.

Schwerpunkt: Plattform-Evolution (Factory→DI, legacy triggerEvent→typed Events), Extension-Governance und technische Schuld vor dem nächsten Major-Release.

Optionen

Dokumentations-Template: arc42 (gewählt) — alternativ c4-light, adr-first, lean-service
Charakterisierung: Monolith + Extension-Modell als bewusste Plattform-Architektur (nicht neu entschieden)
Domain-Tiefe: 18 Subdomains klassifiziert — 3 Core, 11 Supporting, 4 Generic
Follow-on: WRK-001 Plugin/Event-Deep-Dive, Data-Model-Refinement — Milestone Review ausstehend

Vorgehen

AGM-Bootstrap: 20 Sessions — Phasen 0–17 (vollständiges arc42 + Domain Layer + Ops-Runbooks)
Domain Layer: Context Map (10 Bounded Contexts), Event Catalog, Core-Context-Modelle
WRK-001: Plugin- & Event-System-Analyse — 7 Findings, 6 priorisierte Empfehlungen
Data Model: ~76 Tabellen aus Installer-SQL, 8 DB-Performance-Patterns dokumentiert
3 ADRs formalisiert: JSON:API, DI-Container, Extension-Boot via services/provider.php
Qualitätsrahmen: 13 messbare Szenarien (QS-01–QS-13) auf CI-Jobs gemappt

Ergebnis

~40 Architektur-Dokumente: C4, Runtime-Pipelines, Building Blocks, ER-Diagramme, Runbooks
12 Risiken (R-01–R-12): Factory→DI unvollständig, API-Paritätslücken, Plugin-Ordering, ACL-Wachstum
8+ Tech-Debt-Items: ~1.838 PHPStan-Suppressions, dual Factory/DI, ~50 legacy triggerEvent-Call-Sites
Event-System: 3 koexistierende Dispatch-Stile identifiziert — REC-02 burn-down für Joomla 7.0
Single Source of Truth für Teams — ersetzt implizites Wissen, Resume-Prompts für Folge-Sessions

work/enterprise-core-system.md

.NET · SQL Server · Business-Capability-Mapping & Ablösungsanalyse

Landeskritisches Line-of-Business-System

.NETSQL ServerLegacyBusiness CapabilitiesSecurityStored Procedures

WRK highlightRund die Hälfte aller Stored Procedures wies keine Referenz in der Codebasis auf — bei ~12.000 DB-Objekten ein zentrales Ablösungsrisiko, das ohne systematisches Inventar und Capability-Mapping unsichtbar geblieben wäre. Erst die Evidenz schafft die Basis für eine belastbare Migrations- oder Ablösungsentscheidung.

Eine über ~20 Jahre gewachsene .NET-Anwendung als operatives Kernsystem einer nationalen Business Unit eines multinationalen Konzerns — ohne belastbare Übersicht, welche Geschäftsfälle tatsächlich abgedeckt sind. Geplante Ablösung, aber unklare Scope- und Risikobasis.

Technischer Ist-Zustand: mehrere Module mit quer verlaufenden Aufrufen untereinander, ~150 Datenbanktabellen und ~12.000 Stored Procedures — davon rund die Hälfte ohne nachweisbare Referenz in der Codebasis. Hardcodierte Zugangsdaten, auskommentierte Sicherheitsmechanismen, kein automatisierter Testbestand, keine Testumgebungen. Deployment über Pack-Skripte und manuellen Transport auf Produktionsserver — kein definierter Release-Prozess.

Optionen

Option A: Greenfield-Ablösung — nur vertretbar nach belastbarer Business-Capability-Map und Scope-Freeze
Option B: Strangler-Pattern entlang identifizierter Fachdomänen — schrittweise Entkopplung statt Big Bang
Option C: Analyse-first — Ist-Transparenz, SP-Traceability und Security-Assessment vor jeder Migrationsentscheidung
Dokumentation: arc42 via AGM; Schwerpunkte DB-Orphans, Modulkopplung, Security, Deployment-Prozess

Vorgehen

Bootstrap + Ist-Aufnahme: Modul-Landschaft, Technologie-Stack und Betriebsmodell dokumentieren
WRK-001: Stored-Procedure-Inventar — Abgleich DB-Objekte ↔ Code-Referenzen, Orphan-Klassifikation
WRK-002: Modul- und Abhängigkeitsanalyse — Queraufrufe, Zyklen und Kopplungscluster
WRK-003: Security-Assessment — hardcodierte Credentials, deaktivierte Schutzmechanismen, Angriffsflächen
WRK-004: Business-Capability-Mapping — Evidenz aus Code, DB-Objekten und Fachinterviews
WRK-005: Betriebs- und Deployment-Analyse — Pack-/Transport-Prozess, fehlende Stages, Release-Risiken

Ergebnis

Quantifizierte DB-Transparenz: ~12.000 Stored Procedures inventarisiert, ~50 % ohne Code-Referenz — hohes Ablösungs- und Migrationsrisiko
Modul-Kopplungsgraph mit Queraufrufen — keine isolierbare Fachdomäne ohne Vorarbeit identifizierbar
Security-Findings: hardcodierte Credentials, auskommentierte Schutzmechanismen — P0 vor jeder Produktionsänderung
Business-Capability-Register: dokumentierte vs. angenommene Abdeckung — Grundlage für Scope und Ablösungsreihenfolge
Betriebsbefund: fehlende Teststages und manuelles Deployment als strukturelle Blocker für sichere Evolution

work/global-address-gis.md

Java · PostgreSQL/PostGIS → Python · KI-gestützte Stack-Migration

Globales Lieferadressen-GIS

JavaPythonPostgreSQLPostGISGISKI-Migration

WRK highlightDie KI-gestützte Migration von Java/PostGIS auf Python mit interner GIS-Library verkürzte die Verarbeitungszeit von Stunden auf Sekunden — inklusive gehärteter Schnittstellen und einem Fehlerhandling mit systematischer Daten-Nacharbeit.

Eine Java-Anwendung mit PostgreSQL und PostGIS zur Verwaltung und Verarbeitung weltweiter Lieferadressen über Geodaten-Funktionen. Räumliche Abfragen und Adressvalidierungen liefen im Batch — mit Verarbeitungszeiten im Stundenbereich. Schnittstellen und Fehlerbehandlung entsprachen nicht mehr den Anforderungen an Betriebssicherheit und Weiterentwicklung.

Ziel: Technologie-Wechsel und Performance-Hebung ohne manuelles Neuschreiben im klassischen Projektumfang — Migration vollständig KI-gestützt, mit Validierung der funktionalen Äquivalenz und Datenqualität.

Optionen

Option A: Optimierung im Ist-Stack — Java/PostGIS-Tuning, Indexing, Query-Refactoring (begrenzter Performance-Spielraum)
Option B: Python-Greenfield mit eingebetteter GIS-Library statt DB-seitiger PostGIS-Logik (gewählt)
Option C: Hybrid — PostGIS als System of Record, neue Verarbeitungsschicht in Python
Umsetzung: KI-gestützte Migration End-to-End — Architektur, Code, Schnittstellen, Fehlerpfade

Vorgehen

Ist-Aufnahme: Java-Domain-Logik, PostGIS-Abfragen, Schnittstellenverträge und Batch-Abläufe dokumentieren
Zielarchitektur: Python-Service mit interner GIS-Library — Entkopplung von DB-gebundener Raumlogik
KI-gestützte Transformation: Modulweise Migration mit funktionaler Paritätsprüfung je Inkrement
Schnittstellen-Härtung: API-Verträge modernisiert, Eingabevalidierung und Autorisierung nachgezogen
Fehlerbehandlung: strukturierte Fehlerpfade, Retry-Logik und Nacharbeit-Prozesse für fehlerhafte Adressdaten
Abnahme: Performance-Benchmarks und Datenqualitäts-Checks gegen Referenzläufe

Ergebnis

Verarbeitungszeit von Stunden auf Sekunden reduziert — räumliche Adressoperationen produktionsfähig skaliert
Vollständige Stack-Migration Java/PostgreSQL/PostGIS → Python mit interner GIS-Library
Schnittstellen abgesichert und modernisiert — belastbare Verträge für angebundene Systeme
Fehlerhandling mit Nacharbeit der Daten — fehlerhafte Datensätze werden erfasst, klassifiziert und bereinigt
Nachweis: KI-gestützte Migration als durchgängiger Modernisierungspfad — nicht nur Analyse, sondern Umsetzung

work/community-platform.md

Dynamische Erweiterungen · Dienstplan & Ressourcenmanagement

Online-Community-Plattform

CommunityDienstplanRessourcenmanagementErweiterungModularKI-gestützt

WRK highlightStatt die gewachsene Community-Plattform zu ersetzen, wurden Dienstplan- und Ressourcenmanagement als dynamische, modular eingebettete Funktionen realisiert — mit klar abgegrenzten Domänen und ohne Eingriff in den Plattform-Kern.

Eine bestehende Online-Community-Plattform sollte um dynamische Funktionen erweitert werden — zur Organisation von Dienstplänen, Verfügbarkeiten und Ressourcen innerhalb verteilter Community-Strukturen. Die Ausgangslage: gewachsene Plattform mit festen Kernfunktionen, aber ohne modulare Bausteine für operative Planungsprozesse.

Anforderung: unterschiedlichste, miteinander verzahnte Komponenten — von Schichtplanung und Einsatzkoordination bis zu Ressourcenbelegung und Berechtigungslogik — nahtlos in die bestehende Community-Umgebung integriert, ohne die Stabilität des Kernsystems zu gefährden.

Optionen

Option A: Monolithische Erweiterung im Plattform-Kern — schnell, aber erhöhte Kopplung und Wartungsrisiko
Option B: Modulare Plugin-/Extension-Architektur mit klar abgegrenzten Domänen (gewählt)
Option C: Ausgelagerte Planungs-Services mit API-Anbindung an die Community-Plattform
Scope: Dienstplan-Komponenten, Ressourcenmanagement, dynamische Konfiguration je Community-Kontext

Vorgehen

Ist-Aufnahme: Extension Points, Datenmodell und Berechtigungskonzept der bestehenden Plattform
Domänenmodell: Dienstplan, Verfügbarkeit, Ressource, Einsatz — als Bounded Contexts abgegrenzt
Komponenten-Design: wiederverwendbare Bausteine für Planungs-, Zuweisungs- und Konfliktlogik
KI-gestützte Implementierung: dynamische Funktionen iterativ entwickelt und in die Plattform integriert
Schnittstellen: Einbettung in Community-UI, Rollen-/Rechtemodell und Benachrichtigungskanäle
Abnahme: Szenarien für Mehrfach-Communities, parallele Einsätze und Ressourcenkonflikte

Ergebnis

Dynamische Funktionsbausteine produktiv in der bestehenden Community-Plattform — ohne Kern-Refactoring
Dienstplan-Komponenten: Schichtplanung, Verfügbarkeiten und Einsatzzuweisung je Community-Kontext
Ressourcenmanagement: Belegung, Kapazitäten und Konfliktauflösung über vereinheitlichte Logik
Modulare Architektur — Erweiterungen isoliert wartbar, Kernplattform bleibt upgrade-fähig
Operative Entlastung: Planungsprozesse digitalisiert statt manuell über Inseltools koordiniert

Nächster Schritt

Ähnliche Ausgangslage?

Ob Security-Assessment, Architektur-Dokumentation oder Modernisierungsentscheidung — im Erstgespräch klären wir Scope und passende Leistungsbausteine.

Erstberatung vereinbaren