Brancheneinstufung2/docs/market_intel_backend_plan.md

Plan: Umsetzung des "General Market Intelligence" Backends als Python-Service

Dieses Dokument beschreibt den Plan zur Umsetzung der Backend-Logik für die React-Anwendung unter /general-market-intelligence als robusten, faktenbasierten Python-Service. Dieser Ansatz ersetzt die ursprüngliche Idee einer n8n-Migration.

1. Zielsetzung & Architektur-Entscheidung

Das primäre Ziel ist die Schaffung eines transparenten, kontrollierbaren und faktenbasierten Backend-Prozesses. Die ursprüngliche Implementierung der React-App zeigte Schwankungen in der Ergebnisqualität und mangelnde Nachvollziehbarkeit, da die KI-Aufrufe nicht auf verifizierbaren Daten basierten ("Grounding").

Nach einer Analyse wurde entschieden, von einer n8n-basierten Lösung Abstand zu nehmen und stattdessen einen dedizierten Python-Service zu entwickeln.

Gründe für Python statt n8n:

• Maximale Kontrolle & Transparenz: Ein Python-Skript ermöglicht detailliertes Logging, schrittweises Debugging und die volle Kontrolle über jeden Aspekt der Logik – von Web-Scraping bis zu den API-Aufrufen. Dies ist entscheidend, um die Ergebnisqualität sicherzustellen.
• Nahtlose Projekt-Integration: Das Python-Skript fügt sich perfekt in die bestehende, Python-basierte Projektstruktur ein und kann auf geteilte Module (config.py, helpers.py) zugreifen.
• Robuste Fehlerbehandlung: Komplexe Fehler- und Wiederholungslogiken lassen sich in Python präziser und robuster implementieren als in einer visuellen Workflow-Engine.
• Vermeidung von Plattform-Limitierungen: Wir umgehen technische Hürden wie die eingeschränkte REST-API der selbstgehosteten n8n-Version.

2. Architektur: React-Frontend mit Python-Backend

Die Architektur besteht aus drei Kernkomponenten, die in einem Docker-Container gekapselt werden:

1. React-Frontend (unverändert): Die bestehende Anwendung in /general-market-intelligence bleibt die interaktive Benutzeroberfläche.
2. Node.js API-Brücke (server.js): Ein minimaler Express.js-Server, der im selben Verzeichnis wie die React-App läuft. Seine einzige Aufgabe ist es, HTTP-Anfragen vom Frontend entgegenzunehmen und sie sicher an das Python-Skript weiterzuleiten.
3. Python-Orchestrator (market_intel_orchestrator.py): Das Herzstück der Logik. Dieses Kommandozeilen-Skript ist zuständig für:
   • Web-Scraping zur Gewinnung von Rohdaten ("Ground Truth").
   • Text-Extraktion und -Bereinigung.
   • Gezielte und "geerdete" Aufrufe an die Gemini-API.
   • Rückgabe der strukturierten Ergebnisse als JSON über die Konsole (stdout).

Deployment: Der gesamte Backend-Service (Node.js-Brücke und Python-Skript) wird in einem Docker-Container verpackt, um eine konsistente, "immer online" verfügbare Umgebung zu schaffen.

3. Kernfunktionen als Python-Module

Die Logik aus geminiService.ts wird in Python-Funktionen innerhalb von market_intel_orchestrator.py nachgebildet, wobei der Fokus auf Faktenbasiertheit liegt.

---

Funktion 1: generate_search_strategy

• Trigger: Aufruf durch die Node.js-Brücke mit --mode generate_strategy.
• Input: reference_url und context_content (Strategie-Dokument).
• Prozess:
  1. Scraping (Grounding): Lädt den HTML-Inhalt der reference_url.
  2. Text-Extraktion: Bereinigt das HTML zu sauberem Text.
  3. KI-Analyse: Ruft die Gemini-API mit einem Prompt auf, der explizit anweist, die digitalen Signale aus dem bereitgestellten Website-Text und dem Strategie-Kontext abzuleiten.
• Output: Gibt das SearchStrategy-JSON auf der Konsole aus.

