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

```mermaid
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. |

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