docs: Update documentation for consolidated Docker architecture
- Consolidated architecture overview in readme.md\n- Updated deployment and development sections in b2b_marketing_assistant_plan.md and market_intel_backend_plan.md
This commit is contained in:
182
readme.md
182
readme.md
@@ -660,90 +660,150 @@ Diese Datei enthält eine Sammlung von globalen, wiederverwendbaren Hilfsfunktio
|
||||
|
||||
---
|
||||
|
||||
## 9. Standalone Tool: Market Intelligence App
|
||||
|
||||
### Funktionsweise und Architektur
|
||||
|
||||
Das Market Intelligence Tool ist eine mehrstufige Webanwendung für die B2B-Marktanalyse und Lead-Qualifizierung. Es kombiniert eine interaktive React-Oberfläche mit einem robusten, faktenbasierten Python-Backend, um potenzielle Kunden zu finden, zu analysieren und personalisierte Ansprachen zu generieren.
|
||||
## 9. Konsolidierte Architektur & Web-Anwendungen
|
||||
|
||||
Der entscheidende Unterschied zur ursprünglichen Implementierung liegt im Backend-Ansatz: Statt direkter, potenziell inkonsistenter KI-Aufrufe aus dem Frontend wird ein kontrollierter, transparenter und auf echten Daten basierender Prozess eingesetzt, um die Qualität und Nachvollziehbarkeit der Ergebnisse massiv zu verbessern.
|
||||
|
||||
#### Technische Umsetzung und Architektur
|
||||
|
||||
Die Anwendung ist als Service in einem **Docker-Container** gekapselt und besteht aus drei Hauptkomponenten:
|
||||
Um die verschiedenen Werkzeuge zugänglicher und wartbarer zu machen, wurden der **B2B Marketing Assistant** und das **Market Intelligence Tool** in einer einzigen, Docker-basierten Architektur konsolidiert. Diese neue Struktur bietet einen zentralen, passwortgeschützten Einstiegspunkt und optimiert sowohl die Entwicklung als auch den Betrieb.
|
||||
|
||||
1. **React-Frontend:** Die Benutzeroberfläche unter `general-market-intelligence/` bleibt der interaktive Arbeitsbereich für den Benutzer. Alle Eingaben und die Visualisierung der Ergebnisse finden hier statt.
|
||||
2. **Node.js API-Brücke:** Ein minimaler Express.js-Server, der als Schnittstelle zwischen dem Frontend und der Python-Logik dient. Er nimmt die Anfragen der App entgegen und ruft das Python-Skript als sicheren Unterprozess auf.
|
||||
3. **Python-Orchestrator (`market_intel_orchestrator.py`):** Das Herzstück des Systems. Dieses Skript führt die Kernlogik aus und ist nach dem Prinzip **"Grounding first"** konzipiert:
|
||||
- **Web-Scraping als "Ground Truth":** Bevor eine KI-Analyse stattfindet, werden die relevanten Webseiten der Unternehmen (Referenzkunden, Zielunternehmen) gescrapt. Der extrahierte, bereinigte Text dient als unveränderliche Faktenbasis.
|
||||
- **Gezielte KI-Analyse:** Die Gemini-API wird erst im zweiten Schritt aufgerufen. Sie erhält den extrahierten Website-Text als primären Kontext und die Anweisung, ihre Analyse (z.B. die Identifizierung digitaler Signale) ausschließlich auf diesen realen Daten zu basieren.
|
||||
|
||||
Dieser Ansatz stellt sicher, dass die Ergebnisse nicht "halluziniert" sind, sondern auf den tatsächlichen Inhalten der Unternehmens-Websites beruhen, was zu konsistenteren und validierbareren Analysen führt.
|
||||
|
||||
#### Der Analyse-Prozess im Überblick
|
||||
### Architektur im Überblick
|
||||
|
||||
Der Prozess für den Benutzer bleibt weitgehend gleich, ist aber technisch solider untermauert:
|
||||
|
||||
**Schritt 1: Input & Strategie-Erstellung**
|
||||
- **Dateneingabe:** Der Benutzer lädt ein **Strategie-Dokument** hoch und gibt die **URL eines Referenzkunden** an.
|
||||
- **Backend-Prozess:**
|
||||
1. Das Python-Skript extrahiert regelbasiert die Zielbranchen aus dem Dokument ("Grounding").
|
||||
2. Das Skript scrapt die Website des Referenzkunden, um eine Faktenbasis ("Ground Truth") zu schaffen.
|
||||
3. Die KI analysiert den Website-Inhalt im Kontext des Strategie-Dokuments und leitet daraus ein faktenbasiertes **"Ideal Customer Profile" (ICP)** und eine Liste hochrelevanter **"Digitaler Signale"** ab.
|
||||
4. **NEU:** Für jedes Signal wird eine spezifische **"Proof-Strategy"** (Suchbegriffe & Quellen wie Datenschutz, Jobs, Presse) generiert.
|
||||
|
||||
**Schritt 2: Identifizierung & Überprüfung der Zielunternehmen**
|
||||
- **Lead-Findung:** Basierend auf dem ICP und der Referenz-URL wird eine Liste ähnlicher Unternehmen generiert, kategorisiert in **Lokal, National und International**.
|
||||
- **Manuelle Überprüfung:** Der Benutzer kuratiert diese Liste im Frontend.
|
||||
Die konsolidierte Lösung besteht aus vier Haupt-Containern, die von `docker-compose.yml` gesteuert werden:
|
||||
|
||||
**Schritt 3: Deep Tech Audit (Tiefenanalyse)**
|
||||
- **Live-Feedback:** Ein integriertes Terminal in der UI zeigt den echten Fortschritt (Searching website, Scraping, Analyzing signals) in Echtzeit an.
|
||||
- **Backend-Prozess (Smart Grounding):**
|
||||
1. **Gezielte Suche:** Für jedes Unternehmen werden bis zu 5 gezielte Google-Suchen (SerpAPI) ausgeführt, um spezifische Beweise für die Signale (z.B. in Stellenanzeigen oder im Datenschutz) zu finden.
|
||||
2. **Zweistufige Evidenz:** Die KI bewertet die Signale basierend auf dem Homepage-Scrape UND den Google-Snippets.
|
||||
3. **Transparenz:** Jede Bewertung enthält einen **Beleg-Link oder ein Snippet** ("Proof"), um Halluzinationen auszuschließen.
|
||||
4. **Firmographics:** Umsatz- und Mitarbeiterzahlen werden in stabilen Buckets geschätzt.
|
||||
|
||||
**Schritt 4 & 5: Reporting & Personalisierte Ansprache**
|
||||
- **Ergebnis-Darstellung:** Die faktenbasierten Analyseergebnisse werden im Frontend angezeigt.
|
||||
- **Kampagnen-Generierung:** Die KI nutzt die validierten "Digitalen Signale" als Aufhänger, um hyper-personalisierte und extrem treffsichere E-Mail-Entwürfe zu erstellen. Dabei werden **operative Schmerzpunkte ("Grit")** und **Social Proof** (Referenzkunden) aggressiv genutzt, um Insider-Status zu demonstrieren.
|
||||
|
||||
## 10. Deployment & Online-Zugriff (Production)
|
||||
1. **Proxy (Nginx):**
|
||||
|
||||
Für den dauerhaften Betrieb ("Production Mode") auf einem Server (z.B. Synology Diskstation) wird die Anwendung via **Docker Compose** orchestriert. Dies startet sowohl das Backend (Python/Node) als auch das Frontend (Nginx) in optimierten Containern.
|
||||
* **Zentraler Einstiegspunkt:** Der Proxy lauscht auf Port `8090` und ist der einzige von außen erreichbare Punkt.
|
||||
|
||||
### Starten der Anwendung
|
||||
* **Passwortschutz:** Sichert den gesamten Zugriff mit HTTP Basic Authentication (Benutzer: `admin`, Passwort: `gemini`).
|
||||
|
||||
1. Stellen Sie sicher, dass Docker und Docker Compose installiert sind.
|
||||
2. Navigieren Sie in das Hauptverzeichnis.
|
||||
3. Starten Sie den Stack:
|
||||
* **Routing:** Leitet Anfragen an die richtigen Anwendungs-Container weiter:
|
||||
|
||||
* `/` -> Dashboard (Landingpage)
|
||||
|
||||
* `/b2b/` -> B2B Marketing Assistant
|
||||
|
||||
* `/market/` -> Market Intelligence Tool
|
||||
|
||||
|
||||
|
||||
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.
|
||||
|
||||
|
||||
|
||||
3. **B2B Marketing Assistant (`b2b-app`):**
|
||||
|
||||
* Ein Docker-Container, der das React-Frontend und die dazugehörige Node.js/Python-Backend-Logik enthält.
|
||||
|
||||
* Erreichbar über das Unterverzeichnis `/b2b/`.
|
||||
|
||||
|
||||
|
||||
4. **Market Intelligence (`market-frontend` & `market-backend`):**
|
||||
|
||||
* Diese Anwendung bleibt in Frontend- und Backend-Container aufgeteilt, wird aber nun ebenfalls über den zentralen Proxy unter `/market/` geroutet.
|
||||
|
||||
|
||||
|
||||
### Vorteile dieser Architektur
|
||||
|
||||
|
||||
|
||||
- **Zentraler & Sicherer Zugriff:** Nur ein Port muss freigegeben werden, und der Zugang ist einheitlich geschützt.
|
||||
|
||||
- **Einfache Skalierbarkeit:** Die einzelnen Komponenten sind voneinander entkoppelt und können unabhängig voneinander aktualisiert werden.
|
||||
|
||||
- **Optimierte Builds:** Durch die Verwendung von `.dockerignore` und Python-Basis-Images werden die Build-Zeiten verkürzt und die Image-Größen reduziert.
|
||||
|
||||
- **Effiziente Entwicklung:** Die Python-Skripte (`*.py`) werden als Volumes eingebunden ("Sideloading"). Änderungen am Python-Code erfordern daher **keinen** kompletten Docker-Rebuild, sondern nur einen Neustart des Containers.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
|
||||
|
||||
## 10. Deployment & Entwicklung
|
||||
|
||||
|
||||
|
||||
### Produktions-Deployment
|
||||
|
||||
|
||||
|
||||
Für den dauerhaften Betrieb auf einem Server (z.B. Synology Diskstation) wird die gesamte Anwendung mit einem einzigen Befehl gestartet.
|
||||
|
||||
|
||||
|
||||
1. **Stellen Sie sicher, dass Docker und Docker Compose installiert sind.**
|
||||
|
||||
2. **Navigieren Sie in das Hauptverzeichnis des Projekts.**
|
||||
|
||||
3. **Starten Sie den gesamten Stack:**
|
||||
|
||||
|
||||
|
||||
```bash
|
||||
|
||||
docker-compose up -d --build
|
||||
|
||||
```
|
||||
|
||||
Der `--build`-Parameter ist nur beim ersten Start oder nach Änderungen an den Dockerfiles oder Frontend-Komponenten (z.B. `App.tsx`) notwendig.
|
||||
|
||||
\`\`\`bash
|
||||
docker-compose up -d --build
|
||||
\`\`\`
|
||||
|
||||
Der Build-Prozess kann beim ersten Mal einige Minuten dauern, da das Frontend kompiliert wird.
|
||||
|
||||
### Zugriff
|
||||
|
||||
* **Frontend:** Die Anwendung ist nun unter `http://<Server-IP>:8085` erreichbar.
|
||||
* **Backend:** Die API läuft intern und ist von außen nicht direkt erreichbar (Sicherheits-Feature). Der Frontend-Container leitet API-Anfragen automatisch weiter.
|
||||
|
||||
### Einrichtung Online-Zugriff (Synology Reverse Proxy)
|
||||
|
||||
Um die App sicher über das Internet (z.B. `https://market-intel.deine-domain.de`) erreichbar zu machen:
|
||||
- **Marketing & Intelligence Hub:** Die zentrale Landingpage ist unter `http://<Server-IP>:8090` erreichbar.
|
||||
|
||||
1. Öffnen Sie auf der Synology Diskstation: **Systemsteuerung > Anmeldeportal > Erweitert > Reverse Proxy**.
|
||||
2. Erstellen Sie eine neue Regel:
|
||||
* **Quelle:**
|
||||
* Protokoll: `HTTPS`
|
||||
* Hostname: `market-intel.deine-domain.de`
|
||||
* Port: `443`
|
||||
* HSTS aktivieren: Ja
|
||||
* **Ziel:**
|
||||
* Protokoll: `HTTP`
|
||||
* Hostname: `localhost` (oder Docker-IP)
|
||||
* Port: `8085` (Port des Frontend-Containers)
|
||||
3. (Optional) Weisen Sie im Tab "Sicherheit" ein Let's Encrypt Zertifikat zu.
|
||||
- **B2B Marketing Assistant:** Direkt erreichbar unter `http://<Server-IP>:8090/b2b/`.
|
||||
|
||||
Die App ist nun weltweit sicher per HTTPS erreichbar.
|
||||
- **Market Intelligence Tool:** Direkt erreichbar unter `http://<Server-IP>:8090/market/`.
|
||||
|
||||
|
||||
|
||||
### Entwicklung & Sideloading
|
||||
|
||||
|
||||
|
||||
Dank des Volume-Mountings für die Python-Skripte ist die Entwicklung sehr effizient:
|
||||
|
||||
|
||||
|
||||
1. **Ändern Sie den Python-Code** in `b2b_marketing_orchestrator.py` oder `market_intel_orchestrator.py`.
|
||||
|
||||
2. **Starten Sie den betroffenen Container neu**, damit die Änderungen wirksam werden:
|
||||
|
||||
|
||||
|
||||
```bash
|
||||
|
||||
# Für den B2B Assistant
|
||||
|
||||
docker-compose restart b2b-app
|
||||
|
||||
|
||||
|
||||
# Für das Market Intelligence Backend
|
||||
|
||||
docker-compose restart market-backend
|
||||
|
||||
```
|
||||
|
||||
|
||||
|
||||
Ein zeitaufwändiger `docker-compose build` ist nur bei Änderungen am Frontend-Code, an den `Dockerfile`n oder an den `requirements.txt`/`package.json`-Dateien erforderlich.
|
||||
|
||||
Reference in New Issue
Block a user