Docs: Add detailed architectural documentation

TRADING_TWINS_DOCUMENTATION.md

@@ -0,0 +1,105 @@
+# 🚀 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.