Refactor GTM Architect to v2: Python-driven architecture, 9-phase process, new DB and Docker setup
This commit is contained in:
@@ -1,14 +1,14 @@
|
||||
# Dokumentation: GTM Architect Engine
|
||||
# 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 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).
|
||||
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.
|
||||
Das System ist als Microservice in die bestehende Docker-Umgebung integriert (`gtm-app`).
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
@@ -25,84 +25,60 @@ graph LR
|
||||
* 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.
|
||||
* **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, startet das Python-Skript und streamt den Output zurück.
|
||||
* *Wichtig:* Timeout ist auf **600s** (10 Minuten) erhöht, um lange KI-Generierungszeiten abzudecken.
|
||||
* 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.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).
|
||||
* Runtime: **Python 3.9+**.
|
||||
* 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 `market_db_manager.py`.
|
||||
* Management: Erfolgt über `gtm_db_manager.py` (init, save, load, list, delete).
|
||||
|
||||
## 3. Der 6-Phasen Prozess
|
||||
## 3. Der 9-Phasen Prozess
|
||||
|
||||
Der Orchestrator (`gtm_architect_orchestrator.py`) steuert die folgenden Phasen über das Argument `--mode`.
|
||||
Der Orchestrator steuert die folgenden Phasen. Jeder Modus erwartet ein spezifisches JSON-Payload.
|
||||
|
||||
| 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. |
|
||||
| **1** | `phase1` | Rohtext / URL | Features, Constraints | Extrahiert technische Daten & 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-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)
|
||||
Der Service läuft im Container `gtm-app`.
|
||||
* **Build:** Multi-Stage: Node.js baut Frontend -> Python Image installiert Node & Python Deps.
|
||||
* **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
|
||||
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
|
||||
docker-compose up -d --build gtm-app
|
||||
```
|
||||
|
||||
## 5. Wartung & Troubleshooting
|
||||
## 5. Logging & Debugging
|
||||
|
||||
### 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`).
|
||||
* **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`.
|
||||
|
||||
Reference in New Issue
Block a user