Brancheneinstufung2/gtm_architect_documentation.md

Dokumentation: GTM Architect Engine (v2.6)

1. Projektübersicht

Der GTM Architect ("Go-to-Market Architect") ist ein KI-gestütztes System zur Entwicklung umfassender Marktstrategien für neue technische Produkte (Schwerpunkt: Robotik & Facility Management).

Das System führt den Nutzer durch einen 9-stufigen Prozess – von der technischen Analyse über Business-Case-Modellierung bis hin zu fertigen Vertriebsunterlagen und Landingpages.

2. Architektur & Tech-Stack (Stand Jan 2026)

Das System ist als Microservice in die bestehende Docker-Umgebung integriert (gtm-app).

graph LR
    User[Browser] -- HTTP/JSON --> Proxy[Nginx :8090]
    Proxy -- /gtm/ --> NodeJS[Node.js Server :3005]
    NodeJS -- Spawn Process --> Python[Python Orchestrator]
    Python -- import --> Helpers[Core Engine (helpers.py)]
    Helpers -- Dual SDK --> Gemini[Google Gemini 2.0 Flash (Text)]
    Helpers -- Dual SDK --> Imagen[Google Imagen 4.0 (Text-to-Image)]
    Helpers -- Dual SDK --> GeminiImg[Google Gemini 2.5 Flash (Image-to-Image)]
    Python -- SQL --> DB[(SQLite: gtm_projects.db)]

Komponenten

1. Frontend (/gtm-architect):

   • Framework: React (Vite + TypeScript).
   • Features: Session History, Hard Fact Extraction UI und Markdown Upload.

2. Backend Bridge (server.cjs):

   • Runtime: Node.js (Express).
   • Funktion: Nimmt HTTP-Requests entgegen und startet Python-Prozesse (gtm_architect_orchestrator.py).

3. Logic Core (gtm_architect_orchestrator.py):

   • Runtime: Python 3.11+.
   • Verantwortlichkeit: Steuert den 9-Phasen-Prozess, verwaltet Payloads und interagiert mit der Datenbank. Nutzt helpers.py für alle KI-Interaktionen.

4. Core Engine (helpers.py):

   • Laufzeit: Python 3.11+.
   • Verantwortlichkeit: Abstrahiert die Komplexität der KI-API-Aufrufe. Stellt robuste, wiederverwendbare Funktionen für Text- und Bildgenerierung bereit.

5. Persistenz (gtm_projects.db):

   • Typ: SQLite. Speichert alle Phasen-Ergebnisse als JSON-Blobs in einer einzigen Tabelle.

3. Kernfunktionalität: Die AI Engine (helpers.py)

Das Herzstück des Systems ist die helpers.py-Bibliothek, die für Stabilität und Zukunftssicherheit konzipiert wurde.

3.1 Dual SDK Support

Um maximale Stabilität zu gewährleisten und gleichzeitig Zugriff auf die neuesten KI-Modelle zu haben, wird ein dualer Ansatz für die Google AI SDKs verfolgt:

• google-generativeai (Legacy): Wird bevorzugt für Text-Generierungs-Aufgaben (gemini-2.0-flash) verwendet, da es sich in diesem Setup als robuster erwiesen hat.
• google-genai (Modern): Wird für alle Bild-Generierungs-Aufgaben und als Fallback für die Text-Generierung genutzt.

3.2 Hybride Bildgenerierung

Die call_gemini_image-Funktion wählt automatisch die beste Methode basierend auf dem Input:

• Szenario A: Text-to-Image (Kein Referenzbild)
  • Modell: imagen-4.0-generate-001.
  • Anwendung: Generiert ein komplett neues Bild basierend auf einem textuellen Prompt (z.B. für Landingpage-Banner).
• Szenario B: Image-to-Image (Mit Referenzbild)
  • Modell: gemini-2.5-flash-image.
  • Anwendung: Platziert ein existierendes Produkt (via Upload) in eine neue, per Text beschriebene Szene. Der Prompt ist darauf optimiert, das Produktdesign nicht zu verändern.

4. Der 9-Phasen Prozess

