🚀 TradingTwins Lead Engine - Documentation

1. Projektübersicht

Die TradingTwins Lead Engine ist ein spezialisiertes Automatisierungs-Tool zur Verarbeitung eingehender B2B-Leads (speziell von der Plattform "tradingtwins").

Ziel: Minimierung der "Time-to-Response" und Maximierung der Lead-Qualität durch automatische Anreicherung und Bewertung.

Das Tool fungiert als Middleware zwischen dem E-Mail-Eingang und dem zentralen Intelligence-Hub (Company Explorer).

2. Architektur & Workflow

System-Komponenten

Lead Engine (Python/Streamlit):
- Hält den State der Leads (Neu, Synced, Drafted).
- Bietet ein Dashboard zur Überwachung.
- Führt die Logik aus.
Company Explorer (CE):
- Single Source of Truth für Firmendaten.
- Führt die eigentliche Web-Recherche (Discovery) und Bewertung (Scoring) durch.
SQLite Datenbank (data/leads.db):
- Lokaler Speicher für Lead-Status und Historie.

Der Prozess-Flow (Sync Logic)

graph TD
    A[E-Mail Eingang] -->|Parser| B(Lead Engine DB)
    B --> C{Check: Existiert Firma in CE?}
    
    C -- JA --> D[Hole ID & Status]
    C -- NEIN --> E[Erstelle Firma via API]
    
    E --> F[Trigger: Discovery & Enrichment]
    D --> G[Update Lead-Status: 'Synced']
    F --> G
    
    G --> H[Dashboard: Ready for Response]

3. Installation & Deployment

Das System läuft als Docker-Container.

Voraussetzungen

Zugriff auf das lead-engine-mvp Git-Repository.
Laufender Company Explorer im selben Netzwerk (oder erreichbar via IP).

Starten (Docker)

# 1. Image bauen
docker build -t lead-engine .

# 2. Container starten
# WICHTIG: Ports mappen & Netwerk beachten
docker run -d \
  -p 8501:8501 \
  --name lead-engine \
  -e CE_API_URL="http://192.168.178.6:8090/ce/api" \
  -e CE_API_USER="admin" \
  -e CE_API_PASS="gemini" \
  lead-engine

Environment Variablen

Variable	Default	Beschreibung
`CE_API_URL`	`http://192.168.178.6:8090/ce/api`	Basis-URL zur Company Explorer API (via Nginx Proxy)
`CE_API_USER`	`admin`	Benutzer für Basic Auth
`CE_API_PASS`	`gemini`	Passwort für Basic Auth
`PYTHONUNBUFFERED`	`1`	Wichtig für Docker Logs

4. Technische Details

Datenmodell (SQLite)

Die lokale Datenbank leads.db speichert:

source_id: ID aus der E-Mail (TradingTwins Lead-ID).
raw_body: Der originale E-Mail-Text.
enrichment_data: JSON-Blob mit Daten vom Company Explorer (Score, Vertical, IDs).
status: new -> synced -> drafted -> sent.

API Integration (Company Explorer)

Das Tool nutzt folgende Endpunkte des CE:

Suche: GET /companies?search={Name}
- Prüft auf Duplikate.
Erstellung: POST /companies
- Payload: {"name": "...", "city": "..."}
Discovery: POST /enrich/discover
- Triggert den Crawler, um Webseite und Branche zu finden.

5. Roadmap / Offene Punkte

[ ] IMAP Live-Anbindung: Ersetzen des aktuellen Mock-Ingests durch echten IMAP-Listener (Skript check_mail.py existiert bereits als Vorlage).
[ ] Response Generation: Abruf eines "Sales Pitches" vom Company Explorer basierend auf den angereicherten Daten (Pain Points, Vertical).
[ ] CRM Push: Optionale Weiterleitung an SuperOffice/Odoo nach erfolgreicher Qualifizierung.

3.4 KiB Raw Blame History