# Phase 1: Grundgerüst + Tippmechanik - Context

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

<domain>
## Phase Boundary

Eine spielbare Tipp-Übung im Browser, die ohne API funktioniert. Umfasst: Vite-Projekt-Setup, Projektstruktur, TypeScript-Interfaces, IndexedDB-Wrapper, Screen-Management, Willkommens-Screen mit Begleitfigur/Layout-Auswahl, QWERTZ-Bildschirmtastatur mit Fingerfarben, Übungsphase "Üben" (Buchstaben einzeln tippen), adaptives Tempo, Stufen 1–6 Daten, Stufenkarte, CSS-Palette/Typografie. Kein API-Zugriff, keine Bildgenerierung, keine Begleitfigur-Dialoge.
</domain>

<decisions>
## Implementation Decisions

### Screen Management Architecture
- **D-01:** All 5 screens (welcome, forest, lesson, reward, parent) exist as DOM containers in index.html, toggled via CSS classes with fade transitions. No dynamic DOM creation/destruction. Each screen is a `<section>` with a shared `.screen` class; only `.screen--active` is visible.

### IndexedDB Schema
- **D-02:** Create the full IndexedDB schema with all 5 stores (progress, companionAssets, styleReference, forestElements, settings) in Phase 1. Only `progress` and `settings` get full read/write methods; other stores are structurally defined but unused until Phase 2+. This avoids painful version migrations later.

### Typing Exercise Scope
- **D-03:** Phase 1 implements only the "Üben" (practice) phase — single letters appearing one at a time, typed by the child. "Entdecken" (TYPE-05) and "Wörter bauen" (TYPE-06) are Phase 3 scope. The lesson screen shows only the practice flow.
- **D-04:** A lesson consists of 8–12 random letters from the current level's key set. After all letters are correctly typed, the lesson is complete. No timer visible to the child.

### Companion Placeholders
- **D-05:** Welcome screen uses emoji placeholders (🧚 🦄 🦊 🦉) with character names for companion selection. No companion figure appears during typing exercise. Real generated avatars replace these in Phase 2 (ASST-03).

### Level Progression
- **D-06:** Levels 1–6 defined as static data with their key sets per the spec's progression table. A level counts as completed after one full playthrough (not perfection). Next level unlocks immediately.
- **D-07:** After completing a lesson, the app returns to the forest overview (Stufenkarte). No reward screen content in Phase 1 — the reward screen exists structurally but is skipped or shows a simple "Gut gemacht!" placeholder until Phase 3 adds Gemini-generated rewards.

### Adaptive Tempo
- **D-08:** Start interval 3s. After 2 correct in sequence: -200ms (min 1.5s). After 1 error: +500ms (max 4s). Reset to 3s at start of each new lesson.

### Claude's Discretion
- Screen transition timing and easing (CSS fade duration, easing function)
- Internal file/module organization within the spec's directory structure
- Exact DOM structure of keyboard component (divs vs buttons, row grouping)
- Test coverage scope — focus on typing logic and level progression, not DOM rendering
</decisions>

<canonical_refs>
## Canonical References

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

- `SPEC.md` — Full specification (sections 0–16), THE authoritative source for all design decisions
- `SPEC.md` section 4.1 — Level progression table (keys per level, finger assignments)
- `SPEC.md` section 6.2 — Tech stack decisions (all final)
- `SPEC.md` section 6.3 — IndexedDB store definitions
- `SPEC.md` section 7.2 — CSS color palette and typography
- `SPEC.md` section 8 — Keyboard layout, finger mapping, DE/CH differences
- `SPEC.md` section 13 — Project structure (directories + files)
- `.planning/REQUIREMENTS.md` — Phase 1 requirements: FNDN-01–05, ONBD-01–04, KYBD-01–05, TYPE-01–04, LEVL-01–03, FRST-04–05, PLSH-06
- `public/config.json` — Gemini API key and model names (not used in Phase 1 but structure exists)
</canonical_refs>

<code_context>
## Existing Code Insights

### Reusable Assets
No existing code — greenfield project. The only assets are:
- `public/config.json` with Gemini API key and model names
- `public/config.expample.json` as template

### Established Patterns
None yet — Phase 1 establishes all patterns. The spec mandates:
- Vanilla TypeScript, no framework
- Single `main.css` with CSS Custom Properties
- Biome for lint/format, Vitest for tests
- Vite 6.x with vanilla-ts template

### Integration Points
- `public/config.json` — Phase 2 will read this for API access; Phase 1 should not depend on it
- IndexedDB stores — Phase 2+ will use companionAssets, styleReference, forestElements stores created here
- Screen management — Phase 3 will add dynamic content to forest and reward screens
- Keyboard component — Phase 3 "Entdecken" phase will highlight keys for new letter introduction
</code_context>

<specifics>
## Specific Ideas

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

<deferred>
## Deferred Ideas

None — analysis stayed within phase scope
</deferred>