Phase	Modus	Input	Output	Beschreibung
1	phase1	Rohtext / URL	Features, Constraints, Specs	Extrahiert technische Daten, Hard Facts (Specs) & erstellt DB-Projekt. Specs sind editierbar.
2	phase2	Phase 1 Result	ICPs, Data Proxies	Identifiziert ideale Kundenprofile.
3	phase3	Phase 2 Result	Whales, Rollen	Identifiziert Zielkunden & Buying Center.
4	phase4	Phase 1 & 3	Strategy Matrix	Entwickelt "Angles" und Pain-Points.
5	phase5	Alle Daten	Markdown Report	Strategie-Fixierung. Konsolidierter Report inkl. Specs & Phase 2 Insights.
6	phase6	Phase 1, 3, 4	Battlecards, Prompts	Generiert Einwandbehandlung & Bild-Prompts.
7	phase7	Phase 2, 4	Landing Page Copy	Erstellt Landingpage-Texte.
8	phase8	Phase 1, 2	Business Case	CFO-Argumentation, ROI-Logik.
9	phase9	Phase 1, 4	Feature-to-Value	Übersetzung technischer Features in Nutzen.

5. Sitzungs-Management

Das System verwaltet persistente Sitzungen in der SQLite-Datenbank:

• List: Abruf aller gespeicherten Projekte, angereichert mit extrahierten Metadaten wie Produktname, Kategorie und Beschreibung für eine informative Übersicht.
• Load: Vollständige Wiederherstellung des App-States (alle Phasen).
• Delete: Permanentes Entfernen aus der Datenbank.

6. Deployment & Betrieb

• Wichtig: Das Frontend wird im Build-Stage gebaut. Bei Änderungen an App.tsx muss der Container mit docker-compose up -d --build gtm-app neu gebaut werden.
• Backend: Änderungen an gtm_architect_orchestrator.py oder helpers.py erfordern keinen Build, nur einen Restart (docker restart gtm-app).

7. Historie & Fixes (Jan 2026)

• [UPGRADE] v2.6.2: Report Completeness & Edit Mode

  • Edit Hard Facts: Neue Funktion in Phase 1 ("Edit Raw Data") erlaubt die manuelle Korrektur der extrahierten technischen JSON-Daten.
  • Report-Update: Phase 5 Prompt wurde angepasst, um explizit die Ergebnisse aus Phase 2 (ICPs & Data Proxies) im finalen Report aufzuführen.
  • Backend-Fix: Korrektur eines Fehlers beim Speichern von JSON-Daten, der auftrat, wenn Datenbank-Inhalte als Strings vorlagen.

• [UPGRADE] v2.6.1: Stability & UI Improvements

  • White Screen Fix: Robuste Absicherung des Frontends gegen undefined-Werte beim Laden älterer Sitzungen (optional chaining).
  • Session Browser: Komplettes Redesign der Sitzungsübersicht zu einer übersichtlichen Listenansicht mit Icons (Reinigung/Service/Transport/Security).
  • URL-Anzeige: Die Quell-URL wird nun als dedizierter Link angezeigt und das Projekt automatisch basierend auf dem erkannten Produktnamen umbenannt.

• [UPGRADE] v2.6: Rich Session Browser

  • Neues UI: Die textbasierte Liste für "Letzte Sitzungen" wurde durch eine dedizierte, kartenbasierte UI (SessionBrowser.tsx) ersetzt.
  • Angereicherte Daten: Jede Sitzungskarte zeigt nun den Produktnamen, die Produktkategorie (mit Icon), eine Kurzbeschreibung und einen Thumbnail-Platzhalter an.
  • Backend-Anpassung: Die Datenbankabfrage (gtm_db_manager.py) wurde erweitert, um diese Metadaten direkt aus der JSON-Spalte zu extrahieren und an das Frontend zu liefern.
  • Verbesserte UX: Deutlich verbesserte Übersichtlichkeit und schnellere Identifikation von vergangenen Analysen.

• [UPGRADE] v2.5: Hard Fact Extraction

  • Phase 1 Erweiterung: Implementierung eines sekundären Extraktions-Schritts für "Hard Facts" (Specs).
  • Strukturiertes Daten-Schema: Integration von templates/json_struktur_roboplanet.txt.
  • Normalisierung: Automatische Standardisierung von Einheiten (Minuten, cm, kg, m²/h).
  • Frontend Update: Neue UI-Komponente zur Anzeige der technischen Daten (Core Data, Layer, Extended Features).
  • Sidebar & Header: Update auf "ROBOPLANET v2.5".

• [UPGRADE] v2.4:

  • Dokumentation der Kern-Engine (helpers.py) mit Dual SDK & Hybrid Image Generation.
  • Aktualisierung der Architektur-Übersicht und Komponenten-Beschreibungen.
  • Versionierung an den aktuellen Code-Stand (v2.4.0) angepasst.

• [UPGRADE] v2.3:

  • Einführung der Session History (Datenbank-basiert).
  • Implementierung von Markdown-Cleaning (Stripping von Code-Blocks).
  • Prompt-Optimierung für tabellarische Markdown-Ausgaben in Phase 5.
  • Markdown-File Import Feature.