Floke/Brancheneinstufung2
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: Update documentation for consolidated Docker architecture

Browse Source 
- 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:
Floke
2025-12-29 08:49:28 +00:00
parent b78e2fca59
commit 7a33cfe841
3 changed files with 160 additions and 180 deletions
Download Patch File Download Diff File Expand all files Collapse all files

117
b2b_marketing_assistant_plan.md
View File

@@ -87,123 +87,38 @@ Dieses Projekt ist der erste Schritt zur Schaffung eines einheitlichen "Strategy
## 5. Deployment & Betrieb ## 5. Deployment & Betrieb (Konsolidierte Architektur)
Die Anwendung ist nun vollständig in die zentrale Docker-Compose-Architektur des Projekts integriert. Das separate Bauen und Starten einzelner Container ist nicht mehr notwendig.
### Zentraler Start via Docker Compose
Der gesamte Anwendungs-Stack (Proxy, Dashboard, B2B Assistant, Market Intelligence) wird über die `docker-compose.yml`-Datei im Hauptverzeichnis des Projekts verwaltet und gestartet.
1. **Navigieren Sie in das Projekt-Hauptverzeichnis.**
2. **Starten Sie alle Dienste:**
Da das Frontend (`App.tsx`) in das Docker-Image kompiliert wird, müssen Änderungen am Code durch einen **Rebuild** aktiviert werden.
### Standard-Start (für Nutzung)
Wenn das Image bereits aktuell ist:
```bash
docker run -d -p 3004:3002 --name b2b-assistant-instance \
-v "$(pwd)/b2b_marketing_orchestrator.py:/app/b2b_marketing_orchestrator.py" \
-v "$(pwd)/b2b-marketing-assistant/server.cjs:/app/server.cjs" \
-v "$(pwd)/gemini_api_key.txt:/app/gemini_api_key.txt" \
-v "$(pwd)/Log_from_docker:/app/Log_from_docker" \
b2b-marketing-assistant
```
Das Tool ist dann unter `http://localhost:3004` erreichbar. Logs finden Sie im Ordner `Log_from_docker`.
### Update & Rebuild (nach Code-Änderungen)
Wenn Sie `App.tsx`, `index.html` oder `package.json` geändert haben, **müssen** Sie neu bauen:
1. **Alten Container entfernen:**
```bash ```bash
docker-compose up -d --build
docker stop b2b-assistant-instance
docker rm b2b-assistant-instance
``` ```
Der `--build`-Parameter sorgt dafür, dass alle Docker-Images neu erstellt werden. Dies ist bei Änderungen am Frontend (`App.tsx`), an den `Dockerfile`n oder den `requirements.txt`/`package.json` notwendig.
### Zugriff
- Das zentrale Dashboard ist unter `http://<Server-IP>:8090` erreichbar.
- Der **B2B Marketing Assistant** ist direkt über das Unterverzeichnis `http://<Server-IP>:8090/b2b/` zugänglich.
- Der Zugang ist durch Basic Authentication geschützt (Benutzer: `admin`, Passwort: `gemini`).
2. **Image neu bauen:** ### Entwicklung (Sideloading)
Für eine schnelle Entwicklung ist "Sideloading" für die Python-Logik aktiviert. Das bedeutet, die `b2b_marketing_orchestrator.py` wird als Volume in den Container gemountet.
- **Nach Änderungen am Python-Skript:** Ein einfacher Neustart des Containers genügt, um die Änderungen zu übernehmen. Ein kompletter Rebuild ist nicht erforderlich.
```bash ```bash
docker-compose restart b2b-app
docker build -t b2b-marketing-assistant -f b2b-marketing-assistant/Dockerfile .
``` ```
3. **Neu starten:** (siehe Befehl oben).

41
market_intel_backend_plan.md
View File

