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

### Der Prozess-Flow (Sync Logic)

```mermaid
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)

```bash
# 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:

1.  **Suche:** `GET /companies?search={Name}`
    *   Prüft auf Duplikate.
2.  **Erstellung:** `POST /companies`
    *   Payload: `{"name": "...", "city": "..."}`
3.  **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.