Einseitige Architekturkarte für einen chaotischen Prototyp: eine praktische Methode

Warum chaotische Prototypen schwer zu reparieren sind ohne Karte

Ein chaotischer Prototyp ist auf eine sehr spezielle Art verwirrend. Nichts ist beschriftet, Ordnernamen klingen wichtig, sagen aber nichts aus, und das tatsächliche Verhalten versteckt sich hinter Helfern und kopiertem Code. Du klickst einen Button in der UI und drei API-Aufrufe werden ausgelöst, ein Hintergrundjob läuft, und Daten erscheinen in einer Tabelle, die scheinbar von woanders befüllt wird.

Wenn du versuchst, Probleme in so einem Repo zu beheben, rätst du oft nur. Raten ist teuer aus zwei Gründen: Du verschwendest Zeit, weil du der falschen Datei nachjagst, und du erzeugst neue Bugs, wenn du etwas änderst, das ungenutzt aussieht, aber stillschweigend die App am Laufen hält.

Eine einseitige Architekturkarte hilft, weil sie allen dasselbe Bild davon gibt, wie die App im Kern funktioniert. Es ist kein perfektes Diagramm und keine Dokumentation für jede Klasse. Es ist eine gemeinsame Referenz, damit das Team über dasselbe spricht.

Ohne Karte werden Fixes oft zu:

• Änderungen am Code in der Nähe des Fehlers, nur um dann zu entdecken, dass die eigentliche Ursache zwei Schritte vorher liegt
• dieselbe Schwachstelle an mehreren Stellen zu patchen, weil Logik dupliziert ist
• Authentifizierung, Zahlungen oder E-Mails zu zerstören, weil eine „kleine“ Änderung geteilte Middleware berührt hat
• externe Abhängigkeiten wie Webhooks, Queues oder Drittanbieter-Speicher zu übersehen

Dieser Ansatz ist besonders nützlich, wenn der Codebestand vererbt wurde, in Eile entstand oder von Tools generiert wurde, die funktionale Demos mit wackeliger Struktur produzieren. Viele KI-generierte Prototypen fallen in diese Kategorie: Abläufe sind implizit, und Secrets, Auth und Datenregeln sind verteilt.

Ein kurzes Beispiel: Eine Gründerin meldet „Anmeldung funktioniert lokal, in Produktion nicht.“ Ohne Karte ist man leicht versucht, sich auf das Login-Formular zu fokussieren. Mit einer Karte sieht man den ganzen Pfad: UI -> Auth-Route -> Datenbankabfrage -> Cookie- oder Token-Setzen -> Middleware-Check bei der nächsten Anfrage. Diese Sicht zeigt oft, wo der Flow tatsächlich bricht.

Was eine einseitige Architekturkarte nützlich macht

Eine einseitige Architekturkarte funktioniert, wenn jemand sie in 60 Sekunden lesen kann und sagt: „Ja, so funktioniert es.“ Wenn alle der Geschichte zustimmen, hört das Team auf, über Vermutungen zu streiten, und beginnt, die richtigen Schritte zu testen.

Die besten Karten verwenden einfache Worte. Anstatt Ordnernamen wie src/services/authV2, beschrifte ein Kästchen mit „Login und Sessions“. Anstelle von api/routes schreibe „HTTP-Endpunkte“. Das macht die Karte für nicht-technische Kollegen lesbar und zwingt dich, zu benennen, was der Code wirklich tut.

Eine Einseiter-Karte verhindert auch Überdokumentation. Zeige nur die Pfade, die für das Business und die Bugs wichtig sind, die du jagst. Die meisten Prototypen haben einige kritische Journeys; alles andere kann warten.

Beginne mit den Flows, die normalerweise darüber entscheiden, ob die App funktioniert:

• Anmeldung und Kontoerstellung
• der Kern-Workflow (das Hauptfeature, für das Nutzer kommen)
• Zahlungen (falls du Geld verlangst)
• E-Mails, Benachrichtigungen oder Webhooks
• Uploads und Downloads (falls Dateien eine Rolle spielen)

Pfeile schlagen Absätze. Ein Pfeil sollte beantworten: wer ruft wen auf, welche Daten gehen rein und was kommt raus. „Browser -> API -> Datenbank“ plus ein kurzer Hinweis wie „erstellt Benutzer-Datensatz“ ist oft nützlicher als eine Seite Text.

Sammle schnelle Hinweise bevor du viel Code liest