@@ -82,30 +82,35 @@ Die Logik aus `geminiService.ts` wird in Python-Funktionen innerhalb von `market
2. Ruft die Gemini-API auf. 2. Ruft die Gemini-API auf.
- **Output:** Gibt die `EmailDraft`-Objekte als JSON-Array aus. - **Output:** Gibt die `EmailDraft`-Objekte als JSON-Array aus.
## 4. Nächste Schritte (für die nächste Sitzung) ## 4. Deployment & Betrieb in der Konsolidierten Architektur
1. Die neuesten Code-Änderungen pullen (`git pull`). Das Market Intelligence Tool ist nun vollständig in die zentrale Docker-Compose-Architektur des Projekts integriert. Das separate Bauen und Starten einzelner Container, wie in den alten Abschnitten beschrieben, ist nicht mehr der richtige Weg.
2. Das Docker-Image neu bauen, um die Korrektur zu übernehmen: `docker build -t market-intel-backend .`
3. Den alten Container stoppen/entfernen und den neuen starten: `docker run -p 3001:3001 --name market-intel-backend-instance market-intel-backend`
4. Den React-Dev-Server starten und den End-to-End-Test erneut durchführen.
## 5. Aktueller Status und Debugging-Protokoll (Stand: 2025-12-21 - Abschluss der Sitzung) ### Zentraler Start via Docker Compose
### Status: End-to-End System voll funktionsfähig, Grounded & UX-optimiert! Der gesamte Anwendungs-Stack (Proxy, Dashboard, B2B Assistant, Market Intelligence) wird über die `docker-compose.yml`-Datei im Hauptverzeichnis des Projekts verwaltet und gestartet.
Wir haben heute das gesamte System von einer instabilen n8n-Abhängigkeit zu einem robusten, autarken Python-Service transformiert. 1. **Navigieren Sie in das Projekt-Hauptverzeichnis.**
2. **Starten Sie alle Dienste:**
```bash
docker-compose up -d --build
```
Der `--build`-Parameter sorgt dafür, dass alle Docker-Images neu erstellt werden. Dies ist bei Änderungen am Frontend (`App.tsx`), an den `Dockerfile`n oder den `requirements.txt`/`package.json` notwendig.
**Wichtigste Errungenschaften:** ### Zugriff
- **Präzises Lookalike-Sourcing:** Die Konkurrenten-Identifikation wurde von einer reinen Branchensuche auf eine **ICP-basierte Lookalike-Suche** umgestellt. Die Ergebnisse sind nun hochrelevant und thematisch am Referenzkunden ausgerichtet.
- **Deep Tech Audit mit Beweisführung:** Der Audit-Prozess (Schritt 3) nutzt nun eine kaskadierende Suchstrategie (Homepage-Scrape + gezielte SerpAPI-Suchen). Die KI zitiert konkrete Beweise (z.B. aus Stellenanzeigen) und liefert verifizierbare Links ("Proof").
- **Echtes Terminal-Feedback:** Die UI zeigt nun während des Audits einen **echten Live-Log** des Agenten an (Searching, Scraping, Analyzing), was die Wartezeit transparent macht.
- **Robustes Logging:** Umstellung auf **Tages-Logdateien** (z.B. `2025-12-21_market_intel.log`), die im `/app/Log` Verzeichnis (via Docker Volume) gespeichert werden und den vollständigen Verlauf inkl. Prompts enthalten.
- **Optimierte Infrastruktur:** Schlankes Docker-Image mit Bind Mounts ermöglicht **Hot-Reloading** des Python-Codes und direkten Zugriff auf Logs und Keys (`serpapikey.txt`, `gemini_api_key.txt`).
**Gelöste Probleme heute:** - Das zentrale Dashboard ist unter `http://<Server-IP>:8090` erreichbar.
- **Abhängigkeits-Chaos:** Vollständige Entkopplung von `helpers.py` und `config.py` im Backend-Orchestrator. - Das **Market Intelligence Tool** ist direkt über das Unterverzeichnis `http://<Server-IP>:8090/market/` zugänglich.
- **API-Endpunkt Fehler:** Behebung aller `v1beta` 404 Fehler durch Umstieg auf direkte REST-Calls (Gemini v1). - Der Zugang ist durch Basic Authentication geschützt (Benutzer: `admin`, Passwort: `gemini`).
- **Frontend-Abstürze:** Absicherung des Reports gegen fehlende Datenpunkte.
### Entwicklung (Sideloading)
Für eine schnelle Entwicklung ist "Sideloading" für die Python-Logik aktiviert. Das bedeutet, die `market_intel_orchestrator.py` wird als Volume in den Container gemountet.
- **Nach Änderungen am Python-Skript:** Ein einfacher Neustart des Containers genügt, um die Änderungen zu übernehmen. Ein kompletter Rebuild ist nicht erforderlich.
```bash
docker-compose restart market-backend
```
--- ---

182
readme.md
View File

@@ -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** Die konsolidierte Lösung besteht aus vier Haupt-Containern, die von `docker-compose.yml` gesteuert werden:
- **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.
**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. * **Routing:** Leitet Anfragen an die richtigen Anwendungs-Container weiter:
2. Navigieren Sie in das Hauptverzeichnis.
3. Starten Sie den Stack: * `/` -> 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 ### 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**. - **B2B Marketing Assistant:** Direkt erreichbar unter `http://<Server-IP>:8090/b2b/`.
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.
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.