Floke
63243cd344
Refactors the GTM orchestrator prompts (phases 2-9) to use a question-based strategic framework derived from the internal marketing blueprint. This new 'Meta-Framework' approach ensures strategic depth and prevents content pollution from irrelevant examples when analyzing new product categories. - Updates orchestrator prompts in . - Adds documentation in explaining how to modify the new strategy logic. - Includes minor fixes to the Node.js and dependency updates in .
174 lines
11 KiB
Markdown
174 lines
11 KiB
Markdown
# Dokumentation: GTM Architect Engine (v2.6)
|
||
|
||
## 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 **9-stufigen Prozess** – von der technischen Analyse über Business-Case-Modellierung bis hin zu fertigen Vertriebsunterlagen und Landingpages.
|
||
|
||
## 2. Architektur & Tech-Stack (Stand Jan 2026)
|
||
|
||
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 -- import --> Helpers[Core Engine (helpers.py)]
|
||
Helpers -- Dual SDK --> Gemini[Google Gemini 2.0 Flash (Text)]
|
||
Helpers -- Dual SDK --> Imagen[Google Imagen 4.0 (Text-to-Image)]
|
||
Helpers -- Dual SDK --> GeminiImg[Google Gemini 2.5 Flash (Image-to-Image)]
|
||
Python -- SQL --> DB[(SQLite: gtm_projects.db)]
|
||
```
|
||
|
||
### Komponenten
|
||
|
||
1. **Frontend (`/gtm-architect`):**
|
||
* Framework: **React** (Vite + TypeScript).
|
||
* Features: **Session History**, **Hard Fact Extraction UI** und **Markdown Upload**.
|
||
|
||
2. **Backend Bridge (`server.cjs`):**
|
||
* Runtime: **Node.js** (Express).
|
||
* Funktion: Nimmt HTTP-Requests entgegen und startet Python-Prozesse (`gtm_architect_orchestrator.py`).
|
||
|
||
3. **Logic Core (`gtm_architect_orchestrator.py`):**
|
||
* Runtime: **Python 3.11+**.
|
||
* Verantwortlichkeit: Steuert den 9-Phasen-Prozess, verwaltet Payloads und interagiert mit der Datenbank. Nutzt `helpers.py` für alle KI-Interaktionen.
|
||
|
||
4. **Core Engine (`helpers.py`):**
|
||
* Laufzeit: **Python 3.11+**.
|
||
* Verantwortlichkeit: Abstrahiert die Komplexität der KI-API-Aufrufe. Stellt robuste, wiederverwendbare Funktionen für Text- und Bildgenerierung bereit.
|
||
|
||
5. **Persistenz (`gtm_projects.db`):**
|
||
* Typ: **SQLite**. Speichert alle Phasen-Ergebnisse als JSON-Blobs in einer einzigen Tabelle.
|
||
|
||
## 3. Kernfunktionalität: Die AI Engine (`helpers.py`)
|
||
|
||
Das Herzstück des Systems ist die `helpers.py`-Bibliothek, die für Stabilität und Zukunftssicherheit konzipiert wurde.
|
||
|
||
### 3.1 Dual SDK Support
|
||
|
||
Um maximale Stabilität zu gewährleisten und gleichzeitig Zugriff auf die neuesten KI-Modelle zu haben, wird ein dualer Ansatz für die Google AI SDKs verfolgt:
|
||
* **`google-generativeai` (Legacy):** Wird bevorzugt für Text-Generierungs-Aufgaben (`gemini-2.0-flash`) verwendet, da es sich in diesem Setup als robuster erwiesen hat.
|
||
* **`google-genai` (Modern):** Wird für alle Bild-Generierungs-Aufgaben und als Fallback für die Text-Generierung genutzt.
|
||
|
||
### 3.2 Hybride Bildgenerierung
|
||
|
||
Die `call_gemini_image`-Funktion wählt automatisch die beste Methode basierend auf dem Input:
|
||
* **Szenario A: Text-to-Image (Kein Referenzbild)**
|
||
* **Modell:** `imagen-4.0-generate-001`.
|
||
* **Anwendung:** Generiert ein komplett neues Bild basierend auf einem textuellen Prompt (z.B. für Landingpage-Banner).
|
||
* **Szenario B: Image-to-Image (Mit Referenzbild)**
|
||
* **Modell:** `gemini-2.5-flash-image`.
|
||
* **Anwendung:** Platziert ein existierendes Produkt (via Upload) in eine neue, per Text beschriebene Szene. Der Prompt ist darauf optimiert, das Produktdesign nicht zu verändern.
|
||
|
||
## 4. Der 9-Phasen Prozess
|
||
|
||
| Phase | Modus | Input | Output | Beschreibung |
|
||
| :--- | :--- | :--- | :--- | :--- |
|
||
| **1** | `phase1` | Rohtext / URL | Features, Constraints, **Specs** | Extrahiert technische Daten, **Hard Facts (Specs)** & erstellt DB-Projekt. **Specs sind editierbar.** |
|
||
| **2** | `phase2` | Phase 1 Result | ICPs, Data Proxies | Identifiziert ideale Kundenprofile. |
|
||
| **3** | `phase3` | Phase 2 Result | Whales, Rollen | Identifiziert Zielkunden & Buying Center. |
|
||
| **4** | `phase4` | Phase 1 & 3 | Strategy Matrix | Entwickelt "Angles" und Pain-Points. |
|
||
| **5** | `phase5` | Alle Daten | Markdown Report | **Strategie-Fixierung**. Konsolidierter Report inkl. Specs & Phase 2 Insights. |
|
||
| **6** | `phase6` | Phase 1, 3, 4 | Battlecards, Prompts | Generiert Einwandbehandlung & Bild-Prompts. |
|
||
| **7** | `phase7` | Phase 2, 4 | Landing Page Copy | Erstellt Landingpage-Texte. |
|
||
| **8** | `phase8` | Phase 1, 2 | Business Case | CFO-Argumentation, ROI-Logik. |
|
||
| **9** | `phase9` | Phase 1, 4 | Feature-to-Value | Übersetzung technischer Features in Nutzen. |
|
||
|
||
### 4.1 Anleitung: Anpassung der Strategie-Logik (Meta-Framework)
|
||
|
||
Das Herzstück der strategischen Qualität der App ist nicht in einer externen Datei gespeichert, sondern wurde als "Meta-Framework" direkt in die Anweisungen (Prompts) für die KI einprogrammiert. Dieses Framework besteht aus den strategischen Schlüsselfragen, die die KI beantworten muss, um eine GTM-Strategie zu erstellen.
|
||
|
||
Wenn sich Ihre grundlegende Marketing-Strategie weiterentwickelt, können Sie diese Logik anpassen, indem Sie die Prompts im Code ändern.
|
||
|
||
**Wichtig:** Dieser Prozess erfordert ein Verständnis der Programm-Logik und sollte sorgfältig durchgeführt werden.
|
||
|
||
**Schritt-für-Schritt-Anleitung:**
|
||
|
||
1. **Quelldatei identifizieren:** Die gesamte Logik befindet sich in der Datei `gtm_architect_orchestrator.py`.
|
||
|
||
2. **Relevante Funktionen finden:** Jede Phase des GTM-Prozesses hat eine eigene Python-Funktion (z.B. `phase2`, `phase3`, `phase4` etc.). Innerhalb jeder dieser Funktionen gibt es eine Variable namens `prompt`. Das ist die Anweisung für die KI.
|
||
|
||
3. **Prompt-Struktur verstehen:** Die Prompts sind so aufgebaut, dass sie der KI strategische Leitplanken geben. Suchen Sie nach dem Abschnitt `**Strategic Questions:**` innerhalb des `prompt`-Blocks.
|
||
|
||
*Beispiel (Ausschnitt aus `phase2`):*
|
||
```python
|
||
prompt = f"""
|
||
PHASE 2: IDEAL CUSTOMER PROFILE (ICP) & DATA PROXIES - STRATEGIC ANALYSIS
|
||
|
||
**Your Task:**
|
||
Answer the following strategic questions to determine the Ideal Customer Profiles (ICPs).
|
||
|
||
**Strategic Questions:**
|
||
1. **ICP Identification:** Based on the product's core capabilities, which 3 industries face the most significant operational challenges...?
|
||
2. **Rationale:** For each identified ICP, provide a concise rationale...
|
||
3. **Data Proxies:** How can we find these companies online...?
|
||
|
||
{lang_instr}
|
||
|
||
**Output:**
|
||
Provide your analysis ONLY in the following JSON format:
|
||
{{"icps": [...], "dataProxies": [...]}}
|
||
"""
|
||
```
|
||
|
||
4. **Strategische Fragen anpassen:** Sie können die Fragen unter `**Strategic Questions:**` ändern, hinzufügen oder entfernen, um die Denkweise der KI zu steuern. Wenn Sie beispielsweise feststellen, dass die "Data Proxies" präziser sein müssen, könnten Sie die Frage 3 anpassen oder eine vierte Frage hinzufügen.
|
||
|
||
5. **Output-Struktur beibehalten (KRITISCH!):** Der Teil des Prompts, der mit `**Output:**` beginnt, definiert das JSON-Format, das die Funktion zurückgibt. **Ändern Sie dieses Format NICHT**, da sonst die nachfolgenden Phasen und das Frontend die Daten nicht mehr verarbeiten können. Die Anpassung erfolgt ausschließlich über die strategischen Fragen, die das Ergebnis inhaltlich beeinflussen.
|
||
|
||
6. **Änderungen bereitstellen:** Nachdem Sie die `gtm_architect_orchestrator.py` gespeichert haben, ist **kein** `docker build` notwendig. Ein einfacher Neustart des Containers aktiviert die neue Logik:
|
||
```bash
|
||
docker restart gtm-app
|
||
```
|
||
|
||
Durch das Befolgen dieser Schritte können Sie die Kernlogik des GTM Architect selbstständig an neue strategische Anforderungen anpassen.
|
||
|
||
## 5. Sitzungs-Management
|
||
|
||
Das System verwaltet persistente Sitzungen in der SQLite-Datenbank:
|
||
* **List:** Abruf aller gespeicherten Projekte, angereichert mit extrahierten Metadaten wie Produktname, Kategorie und Beschreibung für eine informative Übersicht.
|
||
* **Load:** Vollständige Wiederherstellung des App-States (alle Phasen).
|
||
* **Delete:** Permanentes Entfernen aus der Datenbank.
|
||
|
||
## 6. Deployment & Betrieb
|
||
|
||
* **Wichtig:** Das Frontend wird im Build-Stage gebaut. Bei Änderungen an `App.tsx` muss der Container mit `docker-compose up -d --build gtm-app` neu gebaut werden.
|
||
* **Backend:** Änderungen an `gtm_architect_orchestrator.py` oder `helpers.py` erfordern keinen Build, nur einen Restart (`docker restart gtm-app`).
|
||
|
||
## 7. Historie & Fixes (Jan 2026)
|
||
|
||
* **[UPGRADE] v2.6.2: Report Completeness & Edit Mode**
|
||
* **Edit Hard Facts:** Neue Funktion in Phase 1 ("Edit Raw Data") erlaubt die manuelle Korrektur der extrahierten technischen JSON-Daten.
|
||
* **Report-Update:** Phase 5 Prompt wurde angepasst, um explizit die Ergebnisse aus Phase 2 (ICPs & Data Proxies) im finalen Report aufzuführen.
|
||
* **Backend-Fix:** Korrektur eines Fehlers beim Speichern von JSON-Daten, der auftrat, wenn Datenbank-Inhalte als Strings vorlagen.
|
||
|
||
* **[UPGRADE] v2.6.1: Stability & UI Improvements**
|
||
* **White Screen Fix:** Robuste Absicherung des Frontends gegen `undefined`-Werte beim Laden älterer Sitzungen (`optional chaining`).
|
||
* **Session Browser:** Komplettes Redesign der Sitzungsübersicht zu einer übersichtlichen Listenansicht mit Icons (Reinigung/Service/Transport/Security).
|
||
* **URL-Anzeige:** Die Quell-URL wird nun als dedizierter Link angezeigt und das Projekt automatisch basierend auf dem erkannten Produktnamen umbenannt.
|
||
|
||
* **[UPGRADE] v2.6: Rich Session Browser**
|
||
* **Neues UI:** Die textbasierte Liste für "Letzte Sitzungen" wurde durch eine dedizierte, kartenbasierte UI (`SessionBrowser.tsx`) ersetzt.
|
||
* **Angereicherte Daten:** Jede Sitzungskarte zeigt nun den Produktnamen, die Produktkategorie (mit Icon), eine Kurzbeschreibung und einen Thumbnail-Platzhalter an.
|
||
* **Backend-Anpassung:** Die Datenbankabfrage (`gtm_db_manager.py`) wurde erweitert, um diese Metadaten direkt aus der JSON-Spalte zu extrahieren und an das Frontend zu liefern.
|
||
* **Verbesserte UX:** Deutlich verbesserte Übersichtlichkeit und schnellere Identifikation von vergangenen Analysen.
|
||
|
||
* **[UPGRADE] v2.5: Hard Fact Extraction**
|
||
* **Phase 1 Erweiterung:** Implementierung eines sekundären Extraktions-Schritts für "Hard Facts" (Specs).
|
||
* **Strukturiertes Daten-Schema:** Integration von `templates/json_struktur_roboplanet.txt`.
|
||
* **Normalisierung:** Automatische Standardisierung von Einheiten (Minuten, cm, kg, m²/h).
|
||
* **Frontend Update:** Neue UI-Komponente zur Anzeige der technischen Daten (Core Data, Layer, Extended Features).
|
||
* **Sidebar & Header:** Update auf "ROBOPLANET v2.5".
|
||
|
||
* **[UPGRADE] v2.4:**
|
||
* Dokumentation der Kern-Engine (`helpers.py`) mit Dual SDK & Hybrid Image Generation.
|
||
* Aktualisierung der Architektur-Übersicht und Komponenten-Beschreibungen.
|
||
* Versionierung an den aktuellen Code-Stand (`v2.4.0`) angepasst.
|
||
|
||
* **[UPGRADE] v2.3:**
|
||
* Einführung der Session History (Datenbank-basiert).
|
||
* Implementierung von Markdown-Cleaning (Stripping von Code-Blocks).
|
||
* Prompt-Optimierung für tabellarische Markdown-Ausgaben in Phase 5.
|
||
* Markdown-File Import Feature. |