Wenn ein Prototyp wenig oder keine Dokumentation hat, ist deine erste Aufgabe nicht, jede Funktion zu verstehen. Deine erste Aufgabe ist herauszufinden, was die App vorgibt zu tun, wovon sie abhängt und wo sie die Außenwelt berührt.

Fange mit Dateien an, die dem Projekt „verraten“. Ein README (auch ein schlechtes) kann Hauptfunktionen, Hosting-Setup oder bekannte Probleme erwähnen. Abhängigkeitsdateien wie package.json, requirements.txt oder Lockfiles zeigen schnell Framework, Datenbanktreiber, Auth-Bibliotheken, Tools für Hintergrundjobs und SDKs für Zahlungen oder E-Mail.

Dann überprüfe, wie die App konfiguriert wird. Suche nach .env.example, Konfigvorlagen, Docker-Dateien und Hinweisen zu Secrets. Hier entdeckst du oft fehlende Keys, falsche Callback-URLs oder hardcodierte Tokens, die lokal funktionieren und nach dem Deployment fehlschlagen.

Wenn du eine schnelle Checkliste willst, konzentriere dich auf:

• Woran es läuft: Framework und Laufzeit (aus Abhängigkeitsdateien)
• Wie Anfragen reinkommen: Seiten, API-Endpunkte, Webhooks, geplante Tasks
• Wo Daten liegen: Migrations-, Schema-Dateien, Seed-Skripte, ORM-Modelle
• Womit es spricht: Auth, Zahlungen, E-Mail, Dateispeicherung, Analytics
• Wie es laufen soll: Deployment-Konfigurationen, CI-Dateien, „start“-Skripte

Beispiel: Eine KI-generierte App „funktioniert lokal“, aber Nutzer können sich in Produktion nicht einloggen. Bevor du tief in den Code gehst, entdeckst du ein Auth-SDK in package.json, Callback-URLs in der Env-Vorlage und eine /api/auth-Route, die ein fehlendes SECRET erwartet. Das reicht, um die Schlüsselketten grob zu skizzieren und ein echtes Risiko zu markieren, wenn Secrets exponiert sind.

Finde die Einstiegspunkte und Hauptnutzerflüsse

Wenn du von zufälligen Dateien startest, verpasst du, wie Leute die App tatsächlich nutzen. Beginne bei den Einstiegspunkten: den ersten Stellen, an denen ein echter Nutzer oder ein System deinen Code berührt.

Starte mit Nutzer-Einstiegspunkten

Suche die Bildschirme, die die meisten Zustandsänderungen auslösen: Landing-Page, Sign-up/Sign-in, der Haupt-„Arbeits“-Bildschirm und etwaige Admin-Bereiche. Selbst in einem chaotischen Prototypen offenbaren diese Flows meist die Kern-Datenobjekte (Nutzer, Projekte, Zahlungen, Dateien) und die wichtigen Entscheidungen (eingeloggt vs. nicht, gratis vs. bezahlt, rollenbasierter Zugriff).

Eine praktische Art, den Flow zu bestätigen, ist zu folgen, was nach einem Button-Klick passiert: wohin wird der Nutzer gesendet, welcher API-Call feuert und was wird gespeichert (Cookie, Session, Local Storage, Datenbankzeile)?

Erfasse dann technische Einstiegspunkte

Parallel liste jede Tür in das Backend auf. Diese sind oft der Grund, warum Prototypen in Produktion scheitern.

• UI-Routen und Hauptseiten (inkl. Admin)
• API-Routen (REST/GraphQL), Server-Aktionen, Edge-Funktionen
• Auth-Callbacks (OAuth-Redirects, Magic Links)
• Webhooks von Partnern (Zahlungen, E-Mail-Provider, CRM)
• Automatisierungen (Cron-Jobs, Queues, geplante Tasks)

Externe Aufrufer sind wichtig. Ein Browser ist nicht der einzige Client; eine Mobile-App, ein internes Admin-Tool oder ein Partnersystem könnte dieselben Endpunkte mit anderen Annahmen aufrufen.

Beispiel: Eine KI-generierte App lässt dich lokal „Sign in“, aber in Produktion zeigt die OAuth-Callback-URL auf die falsche Domain. Markiere diesen Callback als Einstiegspunkt und füge eine Notiz daneben: „Muss mit deployed URL übereinstimmen, sonst Login-Loop.“

Liste die Schlüsselmodule ohne dich im Ordnerchaos zu verlieren

