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

```mermaid
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
```bash
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) - FULLY OPERATIONAL

Das System ist nach Abschluss aller Debugging-Arbeiten nun **voll einsatzbereit**.

*   **[GELÖST] Gemini API Integration:**
    *   Erfolgreiche Umstellung auf `genai.GenerativeModel`.
    *   **Dynamische Modell-Wahl:** Das System erkennt nun automatisch verfügbare Modelle (z.B. `gemini-1.5-flash`), was 404-Fehler eliminiert.
*   **[GELÖST] Konfiguration:**
    *   Alle API-Key-Pfade wurden korrigiert.
    *   Kritische Syntax- und Einrückungsfehler in `config.py` wurden behoben.
*   **[GELÖST] Deployment:**
    *   Der Container baut nun korrekt mit allen notwendigen Python-Abhängigkeiten.

**Status:** Das Backend kommuniziert erfolgreich mit der Gemini API, die Datenbank persistiert Projekte, und das Frontend kann den vollen 9-Phasen-Prozess steuern.
