Brancheneinstufung2/gtm_architect_documentation.md

Dokumentation: GTM Architect Engine (v2)

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 nun erweiterten 9-stufigen Prozess – von der technischen Analyse über Business-Case-Modellierung bis hin zu fertigen Vertriebsunterlagen und Landingpages. Es basiert auf einer Hybrid-Architektur aus React (Frontend) und Python (Backend/Logic), verbunden durch eine Node.js-Bridge.

2. Architektur & Tech-Stack

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 -- 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.
   • NEU: Alle API-Aufrufe gehen an /api/run im lokalen Node.js-Server. Keine direkte Google-API-Kommunikation.

2. Backend Bridge (server.cjs):

   • Runtime: Node.js (Express).
   • Funktion: Nimmt HTTP-Requests vom Frontend entgegen, decodiert den Base64-Payload, startet das Python-Skript via spawn, und streamt den JSON-Output zurück.

3. Logic Core (gtm_architect_orchestrator.py):

   • Runtime: Python 3.11+.
   • Funktion: Enthält die gesamte Business-Logik und Prompt-Engineering für alle 9 Phasen.
   • Abhängigkeiten: helpers.py (Gemini Wrapper), gtm_db_manager.py (Datenbank), config.py (Keys).
   • NEU: Argument-Parsing über --mode und --payload_base64.

4. Persistenz (gtm_projects.db):

   • Typ: SQLite.
   • Schema: id (UUID), name (String), data (JSON Blob), timestamps.
   • Management: Erfolgt über gtm_db_manager.py (init, save, load, list, delete).

3. Der 9-Phasen Prozess

Der Orchestrator steuert die folgenden Phasen. Jeder Modus erwartet ein spezifisches JSON-Payload.

Phase	Modus	Input	Output	Beschreibung
1	phase1	Rohtext / URL	Features, Constraints	Extrahiert technische Daten aus Text oder durch Scraping einer URL & prüft Portfolio-Konflikte.
2	phase2	Phase 1 Result	ICPs, Data Proxies	Identifiziert ideale Kundenprofile (Branchen).
3	phase3	Phase 2 Result	Whales (Firmen), Rollen	Identifiziert konkrete Zielkunden und Buying Center Rollen.
4	phase4	Phase 1 & 3	Strategy Matrix	Entwickelt "Angles" und Pain-Points pro Segment.
5	phase5	Alle Daten	Markdown Report	Erstellt den finalen Strategie-Report.
6	phase6	Phase 1, 3, 4	Battlecards, Prompts	Generiert Einwandbehandlung & Bild-Prompts.
7	phase7	Phase 2, 4	Landing Page Copy	NEU: Erstellt Landingpage-Texte (Hero, Bullets, CTA).
8	phase8	Phase 1, 2	Business Case	NEU: CFO-Argumentation, ROI-Logik, Leasing-Vergleich.
9	phase9	Phase 1, 4	Feature-to-Value	NEU: "So what?"-Übersetzung technischer Features.
Extra	translate	Markdown Text	Englisch	Übersetzt den Report ins Business-Englisch.
Extra	image	Prompt	Base64 Image	Generiert Konzeptbilder via Gemini.

4. Deployment & Betrieb

Docker Integration

Der Service läuft im Container gtm-app.

• Build: Multi-Stage: Ein Node.js 20 Builder-Stage baut das Frontend. Das finale Python 3.11 Image installiert Node.js über das offizielle NodeSource-Repository und kopiert die Artefakte.
• Volume Mounts (Sideloading):
  • /app/gtm-architect: Frontend-Build & Server-Code.
  • /app/gtm_architect_orchestrator.py: Python-Logik.
  • /app/gtm_projects.db: Datenbank (persistent).
  • /app/Log_from_docker: Logging.
  • API Keys (gemini_api_key.txt).

Starten / Neustarten

docker-compose up -d --build gtm-app

5. Logging & Debugging

• Logs: Werden in /app/Log_from_docker/ geschrieben.
• Format: YY-MM-DD_HH-MM-SS_step_type.txt (z.B. phase1_extract_response.txt).
• Node.js Logs: docker logs gtm-app.

6. Aktueller Status (Jan 2026) - FIXED & OPERATIONAL

Das System ist nach umfangreichen Fixes nun voll funktionsfähig.

• [GELÖST] Gemini API Integration:
  • Fehler: AttributeError: module 'google.generativeai' has no attribute 'Client' (Veraltete API).
  • Fehler: 404 models/gemini-1.5-flash... not found (Falscher Modellname/Version).
  • Lösung: Umstellung auf moderne genai.GenerativeModel Syntax. Implementierung einer dynamischen Modell-Ermittlung (_get_best_flash_model), die automatisch das beste verfügbare Modell (z.B. gemini-1.5-flash, gemini-1.5-flash-001) wählt, anstatt abzustürzen.
• [GELÖST] Konfiguration & Pfade:
  • Korrekte Einbindung der API-Keys (serpapikey.txt, genderize_api_key.txt) durch Anpassung der Groß-/Kleinschreibung in config.py und Mounts in docker-compose.yml.
  • Behebung von IndentationError in config.py.
  • Hinzufügen der fehlenden gtm-architect/requirements.txt für korrekten Container-Build.

Nächste Schritte:

• Reguläre Nutzung des GTM Architect.
• Bei Bedarf: Erweiterung der helpers.py um weitere spezialisierte Modelle.