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

```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.
    *   *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
```bash
# 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`.