Brancheneinstufung2/gtm_architect_documentation.md

Dokumentation: GTM Architect Engine

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 6-stufigen Prozess – von der technischen Analyse bis hin zu fertigen Vertriebsunterlagen (Sales Enablement). Es basiert auf einer Hybrid-Architektur aus React (Frontend) und Python (Backend/Logic).

2. Architektur & Tech-Stack

Das System ist als Microservice in die bestehende Docker-Umgebung integriert.

graph LR
    User[Browser] -- HTTP/JSON --> Proxy[Nginx :8090]
    Proxy -- /gtm/ --> NodeJS[Node.js Server :3005]
    NodeJS -- Spawn Process --> Python[Python Orchestrator]
    Python -- API Call --> Gemini[Google Gemini API]
    Python -- SQL --> DB[(SQLite: gtm_projects.db)]

Komponenten

1. Frontend (/gtm-architect):

   • Framework: React (Vite + TypeScript).
   • UI-Library: Tailwind CSS, Lucide React Icons.
   • Funktion: State-Management, UI-Rendering, Markdown-Anzeige.
   • Besonderheit: Keine direkte KI-Kommunikation mehr (Refactoring v2). Sendet nur JSON-Payloads an das Backend.

2. Backend Bridge (server.cjs):

   • Runtime: Node.js (Express).
   • Funktion: Nimmt HTTP-Requests vom Frontend entgegen, startet das Python-Skript und streamt den Output zurück.
   • Wichtig: Timeout ist auf 600s (10 Minuten) erhöht, um lange KI-Generierungszeiten abzudecken.

3. Logic Core (gtm_architect_orchestrator.py):

   • Runtime: Python 3.10+.
   • Funktion: Enthält die gesamte Business-Logik und Prompt-Engineering.
   • Abhängigkeiten: helpers.py (für OpenAI/Gemini Wrapper), market_db_manager.py (Datenbank).

4. Persistenz (gtm_projects.db):

   • Typ: SQLite.
   • Schema: id (UUID), name (String), data (JSON Blob), timestamps.
   • Management: Erfolgt über market_db_manager.py.

3. Der 6-Phasen Prozess

Der Orchestrator (gtm_architect_orchestrator.py) steuert die folgenden Phasen über das Argument --mode.

Phase	Modus	Input	Output	Beschreibung
1	analyze_product	Rohtext / URL	Features, Constraints	Extrahiert technische Daten und prüft auf Portfolio-Konflikte.
2	discover_icps	Phase 1 Result	ICPs, Data Proxies	Identifiziert ideale Kundenprofile (Branchen) und wie man sie findet.
3	hunt_whales	Phase 2 Result	Whales (Firmen), Rollen	Identifiziert konkrete Zielkunden (Accounts) und Buying Center Rollen.
4	develop_strategy	Phase 1 & 3	Strategy Matrix	Entwickelt "Angles" (Aufhänger) und Pain-Points pro Segment.
5	generate_assets	Alle Daten	Markdown Report	Erstellt den finalen Strategie-Report.
6	generate_sales_enablement	Alle Daten	Battlecards, Prompts	Generiert Einwandbehandlung und Bild-Prompts für Marketing.

4. Deployment & Betrieb

Docker Integration

Der Service läuft im Container gtm-architect.

• Build: Multi-Stage Build (Node.js Builder -> Python Runtime).
• Optimierung: Nur /dist und Skripte landen im finalen Image.
• Mounts:
  • gtm_projects.db (Persistenz)
  • gemini_api_key.txt (API-Schlüssel)
  • gtm_architect_orchestrator.py (Sideloading für Dev)
  • server.cjs (Sideloading für Dev)
  • helpers.py & config.py (Shared Libraries)

Starten / Neustarten

Der beste Weg, um einen sauberen Neustart zu gewährleisten, ist der up-Befehl mit --build.

# Kompletten Stack neu bauen und starten (empfohlen)
docker-compose up -d --build

# Nur den gtm-app Service neu bauen & neu erstellen
# Das --force-recreate ist entscheidend, um sicherzustellen, dass der alte Container ersetzt wird.
docker-compose up -d --build --force-recreate gtm-app

# Build ohne Cache erzwingen (bei hartnäckigen Problemen)
docker-compose build --no-cache gtm-app && docker-compose up -d gtm-app

5. Wartung & Troubleshooting

Fehler: "White Screen" / Leere Seite nach Start

• Symptom: Der Browser zeigt eine leere Seite. In der Entwicklerkonsole erscheint ein 404 Not Found Fehler für index.css oder index.tsx.
• Ursache: Falsche Pfade in der gtm-architect/index.html. Die href und src Attribute für CSS und JS müssen relativ (./index.css) statt absolut (/index.css) sein.
• Lösung: Pfade in der index.html korrigieren und sicherstellen, dass in vite.config.ts die Option base: './' gesetzt ist. Anschließend den Container mit --build neu erstellen.

Fehler: Leere Listen / Keine API-Antwort im Frontend

• Symptom: Die App startet, aber nach dem Klick auf "Analyse starten" erscheinen keine Features oder Constraints. Es gibt keine Fehlermeldung.
• Ursache: Dem Python-Skript fehlt der API-Schlüssel. Das Skript config.py liest den Schlüssel aus der Datei /app/api_key.txt im Container. Wenn diese Datei fehlt, schlagen API-Aufrufe im Hintergrund fehl, und das Skript gibt eine leere Antwort zurück.
• Lösung: Sicherstellen, dass die docker-compose.yml den API-Schlüssel korrekt in den Container mountet: volumes: - ./gemini_api_key.txt:/app/api_key.txt.

Fehler: Code-Änderungen werden nicht übernommen (Stale Code)

• Symptom: Änderungen an Python- oder Node.js-Dateien haben keine Auswirkung im Container, selbst nach einem restart.
• Ursache: Ein Problem in der docker-compose.yml. Entweder ist der build context falsch gesetzt oder die volumes-Konfiguration für das Sideloading ist fehlerhaft. Ein zu breiter Mount wie - .:/app kann von den Dateien im Image überschrieben werden.
• Lösung:
  1. Den build context auf . setzen und das dockerfile spezifisch adressieren (gtm-architect/Dockerfile).
  2. volumes für jede zu sideloadende Datei einzeln und explizit definieren.
  3. Den Container mit docker-compose up -d --build --force-recreate gtm-app neu erstellen.

Fehler: "502 Bad Gateway"

• Ursache: Der Node.js Server oder Nginx hat den Request wegen Timeout abgebrochen.
• Lösung: Timeouts sind in nginx-proxy.conf und server.cjs auf 600s+ gesetzt. Prüfen, ob der Container läuft (docker ps).