# Technisches Zielbild: GTM-Engine & Google Cloud Integration

Dieses Dokument beschreibt die Architektur und den Datenfluss der **GTM-Engine (Go-to-Market Engine)**.

## Executive Summary: Was wir tun
Wir automatisieren die **Qualifizierung von B2B-Accounts** (Firmen), um den Vertrieb gezielter und effizienter zu steuern ("Whale Hunting").

Anstatt dass ein Mitarbeiter manuell 20 Minuten lang Webseiten liest, um herauszufinden, ob eine Firma relevant ist, übernimmt dies das System automatisiert:
1.  **Input:** Firmenname & Webseite (aus CRM oder Lead-Liste).
2.  **Analyse:** Wir aggregieren öffentlich verfügbare Daten (Website-Text, Impressum, Wikipedia).
3.  **KI-Verarbeitung:** Ein Sprachmodell (Gemini) agiert als "Lese-Assistent". Wir stellen ihm gezielte Fragen an den Kontext (z.B. *"Hat diese Firma mehr als 500 Mitarbeiter?", "Nutzen sie Roboter?", "Sind sie im Bereich Logistik tätig?"*).
4.  **Output:** Strukturierte Daten (Branche, Potential-Score, Summary) fließen zurück ins CRM zur Vertriebssteuerung.

**Wichtig:** Es findet **keine** automatisierte Entscheidung über natürliche Personen statt. Wir bewerten Firmen-Potentiale.

## Kern-Prinzipien
1.  **Trennung von Identität & Daten:** Nutzung von Unternehmens-Identitäten (Managed Google ID) statt privater Konten.
2.  **Datensparsamkeit:** KI-Verarbeitung erfolgt primär auf anonymen Firmendaten (B2B), nicht auf Personendaten.
3.  **Lokale Hoheit:** Die Business-Logik (Python/Docker) läuft kontrolliert lokal oder im Intranet, nicht "in der Cloud".

## Architektur-Übersicht

```mermaid
graph TD
    %% Subgraph: Corporate Environment (Wackler/RoboPlanet)
    subgraph Corporate_IT ["🏢 Wackler / RoboPlanet Umgebung"]
        
        subgraph User_Layer ["🧑‍💻 User & Identity"]
            User[("Christian (User)")]
            CorpID["Corporate Google ID<br/>(@roboplanet.de / @wackler-group.de)"]
            User --> CorpID
        end

        subgraph Local_Execution ["⚙️ Execution Layer (Local/Server)"]
            Docker["🐳 Docker Container<br/>(GTM-Engine / Python)"]
            
            subgraph Data_Handling ["🛡️ Daten-Verarbeitung"]
                RawData[("Rohdaten<br/>(Websites, Listen)")]
                Anonymizer["⚙️ Pre-Processing<br/>(Filterung PII / Personendaten)"]
            end
            
            ResultStorage[("Ergebnisse<br/>(Notion / CRM / Excel)")]
        end
    end

    %% Subgraph: Google Cloud Platform (Managed)
    subgraph Google_Cloud ["☁️ Google Cloud Platform (Enterprise Tenant)"]
        
        subgraph IAM_Security ["🔐 Security & Billing"]
            GCP_Project["GCP Projekt<br/>(z.B. 'gtm-engine-prod')"]
            ServiceAccount["🤖 Service Account<br/>(Technischer User für API)"]
            Billing["💳 Corporate Billing<br/>(Zentrale Abrechnung)"]
        end

        subgraph AI_Services ["🧠 AI Services (Vertex AI / Gemini)"]
            GeminiAPI["⚡ Gemini API<br/>(Enterprise Mode: Zero Logging)"]
        end
    end

    %% Data Flow Connections
    CorpID -.->|"Verwaltet"| GCP_Project
    Docker -->|"Nutzt API Key"| ServiceAccount
    ServiceAccount -->|"Authentifiziert"| GeminiAPI
    
    RawData --> Anonymizer
    Anonymizer -->|"1. Anonymisierter Prompt<br/>(Nur Firmendaten)"| Docker
    Docker -->|"2. API Request (HTTPS/TLS)"| GeminiAPI
    GeminiAPI -->|"3. JSON Response<br/>(Strukturierte Daten)"| Docker
    Docker -->|"4. Speicherung"| ResultStorage

    %% Styling
    style Corporate_IT fill:#f9f9f9,stroke:#333,stroke-width:2px
    style Google_Cloud fill:#e8f0fe,stroke:#4285f4,stroke-width:2px
    style Anonymizer fill:#fff3e0,stroke:#f57c00,stroke-dasharray: 5 5
    style GeminiAPI fill:#e8f0fe,stroke:#4285f4,stroke-width:4px
```

