# Technisches Zielbild: GTM-Engine & Google Cloud Integration

Dieses Diagramm visualisiert den geplanten Datenfluss und die Architektur für den sicheren Betrieb der GTM-Engine (Growth-Marketing) in der Unternehmensumgebung.

## 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.  **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).

## 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 |