Brancheneinstufung2/ARCHITEKTUR_GCP_SETUP.md

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

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

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 (Custom Chat)"]
        style Safe_Space_Workspace fill:#e8f0fe,stroke:#1967d2
        Browser[Browser / Local App] --> PythonApp[Custom Python Chatbot]
        PythonApp -- "Nutzt API Key" --> Vertex
    end

    User -- "Programming / CLI" --> API
    User -- "Manual / Chat" --> 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 (Lokaler Chatbot)

• Einsatzzweck: Ad-hoc Chat und Textarbeit.
• Lösung: Da wir keine Gemini-Lizenzen für 350 User kaufen, bauen wir ein eigenes, leichtgewichtiges Chat-Interface (Python Streamlit).
• Datenschutz: Dieses Tool greift auf Pfad A (GCP API) zu.
  • Vorteil: Wir nutzen die sichere Enterprise-API, ohne Office-Lizenzen ändern zu müssen.
  • Daten bleiben im kontrollierten GCP-Bereich.

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.

Strategie zur Lizenzierung & Kosten (Der "Cloud Identity Free" Ansatz)

Ausgangslage: RoboPlanet nutzt aktuell den "Cloud Identity Free" Tarif (primär für Android-Geräte-Verwaltung). Ein Upgrade auf kostenpflichtige Workspace-Lizenzen für alle 350+ User würde immense Fixkosten verursachen.

Lösung: Entkopplung von User-Lizenz und KI-Leistung Wir vermeiden ein globales Lizenz-Upgrade. Stattdessen nutzen wir die Google Cloud Platform (GCP).

• Technik: GCP-Projekte sind technisch vom Office-Tarif entkoppelt.
• Kosten: Wir zahlen rein nutzungsbasiert (Pay-per-Use) für die API-Aufrufe.
• Vorteil: Keine Änderung am bestehenden "Free Tier" Vertrag notwendig. Enterprise-Security gilt im GCP-Projekt automatisch.

Spickzettel für den Termin (Fragen & Argumente)

1. Zum Lizenz-Status ("Kostenvermeidung")

Argument: "Wir wollen auf keinen Fall für 350 User neue Lizenzen kaufen müssen, nur damit ich KI nutzen kann. Da wir im 'Cloud Identity Free' Tarif sind, ist der Weg über die Google Cloud Platform (GCP) der einzig sinnvolle. Dort zahlen wir nur, was wir verbrauchen (Pay-per-Use), ohne den Hauptvertrag anzufassen."

2. Zur Architektur ("Safe Space GCP")

Argument: "Im GCP-Projekt gelten automatisch die B2B-Enterprise-Terms (kein Training auf Daten), egal welchen Status mein User hat. Ich werde technisch erzwingen, dass die Datenverarbeitung in Frankfurt (europe-west3) stattfindet."

3. Zur Datennutzung

Angebot: "Ich richte eine strikte Trennung ein:

• Entwicklung (Dev): Hier testen wir.
• Produktion (Prod): Hier laufen die Tools. Dadurch verhindern wir, dass Testdaten in produktive Systeme gelangen oder Kosten aus dem Ruder laufen."

Vorlage: Nachricht an die IT (Teams/Mail)

Hi [Name],

ich habe mich nochmal tiefer in die Google-Lizenz-Thematik eingegraben. Da wir ja aktuell im 'Cloud Identity Free' Tarif sind (primär für die Android-Geräte), würde ein Upgrade oder Lizenz-Wechsel bei 350 Usern ja sofort massive Kosten verursachen. Das wollen wir auf keinen Fall auslösen, nur weil ich ein Tool brauche.

Daher mein Vorschlag für den schlanken Weg: Wir lassen an den User-Konten/Lizenzen (Free Tier) alles exakt so, wie es ist. Stattdessen nutzen wir für meine KI-Themen einfach die Google Cloud Platform (GCP). Ich habe gesehen, dass ich darauf mit meinem User sogar schon Zugriff habe.

Das GCP-Projekt ist technisch komplett unabhängig vom Office-Tarif. Wir zahlen dort rein Pay-per-Use für die API-Aufrufe (oft nur Cent-Beträge im laufenden Betrieb).

Was mir dafür noch fehlt, ist das 'Billing' (Rechnungskonto): Aktuell kann ich keine APIs aktivieren, weil kein Zahlungsmittel hinterlegt ist.

Meine Bitte: Könntet ihr mir bitte zwei Projekte anlegen und mit dem zentralen Firmen-Rechnungskonto verknüpfen?

1. roboplanet-ai-dev (Für Entwicklung & Tests, Sandbox)
2. roboplanet-ai-prod (Für den stabilen Betrieb der Tools)

Danach könnt ihr mir einfach Owner-Rechte auf diese beiden Projekte geben. Den Rest (API-Aktivierung, Service Accounts, Region-Lock auf Frankfurt) richte ich dann selbst ein.

Das wäre die sauberste Lösung: Keine Fixkosten durch Lizenz-Upgrades, klare Trennung von Spielwiese und Produktion, und volle Kostentransparenz.

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