Chaotische Prototypen wirken oft größer, als sie sind. Eine schnelle Möglichkeit, Kontrolle zu gewinnen, ist, Code nach Funktion und nicht nach Ordnerbaum zu gruppieren. Dein Ziel sind wenige Module, die auf eine Seite passen.

Beginne damit, nach „Gravitationszentren“ zu suchen: Dateien, die viele andere importieren oder aufrufen. Sie zeigen meist die echten Modulgrenzen, auch wenn die Repo-Struktur zufällig ist.

Eine einfache Modulübersicht ist:

• UI: Seiten, Komponenten, Formulare und Stellen, wo Netzwerkrequests ausgelöst werden
• API-Oberfläche: Route-Handler, Controller, Middleware, Request-Validation
• Business-Logik: Workflows wie „Konto erstellen“ oder „Checkout“, plus Hintergrundjobs
• Datenzugriff: ORM-Modelle, rohe Queries, Migrationen, Caching, Datei-Uploads
• Integrationen: Auth, Zahlungen, E-Mail/SMS, Analytics, Logs

Nachdem du diese Buckets hast, weise Dateien schnell zu. Wenn eine Datei zu zwei Bereichen zu gehören scheint, markiere sie als „Boundary“ und mach weiter. Boundary-Dateien sind oft die Orte, an denen Bugs versteckt sind (z. B. UI-Komponenten, die unsichere Filter bauen, oder API-Routen mit Zahlungsregeln).

Beispiel: Ein KI-generierter Prototyp hat vielleicht einen utils-Ordner mit 40 Dateien. Beim Überfliegen siehst du Cluster, die tatsächlich „E-Mail-Versand“, „Auth-Helper“ und „Datenformatierung“ sind. Diese Cluster sind deine Module, selbst wenn die Ordner etwas anderes behaupten.

Schritt-für-Schritt-Methode, um die Karte aus dem Code zu skizzieren

Eine gute einseitige Architekturkarte baut sich aus beobachtetem Verhalten, nicht aus Ordnernamen. Die schnellste Methode ist: Wähle einen Flow, folge ihm Ende-zu-Ende und zeichne nur, was du nachweisen kannst.

Starte mit einem Flow, den du tatsächlich zurückverfolgen kannst

Wähle einen einzelnen Kern-Flow mit klarem Anfang und Ende, z. B. Sign-up bis zur ersten erfolgreichen Aktion (Projekt erstellen, Datei hochladen, Bestellung aufgeben). Finde den ersten Einstiegspunkt für diesen Flow: eine Seite, Route, ein Controller oder ein API-Endpunkt.

Verfolge dann jeden Hop in der Reihenfolge und mach aus jedem Hop ein Kästchen. Sorge dich nicht um perfekte Namen. Nutze, wie der Code es nennt (z. B. auth.ts, createProject, POST /api/upload). Wenn du einen Hop nicht nachvollziehen kannst, stoppe und markiere ihn als „unbekannt“ statt zu raten.

Notiere neben jedem Kästchen ein paar Wesentlichkeiten:

• was es auslöst (Button-Klick, API-Call, Cron-Job, Webhook)
• was es zurückgibt (Redirect, JSON, Datei-URL, Fehler)
• wo Zustand geändert wird (Datenbanktabelle, Cookie, Local Storage)
• das Hauptrisiko oder die Annahme (fehlende Validierung, Vertrauen in Client-Input)

Füge Services und Vertrauensgrenzen als eigene Formen hinzu

Externe Dienste verdienen eigene Kästchen, weil sie anders versagen als dein Code. Häufige Beispiele: Auth-Provider, Payment-Processor, E-Mail/SMS, Object Storage, Analytics.

Markiere Vertrauensgrenzen mit einfachen Labels an den Kanten, wie „Browser zu Server“ und „Server zu Drittanbieter“. Das hilft, Stellen zu erkennen, an denen Secrets, Tokens und personenbezogene Daten in Bereiche wandern, die du nicht kontrollierst.

Wiederhole die Methode für zwei oder drei weitere kritische Flows, bis die Seite „gefüllt“ wirkt, aber noch lesbar bleibt. Login, Passwort-Reset und die Haupt-Create- oder Checkout-Aktion reichen gewöhnlich aus.

Füge Sicherheits- und Datenschutzhinweise beim Mapping hinzu

Eine einseitige Architekturkarte ist nicht nur Kästchen und Pfeile. Füge kleine Sicherheitsnotizen direkt in die Zeichnung ein, solange der Code noch frisch im Kopf ist. Diese Notizen erklären oft, warum ein Prototyp im Demo-Modus funktioniert, aber in Produktion bricht (oder gefährlich wird).

