Scaffold backend (FastAPI/uv) and frontend (SvelteKit/bun)

Backend: FastAPI app with health check, AppError hierarchy, stderr
logging via LOG_LEVEL, ruff+pyright(strict) config, pytest passing.

Frontend: SvelteKit (TS) with prettier, eslint, vitest (unit +
component), adapter-node for self-hosted deployment on Zeus.

Co-Authored-By: Claude <noreply@anthropic.com>

.gitignore

@@ -1,6 +1,7 @@
 # Lock files
 uv.lock
 bun.lockb
+bun.lock
 
 # Secrets & live config (commit *.toml.example only)
 secrets.toml

README.md

@@ -8,13 +8,26 @@ See [SPEC.md](SPEC.md) for the full spec, architecture, and design areas.
 
 ## Status
 
-Spec-only. Implementation not started yet.
+Scaffolded, no features implemented yet. `backend/` and `frontend/` both run
+and have a passing test suite; actual simulation/narration/TTS logic is next.
 
-## Stack (planned)
+## Stack
 
-- Frontend: SvelteKit
+- Frontend: SvelteKit (`frontend/`) — `bun`
-- Backend: FastAPI (Python, `uv`)
+- Backend: FastAPI (`backend/`) — `uv`
 - TTS: Piper (server-side)
 - Narration: Anthropic Haiku API (server-side)
 - Reverse proxy: Caddy
 - Deployment target: Zeus, `sagaphone.orbitstack.casa`
+
+## Dev
+
+```bash
+# backend
+cd backend && uv sync && uv run uvicorn app.main:app --reload
+
+# frontend
+cd frontend && bun install && bun run dev
+```
+
+Each subproject's own README has more detail (lint/test/typecheck commands).

backend/.python-version

@@ -0,0 +1 @@
+3.12

backend/README.md

@@ -0,0 +1,17 @@
+# sagaphone-backend
+
+FastAPI backend for Sagaphone: generates the family tree, calls the Haiku API
+for narration, streams Piper TTS audio to the frontend.
+
+## Dev
+
+```bash
+uv sync
+uv run uvicorn app.main:app --reload
+uv run pytest
+uv run ruff check .
+uv run pyright
+```
+
+See `secrets.toml.example` for required config — copy to `secrets.toml`
+(git-ignored) and fill in real values.

backend/app/errors.py

@@ -0,0 +1,41 @@
+"""Base exception hierarchy for the Sagaphone backend.
+
+Errors propagate normally; only the API edge (see main.py's exception
+handler) catches them and translates them into an HTTP response.
+"""
+
+from __future__ import annotations
+
+
+class AppError(Exception):
+    """Base class for all application errors."""
+
+    status_code: int = 500
+
+    def __init__(self, message: str) -> None:
+        super().__init__(message)
+        self.message = message
+
+
+class NotFoundError(AppError):
+    """Requested resource does not exist."""
+
+    status_code = 404
+
+
+class ConfigError(AppError):
+    """Missing or invalid configuration (e.g. secrets.toml)."""
+
+    status_code = 500
+
+
+class NarrationError(AppError):
+    """The narration (Haiku) call failed or returned something unusable."""
+
+    status_code = 502
+
+
+class TTSError(AppError):
+    """The TTS (Piper) synthesis step failed."""
+
+    status_code = 502

backend/app/logging_config.py

