Add Stork family name board MVP with invite auth and votes.

Includes multilingual etymology fields, seed data for starter names, and CI-ready Python project layout.
2026-08-06 16:43:06 -04:00
commit b88791a0b7
25 changed files with 1601 additions and 0 deletions
@@ -0,0 +1,42 @@
+# Stork
+
+Private family board for baby **first** and **middle** name ideas: suggest
+names, vote, and keep origin / meaning / pronunciation in English, Russian,
+and Hebrew.
+
+Homelab deploy lives in the ansible repo (`make deploy-stork`). This repo is
+the app only — no LAN IPs or production secrets here.
+
+## Quick start (local)
+
+```bash
+cp .env.example .env   # set STORK_INVITE_TOKEN (and optional STORK_ADMIN_TOKEN)
+make install
+make test
+make run
+```
+
+Open http://127.0.0.1:8094 — enter the invite code and your display name.
+Share `http://127.0.0.1:8094/?invite=YOUR_TOKEN` with family for one-tap entry.
+
+## API sketch
+
+| Method | Path | Notes |
+|--------|------|-------|
+| GET | `/api/health` | Liveness |
+| POST | `/api/session` | `{invite, display_name}` → cookies |
+| GET | `/api/names?kind=first\|middle` | Ranked list |
+| POST | `/api/names` | Add name + optional locales |
+| PATCH | `/api/names/{id}` | Update locale notes |
+| POST | `/api/names/{id}/vote` | `{value: 1\|-1\|0}` |
+| DELETE | `/api/names/{id}` | Admin header `X-Stork-Admin` |
+
+## Secrets
+
+- Local: gitignored `.env`
+- Prod: Infisical `/apps/stork` (or host `.env` written by deploy) — never git
+
+## Production shape
+
+Same host pattern as Compare: Docker on automationlab LXC **225**, public
+HTTPS via Caddy (`stork.levkin.ca`). See ansible `docs/guides/stork-deploy.md`.