Floke
84fc0b91b0
- Fixed TypeError in SessionBrowser by adding defensive checks for the sessions array. - Implemented mandatory URL persistence: The research URL is now saved in DB, shown in UI, and included in reports. - Added 'Start New Analysis' button to the session browser for better UX flow. - Updated documentation to reflect v2.6.1 changes.
121 lines
7.3 KiB
Markdown
121 lines
7.3 KiB
Markdown
# Dokumentation: GTM Architect Engine (v2.5)
|
||
|
||
## 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. |
|
||
| **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. technischer Spezifikationen (Hard Facts) aus Phase 1. |
|
||
| **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. |
|
||
|
||
## 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.1: Stability & URL Persistence**
|
||
* **Bugfix:** Behebung des "Weißen Bildschirms" durch Absicherung der Session-Liste gegen `undefined`-Werte.
|
||
* **URL Tracking:** Die Recherche-URL wird nun zwingend im Projekt gespeichert, in der Lade-Übersicht angezeigt und in den finalen Report-Export integriert.
|
||
* **UX Flow:** Direkter Wechsel zwischen "Letzte Sitzungen" und "Neue Analyse starten" jederzeit möglich.
|
||
|
||
* **[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. |