# Phase 2: Gemini-Integration + Asset-Pipeline - Context

**Gathered:** 2026-03-29 (assumptions mode)
**Status:** Ready for planning

<domain>
## Phase Boundary

Gemini-API funktioniert für Text und Bild, Character Sheets sind generiert und eingebunden. Umfasst: Config-Loader, Text-API-Client mit Retry, Bild-API-Client mit Character Consistency, Fallback-Texte und -Bilder, Rate-Limiting, Build-Script für Asset-Generierung, generierte Avatare im Welcome-Screen, Begleitfigur-Texte (Begrüssung, Buchstaben-Vorstellung, Wald-Kommentar). Kein Wald-Wachstum (Phase 3), keine Übungsphasen-Verbindung (Phase 3), kein Audio (Phase 4).
</domain>

<decisions>
## Implementation Decisions

### Build Script Runtime
- **D-01:** `scripts/generate-assets.ts` runs in Node.js via `npx tsx` (new devDependency). Reads `public/config.json` via `fs.readFileSync`. The browser API client uses `fetch('/config.json')`. A shared isomorphic Gemini API module using only `fetch()` serves both contexts — only the config-loading layer differs.
- **D-02:** Build script generates 4 Character Sheets + 4 Avatars + 1 Style Reference, saves as PNG to `src/assets/companions/{type}/` and `src/assets/style-reference/`. These are checked into git.

### IndexedDB Schema Extension
- **D-03:** Keep DB at version 1. API call counts stored as fields in the existing `settings` store (e.g. `apiCallsToday: number`, `lastApiCallDate: string`). No dedicated `apiLog` store — simple counting suffices for rate-limiting (GAPI-06). Detailed per-call logging is not required.
- **D-04:** Add read/write helper methods for `companionAssets` and `styleReference` stores in `db.ts`. These stores exist structurally from Phase 1 but lack accessor functions.

### Welcome Screen Avatar Replacement
- **D-05:** Static imports in `characters.ts` for each avatar file. Each `CompanionDefinition` gets an `avatarUrl: string` field with the Vite-resolved URL. Welcome screen renders `<img>` instead of emoji spans. Type-safe, explicit mapping.
- **D-06:** Fallback to emoji if avatar image fails to load (onerror handler on `<img>`).

### Gemini API Client Architecture
- **D-07:** Isomorphic API module `src/api/gemini.ts` with `generateText(prompt, systemPrompt)` and `generateImage(prompt, referenceImages[])`. Uses only `fetch()` — works in both Node.js 18+ and browser.
- **D-08:** Reference images sent as Base64-encoded `inlineData` (standard Gemini REST pattern). `response_modalities: ["IMAGE"]` for image generation. Verify exact format against current Gemini docs at implementation time.
- **D-09:** Retry logic: 3 attempts with exponential backoff (1s, 2s, 4s). On final failure, return null and let caller use fallback.
- **D-10:** Rate-limiting: Max 1 image + 1 text per exercise unit. Check counts in `settings` store before API call. Reset daily.

### Fallback System
- **D-11:** Fallback texts stored as static arrays in `src/companion/fallbacks.ts`: 10 greetings, 10 forest comments, letter introductions for levels 1-6. All in simple German, max 25 words, no performance praise.
- **D-12:** Fallback images: 5-10 simple SVG illustrations in `src/assets/fallback/` showing generic forest elements (flower, mushroom, bird, tree, butterfly). Used when API unavailable or rate-limited.

### Companion Text Integration
- **D-13:** Companion text module `src/companion/companion.ts` with `getGreeting(character, timeOfDay)`, `getLetterIntro(character, letter)`, `getForestComment(character)`. Each tries API first, falls back to static texts.
- **D-14:** Companion area shown on welcome/forest screens with greeting text. Companion does NOT appear during typing exercise in Phase 2 (Phase 3 adds "Entdecken" phase with companion letter introduction).

### Claude's Discretion
- Exact prompt templates for Gemini API calls (following SPEC.md section 9.2 as guide)
- Build script CLI output format and error handling
- Asset file naming conventions within companion directories
- Config loader error handling strategy
</decisions>

<canonical_refs>
## Canonical References

**Downstream agents MUST read these before planning or implementing.**

- `SPEC.md` — Full specification, THE authoritative source
- `SPEC.md` section 5.4 — Visual consistency architecture (Character Sheets, Style Reference)
- `SPEC.md` section 6.4 — API key handling (config.json structure)
- `SPEC.md` section 9 — Gemini Integration (API endpoints, prompt templates, models)
- `SPEC.md` section 9.2 — Prompt templates for all companion text types
- `SPEC.md` section 9.3 — Character Sheet generation prompts and visual descriptions
- `src/types.ts` — Existing TypeScript interfaces (CompanionAssets, ForestElement, etc.)
- `src/storage/db.ts` — IndexedDB wrapper with 5 stores (companionAssets, styleReference need methods)
- `src/companion/characters.ts` — Companion definitions (needs avatarUrl field)
- `src/ui/screens.ts` — Welcome screen rendering (emoji → img replacement)
- `public/config.json` — Gemini API key and model names
</canonical_refs>

<code_context>
## Existing Code Insights

### Reusable Assets
- `src/types.ts`: `CompanionAssets` interface (characterSheet: Blob, avatarImage: Blob, characterType, generatedAt), `ForestElement` interface, `StyleReference` interface already defined
- `src/storage/db.ts`: 5 IndexedDB stores created, `progress` and `settings` have CRUD methods, other 3 stores need method additions
- `src/companion/characters.ts`: 4 `CompanionDefinition` objects with name, type, emoji, personality — ready to extend with avatarUrl
- `public/config.json`: Already contains `geminiApiKey`, `geminiModel`, `imageModel`

### Established Patterns
- All modules use TypeScript strict mode
- Functions export individually (no default exports)
- IndexedDB operations are Promise-wrapped with typed results
- CSS uses BEM-style class names with `--` modifiers

### Integration Points
- Welcome screen `initWelcomeScreen()` in `screens.ts` — replace emoji cards with img cards
- `app.ts` `initApp()` — add greeting text display after detecting returning user
- `db.ts` — add `saveCompanionAssets()`, `getCompanionAssets()`, `saveStyleReference()`, `getStyleReference()`, `saveForestElement()`, `getForestElement()` methods
- `characters.ts` — add `avatarUrl` to each companion definition
</code_context>

<specifics>
## Specific Ideas

No specific requirements — open to standard approaches
</specifics>

<deferred>
## Deferred Ideas

None — analysis stayed within phase scope
</deferred>
