# Sagaphone — Spec

A web-based, procedural family-saga narrator with TTS. Sagaphone generates a
random family tree and narrates its story via text-to-speech in the browser.
It's meant as a "fall asleep" tool: open it on an iPad or phone, set a timer,
and it reads family sagas until the timer runs out.

**Language of narration:** English. **Tone:** fantasy-medieval.

## Architecture

- **Frontend:** SvelteKit — audio playback + UI only, no business logic.
- **Backend:** FastAPI, deployed on Zeus, reachable via a URL (e.g.
  `sagaphone.orbitstack.casa`).
- **Reverse proxy:** Caddy.
- **TTS:** Piper, runs server-side, audio streamed to the browser. Deliberately
  not Web Speech API — avoids iOS Audio Session issues, works in all browsers.
- **Narration:** Anthropic Haiku API, called server-side only (~$1.50/month at
  daily use). API key is never exposed to the client — no API keys in the
  frontend at all.

## Flow

1. User opens Sagaphone in the browser and sets a timer.
2. On start: a family tree up to generation 6 is pre-generated as JSON — pure
   random logic, no LLM involved, runs in milliseconds.
3. An active line (branch) is picked at random.
4. The LLM generates a paragraph for the active person's current life stage.
5. TTS reads the paragraph aloud; the next paragraph is fetched in the
   background while it plays.
6. When a person's story is fully told: move to the next person in the active
   line, or switch lines if the line has died out.
7. Repeat until the timer runs out.

## Features / Design Areas

- [Data Model](spec/data-model.md) — enums, `Person`, `Stage`, `EventEntry`, `FamilyTree`, `World`.
- [Event System](spec/event-system.md) — event categories, death probability, event tables, follow-bonus map.
- [Line Logic](spec/line-logic.md) — how the active family branch is chosen and switched.
- [Implementation Notes](spec/implementation-notes.md) — event weights/stage locks, living-family lookup, location/name/appearance generators.

## Open Questions (from planning, still unresolved)

- [ ] Tune `magic_factor` and death probabilities via playtesting.
- [ ] Fill event tables with more concrete fantasy events.
- [ ] Define appearance generation in more detail.
- [ ] Work out the LLM prompt structure per life stage.
- [ ] Test the audio-loop workaround on iOS.
- [ ] Decide name / seed mechanism for the first test person.
- [ ] Plan deployment on Zeus.

## Source

Planning originally done in Notion ("Sagaphone" page under "Dokumentation").
This repo is the implementation target; specs here are the source of truth
going forward — update them alongside the code, don't let Notion and the repo
drift apart.