Architektur

CodeDocumentation ist als asynchrone Drei-Phasen-Pipeline aufgebaut, die in einer Gradio-Oberfläche zusammengeführt wird. Die Trennung zwischen statischer Inspektion, modellgestützter Code-Analyse und narrativer Erzeugung folgt einer schichtweisen Aufteilung; die Anwendung läuft als einzelner Container und kann hinter einem Reverse-Proxy unter einem Pfad-Präfix betrieben werden.

Auf einen Blick

• Drei klar getrennte Pipeline-Phasen mit unterschiedlichen Modell-Anforderungen
• Asynchrone Verarbeitung in der Analysephase mit semaphore-begrenzter Parallelität
• Zwei getrennte Sprachmodell-Clients in einer gemeinsamen Wrapper-Klasse mit Retry und Thinking-Block-Behandlung
• Einheitliche Datenmodelle (Dataclasses) als Schnittstelle zwischen den Phasen
• Plug-in-Stelle für framework-spezifische Endpunkt-Extraktoren über eine Registry
• Containerisiert über Dockerfile auf Basis Python 3.11 mit konfigurierbarem Port
• Sechs unabhängige Dokumenten-Generatoren plus Mermaid-Builder und Projekt-Klassifizierer

Architekturbeschreibung

Schichten und Komponenten

Die Anwendung gliedert sich in fünf logische Schichten:

• Präsentation — Eine Gradio-Blocks-Oberfläche mit zwei Tabs („Input & Configuration", „Results"), Fortschrittsanzeige, Datei-Vorschau (gerendert und als Quelltext) und ZIP-Download. Quellauswahl und Modell-Konfiguration werden in Akkordeons gruppiert.
• Orchestrierung — Die Pipeline-Funktion run_pipeline koordiniert den Ablauf, übergibt Fortschritts-Callbacks an die Phasen und kapselt die Fehlerbehandlung. Sie ist asynchron implementiert und nutzt Gradio-Progress-Reporting.
• Inspektion (Phase 1) — Ein Source-Loader nimmt die gewählte Eingangsquelle entgegen und stellt ein Arbeitsverzeichnis bereit. Anschließend laufen Verzeichnis-Walker und mehrere Detektoren (Sprache, Framework, Konfiguration, Abhängigkeiten, Build-Dateien, CI, vorhandene Dokumentation) ohne Modellaufruf.
• Analyse (Phase 2) — Ein Datei-Analyzer ruft das schnelle Modell parallel pro Datei auf; die Antworten werden defensiv als JSON geparst. Parallel laufen framework-spezifische Endpunkt-Extraktoren deterministisch. Ein Wichtigkeits-Scorer und ein Aggregator verdichten die Ergebnisse zu Paket-Strukturen und einem API-Katalog.
• Erzeugung (Phase 3) — Ein Projekt-Klassifizierer und sechs einzelne Dokumenten-Generatoren rufen das Thinking-Modell für die jeweiligen Abschnitte auf. Ein Mermaid-Builder erzeugt das Architektur-Diagramm. Abschließend werden alle Dokumente in ein ZIP-Archiv gepackt.

Komponenten- und Datenfluss-Diagramm

flowchart TB
    UI["Gradio-Oberfläche"]
    ORCH["Pipeline-Orchestrierung"]
    UI --> ORCH

    subgraph Quellen
        SRC1["Lokales Verzeichnis"]
        SRC2["ZIP-Upload"]
        SRC3["GitLab REST API"]
    end

    LOADER["Source Loader"]
    SRC1 --> LOADER
    SRC2 --> LOADER
    SRC3 --> LOADER
    ORCH --> LOADER

    subgraph P1["Phase 1 — Inspektion"]
        WALK["Directory Walker"]
        DETLANG["Sprache und Framework"]
        DETDEP["Abhängigkeiten"]
        DETCFG["Konfiguration"]
        DETBUILD["Build und CI"]
    end
    LOADER --> WALK
    WALK --> DETLANG
    WALK --> DETDEP
    WALK --> DETCFG
    WALK --> DETBUILD

    META["ProjectMetadata"]
    DETLANG --> META
    DETDEP --> META
    DETCFG --> META
    DETBUILD --> META

    subgraph P2["Phase 2 — Code-Analyse"]
        FILEAN["Per-File-LLM-Analyse"]
        FRAMEX["Framework-Extraktoren"]
        SCORE["Wichtigkeits-Scorer"]
        AGG["Aggregator"]
    end
    META --> FILEAN
    META --> FRAMEX
    FILEAN --> SCORE
    FRAMEX --> AGG
    SCORE --> AGG

    LLMFAST["LLM-Client - schnell"]
    FILEAN <--> LLMFAST

    P2RES["Phase2Result"]
    AGG --> P2RES

    subgraph P3["Phase 3 — Erzeugung"]
        CLASS["Projekt-Klassifizierer"]
        GEN["Dokumenten-Generatoren"]
        MERM["Mermaid-Builder"]
        REPORT["Generierungs-Report"]
    end
    META --> CLASS
    P2RES --> CLASS
    META --> GEN
    P2RES --> GEN
    CLASS --> GEN
    GEN --> MERM

    LLMSLOW["LLM-Client - Thinking"]
    CLASS <--> LLMSLOW
    GEN <--> LLMSLOW

    OUT["Markdown-Dateien"]
    GEN --> OUT
    MERM --> OUT
    REPORT --> OUT

    ZIPOUT["ZIP-Archiv"]
    OUT --> ZIPOUT
    ZIPOUT --> UI