@@ -0,0 +1,25 @@
+"""Logging setup for the backend.
+
+Follows the project's output contract: all log output goes to stderr,
+level controlled via the LOG_LEVEL env var (default INFO). This is server
+logging, not the request/response payload — that stays in FastAPI's
+responses.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import sys
+
+
+def configure_logging() -> None:
+    level_name = os.environ.get("LOG_LEVEL", "INFO").upper()
+    level = getattr(logging, level_name, logging.INFO)
+
+    handler = logging.StreamHandler(sys.stderr)
+    handler.setFormatter(logging.Formatter("%(asctime)s %(levelname)-5s %(name)s: %(message)s"))
+
+    root = logging.getLogger()
+    root.setLevel(level)
+    root.handlers = [handler]

backend/app/main.py

@@ -0,0 +1,33 @@
+"""Sagaphone FastAPI entrypoint.
+
+Routes are added as features land (see ../SPEC.md and ../spec/*.md).
+This currently only wires up app creation, logging, and a health check
+so the scaffold is runnable end to end.
+"""
+
+from __future__ import annotations
+
+import logging
+
+from fastapi import FastAPI, Request
+from fastapi.responses import JSONResponse
+
+from app.errors import AppError
+from app.logging_config import configure_logging
+
+configure_logging()
+logger = logging.getLogger(__name__)
+
+app = FastAPI(title="Sagaphone", version="0.1.0")
+
+
+@app.exception_handler(AppError)
+async def app_error_handler(_request: Request, exc: AppError) -> JSONResponse:
+    """Edge-catch: translate AppError subclasses into clean HTTP responses."""
+    logger.error("request failed: %s", exc.message)
+    return JSONResponse(status_code=exc.status_code, content={"error": exc.message})
+
+
+@app.get("/health")
+async def health() -> dict[str, str]:
+    return {"status": "ok"}

backend/pyproject.toml

@@ -0,0 +1,50 @@
+[project]
+name = "sagaphone-backend"
+version = "0.1.0"
+description = "Sagaphone backend — family-tree simulation, narration, and TTS streaming API."
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "fastapi>=0.115",
+    "uvicorn[standard]>=0.32",
+    "anthropic>=0.40",
+]
+
+[dependency-groups]
+dev = [
+    "ruff>=0.8",
+    "pyright>=1.1.390",
+    "pytest>=8.3",
+    "pytest-asyncio>=0.24",
+    "httpx>=0.27",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+
+[tool.pyright]
+include = ["app", "tests"]
+typeCheckingMode = "strict"
+pythonVersion = "3.12"
+
+[[tool.pyright.executionEnvironments]]
+root = "tests"
+reportUnknownMemberType = false
+reportUnknownVariableType = false
+reportUnknownParameterType = false
+reportMissingParameterType = false
+reportMissingTypeStubs = false
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["app"]

backend/secrets.toml.example

@@ -0,0 +1,9 @@
+# Copy to secrets.toml and fill in real values. secrets.toml is git-ignored.
+
+[anthropic]
+api_key = "sk-ant-..."  # Haiku API key, server-side only, never sent to the client
+
+[server]
+host = "0.0.0.0"
+port = 8000
+log_level = "INFO"  # DEBUG | INFO | WARN | ERROR

backend/tests/test_health.py

@@ -0,0 +1,11 @@
+from fastapi.testclient import TestClient
+
+from app.main import app
+
+client = TestClient(app)
+
+
+def test_health() -> None:
+    response = client.get("/health")
+    assert response.status_code == 200
+    assert response.json() == {"status": "ok"}

frontend/.gitignore

@@ -0,0 +1,23 @@
+node_modules
+
+# Output
+.output
+.vercel
+.netlify
+.wrangler
+/.svelte-kit
+/build
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Env
+.env
+.env.*
+!.env.example
+!.env.test
+
+# Vite
+vite.config.js.timestamp-*
+vite.config.ts.timestamp-*

frontend/.npmrc

@@ -0,0 +1 @@
+engine-strict=true

frontend/.prettierignore

@@ -0,0 +1,9 @@
+# Package Managers
+package-lock.json
+pnpm-lock.yaml
+yarn.lock
+bun.lock
+bun.lockb
+
+# Miscellaneous
+/static/

frontend/.vscode/extensions.json

@@ -0,0 +1,3 @@
+{
+	"recommendations": ["svelte.svelte-vscode", "esbenp.prettier-vscode", "dbaeumer.vscode-eslint"]
+}

frontend/README.md

@@ -0,0 +1,42 @@
+# sv
+
+Everything you need to build a Svelte project, powered by [`sv`](https://github.com/sveltejs/cli).
+
+## Creating a project
+
+If you're seeing this, you've probably already done this step. Congrats!
+
+```sh
+# create a new project
+npx sv create my-app
+```
+
+To recreate this project with the same configuration:
+
+```sh
+# recreate this project
+npx sv@0.16.3 create --template minimal --types ts --no-install frontend
+```
+
+## Developing
+
+Once you've created a project and installed dependencies with `npm install` (or `pnpm install` or `yarn`), start a development server:
+
+```sh
+npm run dev
+
+# or start the server and open the app in a new browser tab
+npm run dev -- --open
+```
+
+## Building
+
+To create a production version of your app:
+
+```sh
+npm run build
+```
+
+You can preview the production build with `npm run preview`.
+
+> To deploy your app, you may need to install an [adapter](https://svelte.dev/docs/kit/adapters) for your target environment.

frontend/eslint.config.js

@@ -0,0 +1,41 @@
+import prettier from 'eslint-config-prettier';
+import path from 'node:path';
+import js from '@eslint/js';
+import svelte from 'eslint-plugin-svelte';
+import { defineConfig, includeIgnoreFile } from 'eslint/config';
+import globals from 'globals';
+import ts from 'typescript-eslint';
+
+const gitignorePath = path.resolve(import.meta.dirname, '.gitignore');
+
+export default defineConfig(
+	includeIgnoreFile(gitignorePath),
+	js.configs.recommended,
+	ts.configs.recommended,
+	svelte.configs.recommended,
+	prettier,
+	svelte.configs.prettier,
+	{
+		languageOptions: { globals: { ...globals.browser, ...globals.node } },
+		rules: {
+			// typescript-eslint strongly recommend that you do not use the no-undef lint rule on TypeScript projects.
+			// see: https://typescript-eslint.io/troubleshooting/faqs/eslint/#i-get-errors-from-the-no-undef-rule-about-global-variables-not-being-defined-even-though-there-are-no-typescript-errors
+			'no-undef': 'off'
+		}
+	},
+	{
+		files: ['**/*.svelte', '**/*.svelte.ts', '**/*.svelte.js'],
+		languageOptions: {
+			parserOptions: {
+				projectService: true,
+				extraFileExtensions: ['.svelte'],
+				parser: ts.parser
+			}
+		}
+	},
+	{
+		// Override or add rule settings here, such as:
+		// 'svelte/button-has-type': 'error'
+		rules: {}
+	}
+);

