diff --git a/gtm-architect/README.md b/gtm-architect/README.md index 8154d382..762e3e45 100644 --- a/gtm-architect/README.md +++ b/gtm-architect/README.md @@ -1,20 +1,21 @@ -
-GHBanner -
+# 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`. \ No newline at end of file diff --git a/gtm_architect_documentation.md b/gtm_architect_documentation.md new file mode 100644 index 00000000..53e0932e --- /dev/null +++ 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`. diff --git a/readme.md b/readme.md index 6bc043ca..07d14ee9 100644 --- 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://:8090/market/`. +- **GTM Architect:** Direkt erreichbar unter `http://: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 + ```