## Erläuterung für die IT

1.  **Identity (IAM):**
    *   Es wird kein "Schatten-Account" genutzt. Christian authentifiziert sich mit seiner bestehenden Corporate Identity (`@roboplanet`).
    *   Für die automatisierte Ausführung (Skripte) wird später ein **Service Account** beantragt, dessen Schlüssel (JSON Key) sicher im lokalen Container verwaltet wird (Secrets Management).

2.  **Google Cloud Projekt:**
    *   Wir benötigen ein dediziertes GCP-Projekt (z.B. `rp-marketing-intel`), das im Rechnungskreis der Firma hängt.
    *   Vorteil: Volle Transparenz über Kosten und Nutzung im Admin-Dashboard der IT.

3.  **Environment Strategie (Dev/Prod Trennung):**
    *   Um Entwicklungskosten von Betriebskosten sauber zu trennen und die Stabilität zu gewährleisten, werden **zwei separate GCP-Projekte** empfohlen:
        *   **`rp-marketing-intel-dev`**: Sandbox für Entwicklung (Gemini CLI, Tests). Hier können Budgets gedeckelt und Quotas flexibel genutzt werden, ohne den Betrieb zu gefährden ("Blast Radius" Minimierung).
        *   **`rp-marketing-intel-prod`**: Stabile Umgebung für den Company Explorer. Exklusive Quotas und striktes Monitoring für den operativen Betrieb.

4.  **Datenschutz (DSGVO):**
    *   **Input:** Wir senden Webseiten-Texte und Firmennamen an die API. Wir senden *keine* Mitarbeiterlisten oder Kunden-Adressdaten zur Analyse.
    *   **Enterprise-Garantie:** Durch Nutzung der Enterprise-Verträge (via GCP) ist vertraglich geregelt, dass Google die Daten **nicht** zum Training eigener Modelle verwendet (anders als bei der kostenlosen ChatGPT/Gemini-Consumer-Version).

## Datenschutz- & Lizenz-Architektur (Das Zwei-Wege-Modell)

Um maximale Sicherheit und Compliance zu gewährleisten, trennen wir technisch strikt zwischen **Automatisierung** (Massenverarbeitung) und **Assistenz** (Ad-hoc Arbeit).

```mermaid
flowchart TD
    User[User: Floke]
    
    subgraph Safe_Space_GCP ["Pfad A: Die Engine (Automation)"]
        style Safe_Space_GCP fill:#e6f4ea,stroke:#137333
        API[Python Scripts / GTM-Engine] --> Vertex[Google Vertex AI API]
        Vertex --> Processing[Data Processing in EU]
        Processing -- "No Training / Zero Retention" --> Output_API[Strukturierte Daten]
    end

    subgraph Safe_Space_Workspace ["Pfad B: Der Assistent (Ad-Hoc)"]
        style Safe_Space_Workspace fill:#e8f0fe,stroke:#1967d2
        Browser[Browser / Chat] --> Gemini[Gemini Enterprise App]
        Gemini -- "Enterprise Terms / No Training" --> Output_Chat[Text / Drafts]
    end

    User -- "Programming / CLI" --> API
    User -- "Manual / Web" --> Browser
```

### Pfad A: Die Engine (Google Cloud Platform / Vertex AI)
*   **Einsatzzweck:** Automatisierte Skripte, Massenanalyse (GTM-Engine), Coding.
*   **Lizenz:** Pay-per-Use (über GCP Projekt). Keine User-Lizenz erforderlich.
*   **Datenschutz:**
    *   **GCP Enterprise Terms:** Standardmäßig **kein Training** auf Kundendaten.
    *   **Region Lock:** Datenverarbeitung wird technisch auf `europe-west3` (Frankfurt) oder `europe-west4` gezwungen.
    *   **Zero Retention:** API-Calls werden nach Verarbeitung gelöscht (stateless).

### Pfad B: Der Assistent (Google Workspace / Gemini Enterprise)
*   **Einsatzzweck:** Ad-hoc Chat im Browser (Texte umschreiben, Brainstorming), Integration in Docs/Gmail.
*   **Lizenz:** Erfordert **"Gemini Enterprise"** (oder Business) Add-on für den User.
*   **Datenschutz:**
    *   Nur mit der Enterprise-Lizenz greift die "Enterprise Data Protection".
    *   Ohne Lizenz ist dieser Pfad **gesperrt** (aktueller Status) oder unsicher (Consumer Terms).
    *   **Vorschlag:** Freischaltung nur für Pilot-User mit Lizenz.

