docs(gtm): Create comprehensive documentation and update global readme

2025-12-31 13:16:10 +00:00
parent a1f9619d01
commit a79763b947
3 changed files with 126 additions and 19 deletions
--- a/gtm-architect/README.md
+++ b/gtm-architect/README.md
@@ -1,20 +1,21 @@
-<div align="center">
-<img width="1200" height="475" alt="GHBanner" src="https://github.com/user-attachments/assets/0aa67016-6eaf-458a-adb2-6e31a0763ed6" />
-</div>
+# GTM Architect Frontend

-# Run and deploy your AI Studio app
+Dies ist das React-Frontend für die GTM Architect Engine.

-This contains everything you need to run your app locally.
+## Tech Stack
+*   **React 19**
+*   **Vite**
+*   **TypeScript**
+*   **Tailwind CSS**
+*   **Lucide React** (Icons)

-View your app in AI Studio: https://ai.studio/apps/drive/1bvzSOz-NYMzDph6718RuAy1mnCSjjylz
+## Entwicklung
+Das Frontend ist darauf ausgelegt, im Docker-Container `gtm-app` gebaut und serviert zu werden.
+Es kommuniziert ausschließlich mit dem lokalen Backend unter `/api/gtm`.

-## Run Locally
+## Struktur
+*   `App.tsx`: Hauptlogik und State-Management.
+*   `components/`: UI-Komponenten (Layout).
+*   `types.ts`: TypeScript Definitionen für die API-Payloads.

-**Prerequisites:**  Node.js
-
-
-1. Install dependencies:
-   `npm install`
-2. Set the `GEMINI_API_KEY` in [.env.local](.env.local) to your Gemini API key
-3. Run the app:
-   `npm run dev`
+Für die vollständige Systemdokumentation siehe `../gtm_architect_documentation.md`.
--- a/gtm_architect_documentation.md
+++ b/gtm_architect_documentation.md
@@ -0,0 +1,90 @@
+# 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)
+    *   `gtm_architect_orchestrator.py` (Sideloading für Dev)
+    *   `server.cjs` (Sideloading für Dev)
+    *   `helpers.py` & `config.py` (Shared Libraries)
+
+### Starten / Neustarten
+```bash
+# Bauen und Starten
+docker-compose up -d --build gtm-app proxy dashboard
+
+# Nur Neustart nach Python-Änderungen (dank Sideloading)
+docker-compose restart gtm-app
+```
+
+## 5. Wartung & Troubleshooting
+
+### 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`).
+
+### Fehler: "Project not saved"
+*   **Ursache:** Berechtigungsprobleme auf `gtm_projects.db` oder Datei fehlt.
+*   **Lösung:** Sicherstellen, dass die Datei auf dem Host existiert und gemountet ist (wurde im Setup-Prozess via `touch` erstellt).
+
+### Entwicklung
+Änderungen am Prompting sollten ausschließlich in `gtm_architect_orchestrator.py` vorgenommen werden. Nach der Änderung reicht ein `docker-compose restart gtm-app`.
--- a/readme.md
+++ b/readme.md
@@ -41,7 +41,12 @@ V. DAS KLASSIFIZIERUNGS-SYSTEM (Job-Titel-Analyse)
 VI. DAS STANDALONE-WERKZEUG
    └── company_deduplicator.py (Eigenständiger Duplikats-Check für externe und interne Listen)

-VII. DAS FUNDAMENT
+VII. DIE STRATEGIE-SCHMIEDE (GTM Architect)
+    └── gtm_architect_orchestrator.py (Strategie-Entwicklung)
+        ├── gtm-architect/ (React Frontend)
+        └── server.cjs (Node.js API-Bridge)
+
+VIII. DAS FUNDAMENT
     └── config.py (Einstellungen & Konstanten für ALLE)
 ```

@@ -674,7 +679,7 @@ Um die verschiedenen Werkzeuge zugänglicher und wartbarer zu machen, wurden der



-Die konsolidierte Lösung besteht aus vier Haupt-Containern, die von `docker-compose.yml` gesteuert werden:
+Die konsolidierte Lösung besteht aus fünf Haupt-Containern, die von `docker-compose.yml` gesteuert werden:



@@ -692,13 +697,15 @@ Die konsolidierte Lösung besteht aus vier Haupt-Containern, die von `docker-com

        *   `/market/` -> Market Intelligence Tool

+        *   `/gtm/` -> GTM Architect
+


 2.  **Dashboard:**

    *   Eine simple Nginx-Instanz, die eine statische HTML-Seite (`dashboard/index.html`) ausliefert.

-    *   Diese Seite dient als Landingpage und verlinkt auf die beiden untergeordneten Anwendungen.
+    *   Diese Seite dient als Landingpage und verlinkt auf die drei untergeordneten Anwendungen.



@@ -714,6 +721,10 @@ Die konsolidierte Lösung besteht aus vier Haupt-Containern, die von `docker-com

    *   Diese Anwendung bleibt in Frontend- und Backend-Container aufgeteilt, wird aber nun ebenfalls über den zentralen Proxy unter `/market/` geroutet.

+5.  **GTM Architect (`gtm-app`):**
+    *   Ein Docker-Container, der das React-Frontend und die dazugehörige Node.js/Python-Backend-Logik kapselt.
+    *   Erreichbar über das Unterverzeichnis `/gtm/`.
+


 ### Vorteile dieser Architektur
@@ -774,6 +785,8 @@ Für den dauerhaften Betrieb auf einem Server (z.B. Synology Diskstation) wird d

 -   **Market Intelligence Tool:** Direkt erreichbar unter `http://<Server-IP>:8090/market/`.

+-   **GTM Architect:** Direkt erreichbar unter `http://<Server-IP>:8090/gtm/`.
+


 ### Entwicklung & Sideloading
@@ -784,7 +797,7 @@ Dank des Volume-Mountings für die Python-Skripte ist die Entwicklung sehr effiz



-1.  **Ändern Sie den Python-Code** in `b2b_marketing_orchestrator.py` oder `market_intel_orchestrator.py`.
+1.  **Ändern Sie den Python-Code** in `b2b_marketing_orchestrator.py`, `market_intel_orchestrator.py` oder `gtm_architect_orchestrator.py`.

 2.  **Starten Sie den betroffenen Container neu**, damit die Änderungen wirksam werden:

@@ -802,6 +815,9 @@ Dank des Volume-Mountings für die Python-Skripte ist die Entwicklung sehr effiz

    docker-compose restart market-backend

+    # Für den GTM Architect
+    docker-compose restart gtm-app
+
    ```