Dokumentation: GTM Architect Engine (v2.4)

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

Frontend (/gtm-architect):
- Framework: React (Vite + TypeScript).
- Features: Session History (Laden/Löschen alter Projekte) und Markdown Upload.
Backend Bridge (server.cjs):
- Runtime: Node.js (Express).
- Funktion: Nimmt HTTP-Requests entgegen und startet Python-Prozesse (gtm_architect_orchestrator.py).
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.
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.
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	Extrahiert technische Daten & erstellt DB-Projekt.
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.
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 mit Zeitstempel.
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.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.

5.5 KiB Raw Blame History Unescape Escape