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)
  • gtm_architect_orchestrator.py (Sideloading für Dev)
  • server.cjs (Sideloading für Dev)
  • helpers.py & config.py (Shared Libraries)

Starten / Neustarten

# Bauen und Starten
docker-compose up -d --build gtm-app proxy dashboard

# Nur Neustart nach Python-Änderungen (dank Sideloading)
docker-compose restart gtm-app

5. Wartung & Troubleshooting

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).

Fehler: "Project not saved"

• Ursache: Berechtigungsprobleme auf gtm_projects.db oder Datei fehlt.
• Lösung: Sicherstellen, dass die Datei auf dem Host existiert und gemountet ist (wurde im Setup-Prozess via touch erstellt).

Entwicklung

Änderungen am Prompting sollten ausschließlich in gtm_architect_orchestrator.py vorgenommen werden. Nach der Änderung reicht ein docker-compose restart gtm-app.