# Dokumentation: GTM Architect Engine (v3.1)

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

**Aktuelle Version:** v3.1 ("Closing-Ready Edition") - Stand: 20.01.2026

## 2. Architektur & Tech-Stack

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 (v3.1 Logik)

| Phase | Modus | Input | Output | V3.1 Update |
| :--- | :--- | :--- | :--- | :--- |
| **1** | `phase1` | Rohtext / URL | Features, Constraints, **Category** | Autonome Erkennung der Wackler-Kategorie (z.B. Cleaning Indoor Carpet). |
| **2** | `phase2` | Phase 1 Result | ICPs, Data Proxies | Identifiziert ideale Kundenprofile basierend auf Kategorie. |
| **3** | `phase3` | Phase 2 Result | Whales, **Archetypes** | Identifiziert 4 strategische Archetypen (Operativ, Infrastruktur, Eco, Innovation). |
| **4** | `phase4` | Phase 1 & 3 | Strategy Matrix | Wendet "Service Gap" Logik an (Machine vs. Human Service). |
| **5** | `phase5` | Alle Daten | **Senior Report** | Erstellt "Closing-Ready" Report mit Datasheet-Specs & ROI-Range. |
| **6** | `phase6` | Phase 1, 3, 4 | Battlecards, Prompts | **Legal/Liability** Fokus für Infrastruktur-Persona. |
| **7** | `phase7` | Phase 2, 4 | Landing Page Copy | Erstellt Landingpage-Texte mit Wackler-Symbiose. |
| **8** | `phase8` | Phase 1, 2 | **ROI Framework** | Generiert ROI-Formel mit **Example Ranges** (kein "undefined"). |
| **9** | `phase9` | Phase 1, 4 | Feature-to-Value | Übersetzung technischer Features in Nutzen. |

## 5. Changelog & Version History

*   **[MAJOR] v3.1: "Closing-Ready" Edition (Jan 20, 2026)**
    *   **ROI-Fix:** Phase 8 generiert nun plausible **Wertebereiche** (z.B. "20-30% Reduktion") statt abstrakter Formeln, die zu `undefined` führten.
    *   **Legal-Härtung:** Phase 6 Battlecards adressieren gezielt **Haftung, DSGVO & DGUV V3** für die "Infrastruktur"-Persona.
    *   **Technical Depth:** Phase 5 Report fordert nun explizit **alle** technischen Specs (auch Layer-Daten) für eine "Datasheet"-Qualität.
    *   **Stabilität:** Implementierung von `isinstance(list)` Checks in Phasen 6, 7, 8, um "White Screen of Death" durch Listen-Antworten zu verhindern.

*   **[MAJOR] v3.0: "Dynamic Service Logic" (Jan 20, 2026)**
    *   Einführung der **7 Wackler-Kategorien** (Cleaning Indoor/Outdoor, POS, Security, Service, Transport).
    *   Implementierung der universellen "Machine Layer vs. Human Service Layer" Logik im System-Prompt.
    *   Konsolidierung auf **4 Buying Center Archetypen**.

*   **[UPGRADE] v2.6.2:** Editierbare Hard Facts & Report Completeness.
*   **[UPGRADE] v2.6:** Rich Session Browser & Metadaten-Persistenz.

## 6. GTM Architect V3.1 Prompts (Reference)

Dies ist die Referenz der kritischen Prompts, die die "Senior Grade" Qualität der Engine steuern.

### 6.1. System Prompt (Universal Service Logic)
Definiert die "Denkweise" der KI. Erkennt autonom die Kategorie und wendet die passende Hybrid-Logik an.

```python
def get_system_instruction(lang):
    return """
    # RULE 5: THE "DYNAMIC SERVICE" LOGIC (UNIVERSAL)
    First analyze the **category** of the robot and then apply the appropriate hybrid logic:

    1. CLEANING INDOOR (CARPET) - Vacuums for carpets
       * Robot: Does the area (80%).
       * Human (Wackler Cleaning): Does edges, corners, spot removal (20%).
    
    2. CLEANING INDOOR (WET SURFACE) - Scrubber dryers (Hard floor)
       * Robot: Cleans halls/corridors continuously.
       * Human (Wackler Cleaning): Safety check (slip hazard), water change, hygiene audit.
    
    5. SECURITY ROBOT - Mobile Surveillance (Quadruped/Drone)
       * Robot: "Detection & Presence". 24/7 patrol, thermal imaging, no fatigue.
       * Human (Wackler Security): "Evaluation & Intervention". NSL evaluates alarm, intervention force drives out.
       * Pitch: "The robot sees the danger, Wackler eliminates it."
    
    [...weitere Kategorien...]
    Mandatory application of this logic in PHASE 4 (Strategy) and PHASE 6 (Sales Enablement).
    """
```

### 6.2. Phase 5 Prompt (Senior Report Generation)
Erzwingt ausführliche, gut formatierte Reports und verhindert "dünnen" Content.

```python
report_sys_instr = """
You are a Senior Business Consultant at a top-tier firm (like McKinsey or BCG).
Your task is to write a strategically deep, detailed "Go-to-Market Strategy Report".

RULES:
1.  **No JSON:** Your output is pure, cleanly formatted Markdown.
2.  **Senior Grade:** Do not write "thin" bullet points. Write full sentences...
3.  **Completeness:** Never stop in the middle of a table or sentence.
"""

prompt = """
TASK: Write the "GTM STRATEGY REPORT v3.1" in Markdown. 
REQUIRED STRUCTURE:
...
3. Product Reality Check (Technical Deep Dive)
   * Include ALL available specs... Make it as comprehensive as a technical datasheet.
...
7. Commercial Logic (ROI Framework)
   * Example Calculation: Provide a hypothetical example calculation with plausible ranges...
"""
```

### 6.3. Phase 6 Prompt (Legal Hardening)
Sorgt für rechtssichere Verkaufsargumente.

```python
prompt = """
1. **Anticipate Objections:** ...
   * *Special Focus for 'Infrastructure Responsible' (Gatekeeper):* Address **Legal, Liability & Compliance** issues (e.g. GDPR, DGUV V3, accident liability) specifically.
2. **Formulate Battlecards:** ...
   * *Requirement:* Use specific **proof points** (e.g., "Certified according to...", "Data hosted in Germany") instead of generic promises.
"""
```

### 6.4. Phase 8 Prompt (ROI Ranges)
Verhindert "undefined" Fehler durch Forderung von Schätzbereichen.

```python
prompt = """
2. **ROI Formula & Example:** Create a formula: `Net Value = (Savings + Risk Mitigation) - (TCO)`.
   * *CRITICAL:* Provide **PLAUSIBLE EXAMPLE RANGES** for efficiency gains (e.g., "Estimate: 20-30% reduction in manual patrol time") instead of just listing the variable.
   * **Do NOT output "undefined".** Give a realistic estimation based on the industry context.
"""
```