Workflow

Der Anwender wählt in der Oberfläche eine Quelle, konfiguriert beide Sprachmodell-Endpunkte und stößt den Lauf an. Der Source Loader stellt das Projekt in einem Arbeitsverzeichnis bereit. Phase 1 inspiziert dieses Verzeichnis ohne Modellaufruf und erzeugt ein Metadaten-Objekt. Phase 2 verwendet dieses Objekt, um pro Sprache zunächst die framework-spezifischen Extraktoren laufen zu lassen und parallel das schnelle Modell auf jede Datei anzuwenden. Die ermittelten Endpunkte werden mit den Datei-Analysen verbunden, dedupliziert und in einem API-Katalog aggregiert. Phase 3 fragt das Thinking-Modell zunächst zur Projekt-Charakterisierung an und erzeugt anschließend die einzelnen Dokumente, eingebettet in eine deterministische Datei-Struktur. Der Mermaid-Builder fügt das Architektur-Diagramm in das entsprechende Dokument ein. Zum Abschluss wird ein Generierungs-Report mit Laufzeit, Modellaufrufen und Token-Verbrauch erzeugt und alles in ein ZIP-Archiv gepackt, das in der Oberfläche zum Download bereitsteht.

Rolle der Sprachmodelle

Die Anwendung nutzt zwei Modell-Endpunkte mit klar getrennten Rollen.

• Schnelles Modell (Phase 2) — Pro analysierter Datei ein Aufruf, parallelisiert über eine konfigurierbare Semaphore. Erwartet wird strukturiertes JSON mit Zweck, öffentlicher API und bemerkenswerten Eigenschaften. In dieser Phase fallen pro Lauf zwischen einigen Dutzend und einigen Hundert Aufrufen an.
• Thinking-Modell (Phase 3) — Wenige Aufrufe pro Lauf, jeweils mit längerer Antwortlänge für Fließtext-Abschnitte und das Mermaid-Diagramm. Der nicht-standardisierte enable_thinking-Parameter wird per extra_body an die OpenAI-kompatible Schnittstelle weitergereicht.

Beide Aufrufe werden über denselben Wrapper geführt, der <think>-Blöcke entfernt, JSON robust extrahiert, bei Fehlern mit exponentiellem Backoff wiederholt und Aufrufe sowie Tokens je Rolle zählt.

Nebenläufigkeit und Robustheit

Die Pipeline ist durchgängig asynchron implementiert. Die Datei-Analyse in Phase 2 läuft parallel über asyncio.gather, beschränkt durch eine Semaphore (Standardwert in der Oberfläche einstellbar). Modell-Antworten werden defensiv geparst: JSON in Markdown-Fences wird automatisch befreit, eingebettetes JSON über regulären Ausdruck extrahiert. Fehler in einzelnen Dateien führen zu einer Markierung des Status error ohne Abbruch des Gesamtlaufs. Fehlende oder leere Modell-Antworten werden geloggt; Endpunkte werden über das Tupel (Methode, Pfad) dedupliziert.

Konfiguration und Deployment

Die Konfiguration erfolgt über Umgebungsvariablen oder die Oberfläche; beide Modell-Endpunkte sind getrennt einstellbar (URL, Modellname, optionaler API-Key, Thinking-Modus). Bind-Adresse, Port und Reverse-Proxy-Pfad-Präfix werden ebenfalls über Umgebungsvariablen gesetzt. Die Anwendung wird als einzelner Container betrieben (Basis-Image python:3.11-slim) und exponiert standardmäßig den Port 7870. Temporäre Arbeitsverzeichnisse werden je Lauf angelegt und nach Abschluss durch das Betriebssystem aufgeräumt.

Erweiterbarkeit

Neue Frameworks werden durch eine zusätzliche Extractor-Klasse mit drei Pflichtmethoden (name, language, extract_endpoints), einen Eintrag in der Extractor-Registry und ein Erkennungssignal im Framework-Detektor eingebunden. Die übrige Pipeline und die Oberfläche bleiben unverändert.

Technologie-Übersicht

• Sprache und Laufzeit — Python 3.11
• Oberfläche — Gradio (gr.Blocks-Oberfläche, asynchrone Event-Handler)
• Sprachmodell-Anbindung — openai-Async-Client gegen OpenAI-kompatible Endpunkte; extra_body für nicht-standardisierte Parameter wie enable_thinking
• HTTP-Client — httpx für GitLab-REST-API-Zugriff (Streaming-Download)
• Datenformate — YAML (PyYAML) und TOML (tomllib/tomli) für Phase-1-Parser; JSON für Modell-Antworten; Markdown als Ausgabe
• Diagramme — Mermaid, eingebettet als Code-Block
• Templating — Jinja2 für Dokumenten-Bausteine
• Containerisierung — Dockerfile auf Basis python:3.11-slim, exponierter Port 7870