Beginne mit Authentifizierung. Markiere, wo Login passiert, was die Session oder das Token erstellt und welche Endpunkte davon abhängen. Bei Passwort-Reset oder OAuth notiere den Callback-Route und wo die App State speichert (Cookies, Local Storage, Server-Session).

Suche dann nach Secrets. Schreib auf, wo API-Keys und Connection-Strings liegen und wo sie eventuell auslaufen könnten. In chaotischen Prototypen landen Keys oft im Client-Code, in committeten Konfigdateien, Debug-Logs oder Fehlermeldungen.

Verfolge dann Benutzereingaben beim Eintritt ins System. Markiere jede Grenze, wo untrusted Daten auftauchen: Formulare, Query-Strings, Webhooks, Datei-Uploads, Drittanbieter-Callbacks. Füge je eine Notiz hinzu: „auf Server validiert“ oder „nur UI“.

Für Datenbanksicherheit markiere, wo Queries gebaut werden. Wenn du rohe SQL-Strings, dynamische Filter oder String-Konkatenation siehst, flagge das auf der Karte. Das ist eine häufige Quelle für SQL-Injection und Datenlecks.

Schließlich notiere Autorisierungen. Nur weil eine Route „hinter Auth“ liegt, heißt das nicht automatisch, dass Authorization geprüft ist. Markiere, wo Rollenprüfungen, Ownership-Checks (Nutzer darf nur eigene Datensätze sehen) und Admin-Aktionen durchgesetzt werden.

Eine kurze Annotation-Checkliste:

• Auth-Typ und wo er geprüft wird
• wo Secrets liegen und ob welche exponiert sind
• wo Validierung stattfindet
• wie die DB abgefragt wird (ORM vs rohe SQL)
• wo Autorisierungsregeln durchgesetzt werden

Häufige Fehler, die die Karte irreführend machen

Das Ziel ist Klarheit, nicht Vollständigkeit. Die schnellste Art, eine einseitige Karte zu ruinieren, ist, sie wie ein Dateiverzeichnis zu behandeln. Am Ende hast du eine dichte Seite, die trotzdem nicht erklärt, wie die App sich verhält.

Eine andere Falle ist, Kästchen nach Tools zu benennen statt nach Verhalten. „Next.js + tRPC + Prisma“ sagt einem Entwickler, was verwendet wurde, aber nicht, was passiert, wenn sich ein Nutzer anmeldet, eine Datei hochlädt oder auscheckt. Eine Karte sollte wie eine einfache Geschichte lesbar sein: wer ruft wen auf, welche Daten bewegen sich und was kann fehlschlagen.

Häufige Fehler:

