stork/README.md

Stork

Private family baby-name boards: suggest names, vote, keep origin / meaning / pronunciation in English, Russian, and Hebrew, and optionally record how a name sounds.

Each board has a unique share link (/b/<uid>). Start a board with no password, add names, share the link. 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)

cp .env.example .env   # optional STORK_INVITE_TOKEN bootstraps a "Family" board
make install
make test
make run

Open http://127.0.0.1:8094 → Start new board → share /b/… with family. They open the link and enter a display name.

Features

• Renamable columns (First is fixed; + adds up to 4; ✕ removes extras)
• Votes / ranking per board
• Locale notes (en / ru / he) + voice recordings (re-record overwrites)
• Paper UI at / (classic layout at /v1)

API sketch

Method	Path	Notes
GET	/api/health	Liveness
POST	/api/boards	Start board {title} → {id, url}
GET	/api/boards/{id}	Public board title + url
GET	/api/resolve?invite=	Legacy invite → board url
POST	/api/session	{board_id, display_name} → cookies
GET	/api/columns	Columns for session board
POST/PATCH/DELETE	/api/columns…	Add / rename / remove (not first)
GET/POST	/api/names	List / add
PATCH	/api/names/{id}	Locale notes
POST	/api/names/{id}/vote	{value: 1|-1|0}
POST/GET/DELETE	/api/names/{id}/recording/{lang}	Voice
DELETE	/api/names/{id}	Admin header X-Stork-Admin

Scripts

# Seed Shai/Roze/Odet/Rivka onto a board
make seed STORK_BOARD_ID=b_…   # or STORK_INVITE=… for legacy

# Create an empty board and print share URL
.venv/bin/python scripts/create_board.py

Secrets

• Local: gitignored .env
• Prod: host /opt/stork/.env from deploy (never git)

CI gates

Gitea Actions (.gitea/workflows/ci.yml): ruff and pytest are hard gates (no || true). Gitleaks on PRs. Bandit is advisory.

Production shape

Docker on automationlab; public HTTPS via Caddy (stork.levkin.ca). See ansible docs/guides/stork-deploy.md.