frontend/package.json

@@ -0,0 +1,40 @@
+{
+	"name": "frontend",
+	"private": true,
+	"version": "0.0.1",
+	"type": "module",
+	"scripts": {
+		"dev": "vite dev",
+		"build": "vite build",
+		"preview": "vite preview",
+		"prepare": "svelte-kit sync || echo ''",
+		"check": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json",
+		"check:watch": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json --watch",
+		"lint": "prettier --check . && eslint .",
+		"format": "prettier --write .",
+		"test:unit": "vitest",
+		"test": "bun run test:unit -- --run"
+	},
+	"devDependencies": {
+		"@eslint/js": "^10.0.1",
+		"@sveltejs/adapter-node": "^5.5.4",
+		"@sveltejs/kit": "^2.63.0",
+		"@sveltejs/vite-plugin-svelte": "^7.1.2",
+		"@types/node": "^22",
+		"@vitest/browser-playwright": "^4.1.8",
+		"eslint": "^10.4.1",
+		"eslint-config-prettier": "^10.1.8",
+		"eslint-plugin-svelte": "^3.19.0",
+		"globals": "^17.6.0",
+		"playwright": "^1.60.0",
+		"prettier": "^3.8.3",
+		"prettier-plugin-svelte": "^4.1.0",
+		"svelte": "^5.56.1",
+		"svelte-check": "^4.6.0",
+		"typescript": "^6.0.3",
+		"typescript-eslint": "^8.60.1",
+		"vite": "^8.0.16",
+		"vitest": "^4.1.8",
+		"vitest-browser-svelte": "^2.1.1"
+	}
+}

frontend/prettier.config.js

@@ -0,0 +1,11 @@
+/** @type {import("prettier").Config} */
+const config = {
+	useTabs: true,
+	singleQuote: true,
+	trailingComma: 'none',
+	printWidth: 100,
+	plugins: ['prettier-plugin-svelte'],
+	overrides: [{ files: '*.svelte', options: { parser: 'svelte' } }]
+};
+
+export default config;