• alle Ordner zeichnen und die wenigen wichtigen Flows (Sign-in, Zahlungen, Admin-Aktionen, Onboarding) übersehen
• Kästchen nach Tech-Stack benennen statt nach Aktionen („Create invoice“ ist besser als „Backend service")
• stille Pfade wie Cron-Jobs, Queues und eingehende Webhooks vergessen, die nur in Produktion fehlschlagen
• Umgebungen vermischen (lokale Mocks, Fake-Keys, Dienste, die nach Deployment nicht existieren)
• das Datenmodell weglassen und sich dann wundern, warum Business-Logik sich auf verschiedenen Screens widerspricht

Annahmen sind nicht das Problem; versteckte Annahmen sind es. Wenn du unsicher bist, ob „E-Mails von Provider A gesendet werden“ oder „ein Job stündlich läuft“, schreibe es als „angenommen“ oder „unbekannt“. Das macht Verwirrung zu einer klaren To‑Do.

Schnelle Checks, bevor du die Karte teilst

Bevor du die Karte an ein Teammitglied oder einen Kunden schickst, mach einen kurzen Wahrheitscheck. Ziel ist nicht Perfektion, sondern sicherzustellen, dass die Seite die Wahrheit sagt und auf die richtigen Fragen zeigt.

Probier das: Kannst du den Hauptnutzerfluss in unter zwei Minuten nur mit dem, was auf der Seite steht, erklären? Wenn du ständig „und dann passiert irgendwas“ sagst, füge ein fehlendes Kästchen oder einen Pfeil hinzu.

Fünf Checks, die die meisten Probleme auffangen:

• jeder externe Dienst erscheint irgendwo (Auth, E-Mail/SMS, Zahlungen, Dateispeicher, Analytics)
• mindestens ein klares „Datenspeicher“-Kästchen existiert (Datenbank, Object Storage) mit Lese-/Schreibpfeilen
• Vertrauensgrenzen sind sichtbar (Client, dein Server, Drittparteien)
• Einstiegspunkte sind offensichtlich (Routen, Endpunkte, Jobs, Webhooks)
• die größten Risiken sind sichtbar (Auth/Session-Handling, Secrets, Eingabevalidierung)

Füge danach eine kleine „Unbekannt“-Ecke mit bis zu fünf Punkten hinzu. Mach sie konkret, damit jemand sie schnell bestätigen kann.

Beispiel: Mapping eines KI-generierten Prototyps, der in Produktion bricht

Eine Gründerin erbt einen Bolt- oder Lovable-Prototyp, der lokal gut aussieht, im Deployment aber auseinanderfällt. Nutzer können die Landing-Page öffnen, aber die Registrierung schlägt fehl und niemand kann sich einloggen.

Fange mit einer echten Nutzeraktion an: „Account erstellen.“ Du brauchst keine perfekten Kästchen, sondern wenige Kästchen, die erklären, wer mit wem spricht und wo Daten geändert werden.

Eine typische Karte für diese Situation enthält:

• Browser-UI (Signup-Formular) ruft eine Server-Aktion oder API-Route auf
• Server-Code spricht mit einem Auth-Provider und erhält einen Callback
• Server schreibt eine User-Zeile in die Datenbank
• ein E-Mail-Dienst sendet Verifikationsmails
• Environment-Variablen liefern Keys und Callback-URLs

Verfolge dann den fehlerhaften Schritt in Produktion. Die UI submit­t, der Server redirectet zum Auth-Provider, der Callback kommt zurück an eine andere Domain als erwartet, weil die Callback-URL noch auf localhost gesetzt ist. In schlimmeren Fällen enthält das Client-Bundle ein Auth-Secret, weil es in einer öffentlichen Env-Var lag.

Während du mapst, füge kleine rote-Flag-Notizen hinzu, die die ersten Fixes offensichtlich machen:

• exposed secret in client-side config
• fehlende Rollen- oder Ownership-Checks auf sensiblen Endpunkten
• inkonsistente Tabellennamen (users vs user, profile vs profiles)
• Auth-Callbacks zeigen auf localhost oder falsche Domain

Das Ergebnis ist kein hübsches Diagramm. Es ist Klarheit und eine sicherere Reihenfolge der Fixes.

Nächste Schritte: Verwandle die Karte in einen Reparaturplan

Eine einseitige Architekturkarte zählt nur, wenn sie beeinflusst, was du als Nächstes tust. Nutze sie, um „zufälliges Bugfixing“ in eine klare Arbeitsreihenfolge zu verwandeln, sodass du die blockierendsten Risiken zuerst angehst.

Eine praktische Reihenfolge für die meisten chaotischen Prototypen:

• Authentifizierung und Sessions stabilisieren (Login, Rollen, Token-Speicherung, Passwort-Reset)
• das Datenmodell bestätigen (Tabellen, Relationen, Migrationen, Validierungspunkte)
• den Kernnutzerfluss reparieren (die eine Aktion, die das Produkt End-to-End können muss)
• Extras behandeln (Benachrichtigungen, Analytics, Admin-Tools)

Dann entscheide, ob du patchen, refaktorieren oder neu bauen solltest:

• Patchen, wenn der Flow klar ist und Probleme isoliert sind (eine kaputte Integration, ein paar fehlerhafte Queries).
• Refaktorieren, wenn die App funktioniert, aber die Struktur jede Änderung erschwert (duplizierte Logik, unklare Grenzen).
• Neu bauen, wenn die Karte Spaghetti-Architektur zeigt (alles spricht mit allem, Secrets sind verstreut, kein sicherer Ort für Checks).

Halte die Einseiter-Karte aktuell, während du reparierst. Jedes Mal, wenn du Verantwortung verschiebst (z. B. zentralen DB-Zugriff einführen oder Auth-Checks in Middleware ziehen), aktualisiere die Karte, damit das Team nicht wieder in Raten verfällt.

Wenn du eine zweite Meinung zu einem KI-generierten Codebestand willst, beginnt FixMyMess (fixmymess.ai) mit einer Codebasis-Diagnose und kann helfen, Probleme wie kaputte Authentifizierung, exponierte Secrets und unsicheren Datenzugriff zu reparieren, bevor du Zeit in Rewrites steckst.