Floke
302a211239
- Refactors the gtm-architect Dockerfile for a flat, more efficient build process. - Implements robust web scraping via BeautifulSoup in helpers.py for URL analysis in phase1. - Makes shared library imports (gspread, pandas, etc.) in helpers.py optional to prevent ModuleNotFoundErrors in microservices. - Implements the main execution logic in the orchestrator to handle command-line arguments. - Updates documentation to reflect the new architecture, scraping feature, and dependency handling.
85 lines
4.4 KiB
Markdown
85 lines
4.4 KiB
Markdown
# 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`.
|