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.

4.1 Anleitung: Anpassung der Strategie-Logik (Meta-Framework)

Das Herzstück der strategischen Qualität der App ist nicht in einer externen Datei gespeichert, sondern wurde als "Meta-Framework" direkt in die Anweisungen (Prompts) für die KI einprogrammiert. Dieses Framework besteht aus den strategischen Schlüsselfragen, die die KI beantworten muss, um eine GTM-Strategie zu erstellen.

Wenn sich Ihre grundlegende Marketing-Strategie weiterentwickelt, können Sie diese Logik anpassen, indem Sie die Prompts im Code ändern.

Wichtig: Dieser Prozess erfordert ein Verständnis der Programm-Logik und sollte sorgfältig durchgeführt werden.

Schritt-für-Schritt-Anleitung:

1. Quelldatei identifizieren: Die gesamte Logik befindet sich in der Datei gtm_architect_orchestrator.py.

2. Relevante Funktionen finden: Jede Phase des GTM-Prozesses hat eine eigene Python-Funktion (z.B. phase2, phase3, phase4 etc.). Innerhalb jeder dieser Funktionen gibt es eine Variable namens prompt. Das ist die Anweisung für die KI.

3. Prompt-Struktur verstehen: Die Prompts sind so aufgebaut, dass sie der KI strategische Leitplanken geben. Suchen Sie nach dem Abschnitt **Strategic Questions:** innerhalb des prompt-Blocks.

   Beispiel (Ausschnitt aus phase2):

   prompt = f"""
   PHASE 2: IDEAL CUSTOMER PROFILE (ICP) & DATA PROXIES - STRATEGIC ANALYSIS
   
   **Your Task:**
   Answer the following strategic questions to determine the Ideal Customer Profiles (ICPs).
   
   **Strategic Questions:**
   1.  **ICP Identification:** Based on the product's core capabilities, which 3 industries face the most significant operational challenges...?
   2.  **Rationale:** For each identified ICP, provide a concise rationale...
   3.  **Data Proxies:** How can we find these companies online...?
   
   {lang_instr}
   
   **Output:**
   Provide your analysis ONLY in the following JSON format: 
   {{"icps": [...], "dataProxies": [...]}}
   """
   

4. Strategische Fragen anpassen: Sie können die Fragen unter **Strategic Questions:** ändern, hinzufügen oder entfernen, um die Denkweise der KI zu steuern. Wenn Sie beispielsweise feststellen, dass die "Data Proxies" präziser sein müssen, könnten Sie die Frage 3 anpassen oder eine vierte Frage hinzufügen.

5. Output-Struktur beibehalten (KRITISCH!): Der Teil des Prompts, der mit **Output:** beginnt, definiert das JSON-Format, das die Funktion zurückgibt. Ändern Sie dieses Format NICHT, da sonst die nachfolgenden Phasen und das Frontend die Daten nicht mehr verarbeiten können. Die Anpassung erfolgt ausschließlich über die strategischen Fragen, die das Ergebnis inhaltlich beeinflussen.

6. Änderungen bereitstellen: Nachdem Sie die gtm_architect_orchestrator.py gespeichert haben, ist kein docker build notwendig. Ein einfacher Neustart des Containers aktiviert die neue Logik:

   docker restart gtm-app
   

Durch das Befolgen dieser Schritte können Sie die Kernlogik des GTM Architect selbstständig an neue strategische Anforderungen anpassen.

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.