frontend/src/app.d.ts

@@ -0,0 +1,13 @@
+// See https://svelte.dev/docs/kit/types#app.d.ts
+// for information about these interfaces
+declare global {
+	namespace App {
+		// interface Error {}
+		// interface Locals {}
+		// interface PageData {}
+		// interface PageState {}
+		// interface Platform {}
+	}
+}
+
+export {};

frontend/src/app.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+	<head>
+		<meta charset="utf-8" />
+		<meta name="viewport" content="width=device-width, initial-scale=1" />
+		<meta name="text-scale" content="scale" />
+		%sveltekit.head%
+	</head>
+	<body data-sveltekit-preload-data="hover">
+		<div style="display: contents">%sveltekit.body%</div>
+	</body>
+</html>

frontend/src/lib/assets/favicon.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="107" height="128" viewBox="0 0 107 128"><title>svelte-logo</title><path d="M94.157 22.819c-10.4-14.885-30.94-19.297-45.792-9.835L22.282 29.608A29.92 29.92 0 0 0 8.764 49.65a31.5 31.5 0 0 0 3.108 20.231 30 30 0 0 0-4.477 11.183 31.9 31.9 0 0 0 5.448 24.116c10.402 14.887 30.942 19.297 45.791 9.835l26.083-16.624A29.92 29.92 0 0 0 98.235 78.35a31.53 31.53 0 0 0-3.105-20.232 30 30 0 0 0 4.474-11.182 31.88 31.88 0 0 0-5.447-24.116" style="fill:#ff3e00"/><path d="M45.817 106.582a20.72 20.72 0 0 1-22.237-8.243 19.17 19.17 0 0 1-3.277-14.503 18 18 0 0 1 .624-2.435l.49-1.498 1.337.981a33.6 33.6 0 0 0 10.203 5.098l.97.294-.09.968a5.85 5.85 0 0 0 1.052 3.878 6.24 6.24 0 0 0 6.695 2.485 5.8 5.8 0 0 0 1.603-.704L69.27 76.28a5.43 5.43 0 0 0 2.45-3.631 5.8 5.8 0 0 0-.987-4.371 6.24 6.24 0 0 0-6.698-2.487 5.7 5.7 0 0 0-1.6.704l-9.953 6.345a19 19 0 0 1-5.296 2.326 20.72 20.72 0 0 1-22.237-8.243 19.17 19.17 0 0 1-3.277-14.502 17.99 17.99 0 0 1 8.13-12.052l26.081-16.623a19 19 0 0 1 5.3-2.329 20.72 20.72 0 0 1 22.237 8.243 19.17 19.17 0 0 1 3.277 14.503 18 18 0 0 1-.624 2.435l-.49 1.498-1.337-.98a33.6 33.6 0 0 0-10.203-5.1l-.97-.294.09-.968a5.86 5.86 0 0 0-1.052-3.878 6.24 6.24 0 0 0-6.696-2.485 5.8 5.8 0 0 0-1.602.704L37.73 51.72a5.42 5.42 0 0 0-2.449 3.63 5.79 5.79 0 0 0 .986 4.372 6.24 6.24 0 0 0 6.698 2.486 5.8 5.8 0 0 0 1.602-.704l9.952-6.342a19 19 0 0 1 5.295-2.328 20.72 20.72 0 0 1 22.237 8.242 19.17 19.17 0 0 1 3.277 14.503 18 18 0 0 1-8.13 12.053l-26.081 16.622a19 19 0 0 1-5.3 2.328" style="fill:#fff"/></svg>

frontend/src/lib/index.ts

@@ -0,0 +1 @@
+// place files you want to import through the `$lib` alias in this folder.

frontend/src/lib/vitest-examples/Welcome.svelte

@@ -0,0 +1,8 @@
+<script>
+	import { greet } from './greet';
+
+	let { host = 'SvelteKit', guest = 'Vitest' } = $props();
+</script>
+
+<h1>{greet(host)}</h1>
+<p>{greet(guest)}</p>

frontend/src/lib/vitest-examples/Welcome.svelte.spec.ts