---

Funktion 2: identify_competitors

• Trigger: Aufruf mit --mode identify_competitors.
• Input: reference_url und target_market.
• Prozess:
  1. Ruft die Gemini-API mit einem Google-Search-Tool auf, um ähnliche Unternehmen zu finden.
• Output: Gibt eine JSON-Liste der gefundenen Unternehmen aus.

---

Funktion 3: run_full_analysis

• Trigger: Aufruf mit --mode run_analysis.
• Input: Eine Liste von Unternehmensnamen und die zuvor generierte Suchstrategie.
• Prozess:
  1. Iteriert über die Unternehmensliste.
  2. Für jedes Unternehmen:
     • Sucht die offizielle Website (z.B. über SerpAPI).
     • Scrapt die relevanten Seiten basierend auf den targetPageKeywords der digitalen Signale.
     • Ruft die Gemini-API auf, um die Signale basierend auf dem gescrapten Inhalt zu bewerten.
• Output: Gibt eine Liste von AnalysisResult-Objekten aus.

---

Funktion 4: generate_outreach_campaign

• Trigger: Aufruf mit --mode generate_outreach.
• Input: company_data (ein AnalysisResult-Objekt), knowledge_base (Strategie-Dokument) und reference_url.
• Prozess:
  1. Baut den Prompt für die Erstellung der E-Mail-Kampagne, wobei die faktenbasierten dynamicAnalysis-Ergebnisse als Kern der Personalisierung dienen.
  2. Ruft die Gemini-API auf.
• Output: Gibt die EmailDraft-Objekte als JSON-Array aus.

4. Deployment & Betrieb in der Konsolidierten Architektur

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.

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:

   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 Dockerfilen oder den requirements.txt/package.json notwendig.

Zugriff

• Das zentrale Dashboard ist unter http://<Server-IP>:8090 erreichbar.
• Das Market Intelligence Tool ist direkt über das Unterverzeichnis http://<Server-IP>:8090/market/ zugänglich.
• Der Zugang ist durch Basic Authentication geschützt (Benutzer: admin, Passwort: gemini).

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.

  docker-compose restart market-backend
  

---

Status Update (2026-01-14) - Quality & Stability Refinements

Erreichte Meilensteine:

1. Anti-Halluzinations-Fix (Technographic Audit):

   • Problem: Die KI hat aufgrund von Suggestiv-Prompts ("Look for SAP Ariba") oft Technologien halluziniert oder irrelevante Systeme als Wettbewerber eingestuft.

   • Lösung: Entfernung aller festcodierten "Suggestiv-Listen" aus dem Code. Der Audit sucht nun rein faktenbasiert oder basierend auf der expliziten Strategie-Eingabe.

   • Ergebnis: Keine "falschen Feinde" mehr. Wenn keine Konkurrenz-Hardware gefunden wird, wird korrekt "Greenfield" (Status Quo: Manuell) erkannt.

2. Outreach-Optimierung ("Strategic Observer"):

   • Prompting: Radikale Überarbeitung des Outreach-Prompts.

   • Stil: Weg vom "Verkäufer", hin zum "Scharfsinnigen Branchenbeobachter".

   • Opportunity Bridge: Die E-Mails schlagen in der ersten Nachricht sofort die Brücke von der Beobachtung (z.B. "Expansion") zur Lösungskategorie (z.B. "Autonome Reinigungsrobotik"), ohne plump Features zu verkaufen.

   • Kontext-Sensitivität: Technologische Signale (wie ERP-Systeme) werden nur noch bei Rollen erwähnt, für die sie relevant sind (CIO, CFO), aber bei operativen Rollen (Facility Management) ausgeblendet, um Verwirrung zu vermeiden.

3. Produktionsreife:

   • Der Prozess liefert nun konsistent hochwertige, C-Level-taugliche Ansprachen, die strategische Schmerzpunkte mit operativen Lösungen verbinden.

Nächste Schritte:

• Regelbetrieb & Monitoring: Überwachung der Qualität bei neuen Branchen.

--- End of content ---