Floke
05753edbb1
- Refactor Docker build process for gtm-app to ensure reliability - Correct volume mounts and build context in docker-compose.yml to prevent stale code - Fix frontend 404 error by using relative paths in index.html - Ensure API key is correctly mounted into the container - Stabilize Node.js to Python data passing via explicit --data argument - Update gtm_architect_documentation.md with extensive troubleshooting guide
109 lines
6.2 KiB
Markdown
109 lines
6.2 KiB
Markdown
# 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)
|
||
* `gemini_api_key.txt` (API-Schlüssel)
|
||
* `gtm_architect_orchestrator.py` (Sideloading für Dev)
|
||
* `server.cjs` (Sideloading für Dev)
|
||
* `helpers.py` & `config.py` (Shared Libraries)
|
||
|
||
### Starten / Neustarten
|
||
Der beste Weg, um einen sauberen Neustart zu gewährleisten, ist der `up`-Befehl mit `--build`.
|
||
|
||
```bash
|
||
# Kompletten Stack neu bauen und starten (empfohlen)
|
||
docker-compose up -d --build
|
||
|
||
# Nur den gtm-app Service neu bauen & neu erstellen
|
||
# Das --force-recreate ist entscheidend, um sicherzustellen, dass der alte Container ersetzt wird.
|
||
docker-compose up -d --build --force-recreate gtm-app
|
||
|
||
# Build ohne Cache erzwingen (bei hartnäckigen Problemen)
|
||
docker-compose build --no-cache gtm-app && docker-compose up -d gtm-app
|
||
```
|
||
|
||
## 5. Wartung & Troubleshooting
|
||
|
||
### Fehler: "White Screen" / Leere Seite nach Start
|
||
* **Symptom:** Der Browser zeigt eine leere Seite. In der Entwicklerkonsole erscheint ein `404 Not Found` Fehler für `index.css` oder `index.tsx`.
|
||
* **Ursache:** Falsche Pfade in der `gtm-architect/index.html`. Die `href` und `src` Attribute für CSS und JS müssen relativ (`./index.css`) statt absolut (`/index.css`) sein.
|
||
* **Lösung:** Pfade in der `index.html` korrigieren und sicherstellen, dass in `vite.config.ts` die Option `base: './'` gesetzt ist. Anschließend den Container mit `--build` neu erstellen.
|
||
|
||
### Fehler: Leere Listen / Keine API-Antwort im Frontend
|
||
* **Symptom:** Die App startet, aber nach dem Klick auf "Analyse starten" erscheinen keine Features oder Constraints. Es gibt keine Fehlermeldung.
|
||
* **Ursache:** Dem Python-Skript fehlt der API-Schlüssel. Das Skript `config.py` liest den Schlüssel aus der Datei `/app/api_key.txt` im Container. Wenn diese Datei fehlt, schlagen API-Aufrufe im Hintergrund fehl, und das Skript gibt eine leere Antwort zurück.
|
||
* **Lösung:** Sicherstellen, dass die `docker-compose.yml` den API-Schlüssel korrekt in den Container mountet: `volumes: - ./gemini_api_key.txt:/app/api_key.txt`.
|
||
|
||
### Fehler: Code-Änderungen werden nicht übernommen (Stale Code)
|
||
* **Symptom:** Änderungen an Python- oder Node.js-Dateien haben keine Auswirkung im Container, selbst nach einem `restart`.
|
||
* **Ursache:** Ein Problem in der `docker-compose.yml`. Entweder ist der `build context` falsch gesetzt oder die `volumes`-Konfiguration für das Sideloading ist fehlerhaft. Ein zu breiter Mount wie `- .:/app` kann von den Dateien im Image überschrieben werden.
|
||
* **Lösung:**
|
||
1. Den `build context` auf `.` setzen und das `dockerfile` spezifisch adressieren (`gtm-architect/Dockerfile`).
|
||
2. `volumes` für jede zu sideloadende Datei einzeln und explizit definieren.
|
||
3. Den Container mit `docker-compose up -d --build --force-recreate gtm-app` neu erstellen.
|
||
|
||
### 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`).
|