@@ -0,0 +1,15 @@
+import { page } from 'vitest/browser';
+import { describe, expect, it } from 'vitest';
+import { render } from 'vitest-browser-svelte';
+import Welcome from './Welcome.svelte';
+
+describe('Welcome.svelte', () => {
+	it('renders greetings for host and guest', async () => {
+		render(Welcome, { host: 'SvelteKit', guest: 'Vitest' });
+
+		await expect
+			.element(page.getByRole('heading', { level: 1 }))
+			.toHaveTextContent('Hello, SvelteKit!');
+		await expect.element(page.getByText('Hello, Vitest!')).toBeInTheDocument();
+	});
+});

frontend/src/lib/vitest-examples/greet.spec.ts

@@ -0,0 +1,8 @@
+import { describe, it, expect } from 'vitest';
+import { greet } from './greet';
+
+describe('greet', () => {
+	it('returns a greeting', () => {
+		expect(greet('Svelte')).toBe('Hello, Svelte!');
+	});
+});

frontend/src/lib/vitest-examples/greet.ts

@@ -0,0 +1,3 @@
+export function greet(name: string): string {
+	return 'Hello, ' + name + '!';
+}

frontend/src/routes/+layout.svelte

@@ -0,0 +1,11 @@
+<script lang="ts">
+	import favicon from '$lib/assets/favicon.svg';
+
+	let { children } = $props();
+</script>
+
+<svelte:head>
+	<link rel="icon" href={favicon} />
+</svelte:head>
+
+{@render children()}

frontend/src/routes/+page.svelte

@@ -0,0 +1,2 @@
+<h1>Welcome to SvelteKit</h1>
+<p>Visit <a href="https://svelte.dev/docs/kit">svelte.dev/docs/kit</a> to read the documentation</p>

frontend/static/robots.txt

@@ -0,0 +1,3 @@
+# allow crawling everything by default
+User-agent: *
+Disallow:

frontend/tsconfig.json

@@ -0,0 +1,20 @@
+{
+	"extends": "./.svelte-kit/tsconfig.json",
+	"compilerOptions": {
+		"rewriteRelativeImportExtensions": true,
+		"allowJs": true,
+		"checkJs": true,
+		"esModuleInterop": true,
+		"forceConsistentCasingInFileNames": true,
+		"resolveJsonModule": true,
+		"skipLibCheck": true,
+		"sourceMap": true,
+		"strict": true,
+		"moduleResolution": "bundler"
+	}
+	// Path aliases are handled by https://svelte.dev/docs/kit/configuration#alias
+	// except $lib which is handled by https://svelte.dev/docs/kit/configuration#files
+	//
+	// To make changes to top-level options such as include and exclude, we recommend extending
+	// the generated config; see https://svelte.dev/docs/kit/configuration#typescript
+}

frontend/vite.config.ts

@@ -0,0 +1,45 @@
+import { defineConfig } from 'vitest/config';
+import { playwright } from '@vitest/browser-playwright';
+import adapter from '@sveltejs/adapter-node';
+import { sveltekit } from '@sveltejs/kit/vite';
+
+export default defineConfig({
+	plugins: [
+		sveltekit({
+			compilerOptions: {
+				// Force runes mode for the project, except for libraries. Can be removed in svelte 6.
+				runes: ({ filename }) =>
+					filename.split(/[/\\]/).includes('node_modules') ? undefined : true
+			},
+			adapter: adapter()
+		})
+	],
+	test: {
+		expect: { requireAssertions: true },
+		projects: [
+			{
+				extends: './vite.config.ts',
+				test: {
+					name: 'client',
+					browser: {
+						enabled: true,
+						provider: playwright(),
+						instances: [{ browser: 'chromium', headless: true }]
+					},
+					include: ['src/**/*.svelte.{test,spec}.{js,ts}'],
+					exclude: ['src/lib/server/**']
+				}
+			},
+
+			{
+				extends: './vite.config.ts',
+				test: {
+					name: 'server',
+					environment: 'node',
+					include: ['src/**/*.{test,spec}.{js,ts}'],
+					exclude: ['src/**/*.svelte.{test,spec}.{js,ts}']
+				}
+			}
+		]
+	}
+});