## Datenschutz & Compliance Strategie

### Grundsatz: "Safe Space" & Transparenz
Wir verfolgen einen zweistufigen Ansatz ("Salami-Taktik"), um Datenschutzrisiken zu minimieren und Vertrauen aufzubauen.

**Phase 1: Der "Safe Space" (Aktueller Status)**
*   **Datenbasis:** Ausschließlich öffentlich zugängliche B2B-Firmendaten (Handelsregister, Webseiten).
*   **Personenbezug:** Keiner (oder nur reine B2B-Kontaktdaten gem. DSGVO Erwägungsgrund 47 / berechtigtes Interesse).
*   **Infrastruktur:** Nutzung der bestehenden Google Workspace Enterprise Umgebung ("Walled Garden").
*   **Training:** Expliziter Ausschluss der Datennutzung zu Trainingszwecken in der Google Admin Konsole (Enterprise Data Protection).

**Phase 2: Erweiterte Szenarien (Zukunft / Genehmigungspflichtig)**
*   **Szenario:** Nutzung interner Daten (z.B. Support-Tickets) zur Mustererkennung.
*   **Voraussetzung:** Vorherige Abstimmung eines separaten Datenschutzkonzeptes (z.B. PII-Redaction/Schwärzung vor API-Transfer, Nutzung lokaler LLMs).
*   **Commitment:** Keine Verarbeitung kritischer Daten ohne explizites "Go" durch den Datenschutzbeauftragten.

### Technische Maßnahmen
1.  **Vertrag:** Nutzung von Vertex AI im Rahmen des bestehenden Google Workspace Enterprise-Vertrags (DPA).
2.  **Zero Retention:** Nutzung der API im Modus ohne Datenspeicherung seitens Google.
3.  **Data Residency:** Konfiguration der Datenverarbeitung in EU-Rechenzentren (Frankfurt/Belgien) wo möglich.

## Backend API (Company Explorer)

Das System verfügt bereits über eine standardisierte, dokumentierte API (FastAPI) zur Datenverarbeitung. Dies ermöglicht eine saubere Trennung von Frontend und Backend sowie eine granulare Zugriffskontrolle.

**Core Endpoints:**

| Methode | Pfad | Beschreibung |
| :--- | :--- | :--- |
| `GET` | `/api/health` | System Status Check |
| `GET` | `/api/companies` | Liste von Unternehmen (Filterbar, Sortierbar) |
| `GET` | `/api/companies/{id}` | Detailansicht eines Unternehmens |
| `POST` | `/api/companies` | Manuelle Anlage eines Unternehmens |
| `POST` | `/api/companies/bulk` | Massenimport (Batch-Processing) |
| `GET` | `/api/companies/export` | CSV Export der angereicherten Daten |

**Enrichment & KI-Analyse:**

| Methode | Pfad | Beschreibung |
| :--- | :--- | :--- |
| `POST` | `/api/enrich/discover` | Startet Discovery-Prozess (Website-Suche) |
| `POST` | `/api/enrich/analyze` | Startet KI-Analyse (Scraping + Klassifizierung) |
| `PUT` | `/api/companies/{id}/industry` | Manuelle Korrektur der KI-Branchenzuordnung |
| `POST` | `/api/companies/{id}/override/*` | Manuelle Overrides für kritische Datenquellen (Website, Wikipedia, Impressum) |

**Quality Assurance:**

| Methode | Pfad | Beschreibung |
| :--- | :--- | :--- |
| `POST` | `/api/companies/{id}/report-mistake` | Melden von Datenfehlern ("Human in the Loop") |
| `GET` | `/api/mistakes` | Übersicht gemeldeter Fehler zur Überprüfung |
| `PUT` | `/api/mistakes/{id}` | Status-Update für Fehlermeldungen (Approved/Rejected) |

**Stammdaten & Kataloge:**

| Methode | Pfad | Beschreibung |
| :--- | :--- | :--- |
| `GET` | `/api/robotics/categories` | Katalog der Robotik-Kategorien |
| `GET` | `/api/industries` | Katalog der Branchen |
| `GET` | `/api/job_roles` | Katalog der Job-Rollen |