# Migration Guide: Google AI Builder Apps -> Local Docker Stack

> **CRITICAL WARNINGS & BEST PRACTICES (READ BEFORE MIGRATION):**
>
> 1.  **DIE GOLDENE REGEL DER STRINGS:** Nutze **NIEMALS** `f"""..."""` für komplexe Prompts oder Listen-Operationen mit verschachtelten Keys. Es führt unweigerlich zu `SyntaxError: unterminated string literal`. Nutze **AUSSCHLIESSLICH Triple Raw Quotes (`r"""..."""`)** und die **`.format()`** Methode.
> 2.  **SDK WAHL (DUAL SDK):** Das moderne `google-genai` ist gut, aber das Legacy `google-generativeai` ist oft stabiler für reinen Text (`gemini-2.0-flash`). Nutze die "Dual SDK Strategy" aus `helpers.py`.
> 3.  **GROUNDED TRUTH (MUSS):** Verlasse dich niemals auf das Wissen des Modells allein. Implementiere **immer** Web-Scraping (Homepage + Unterseiten) und SerpAPI-Suchen, um das Modell mit Fakten zu füttern.
> 4.  **DOCKER VOLUMES:** Mounte **nur spezifische Dateien**, niemals den `dist`-Ordner überschreiben. Bei Syntax-Fehlern, die trotz Korrektur bleiben: `docker-compose build --no-cache`.

---

## 0. Der "Quick-Start" Checkliste (5-Minuten-Plan)

1.  **SDK:** Stehen beide SDKs in der `requirements.txt`?
2.  **Prompts:** Sind alle Prompts als `r"""...""".format()` angelegt?
3.  **Grounding:** Werden Produkt- und Branchenseiten gescrapt?
4.  **Package.json:** Sind Build-Tools in `dependencies`?
5.  **Vite Config:** Ist `base: './'` gesetzt?

---

## 1. Vorbereitung & Abhängigkeiten (Common Pitfalls)

Bevor Code kopiert wird, müssen die Grundlagen stimmen.

### 1.1 Package.json Check (Frontend Build-Falle)
Build-Tools wie `vite`, `@vitejs/plugin-react` oder `typescript` müssen in den `dependencies` stehen, nicht in `devDependencies`. Der multi-stage Docker-Build installiert standardmäßig keine dev-dependencies.

### 1.2 Python Syntax & F-Strings (Der Prompt-Albtraum)
Verschachtelte Anführungszeichen in F-Strings sprengen den Python-Parser in vielen Umgebungen.
**RICHTIG:**
```python
prompt = r"""
Analysiere "{name}". Antworte JSON: {{"key": "value"}}
""".format(name=item['name'])
```

### 1.3 Volume Mounts & Datei-Synchronisierung
Einzeldatei-Mounts (`- ./file.py:/app/file.py`) sind oft unzuverlässig bei schnellen Code-Änderungen. Im Zweifel das Image neu bauen.

---

## 2. Die AI Engine (Standard)

Nutze für alle Services die Logik aus `gtm_architect_orchestrator.py`:
1.  **Dual SDK Support** (Legacy + Modern).
2.  **Modell-Fallback** (Versuche 2.0-flash, dann 1.5-flash).
3.  **Grounded Scraping** vor jedem KI-Aufruf.

---
*Dokumentation finalisiert am 10.01.2026 nach der Competitor-Analysis Odyssee.*