Wordsmith — Puzzle Workshop

A small self-hosted web app that generates printable word search PDFs from themed word lists. Single Python process, no database, no build step.

Stack

Python 3.14+
FastAPI + Jinja2 (server-rendered HTML)
reportlab (PDF)
A small piece of vanilla JS for the live theme-editor preview

Local development

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --reload --port 8000

--reload restarts on .py changes; Jinja templates reload without a restart.

Docker

docker compose up --build

Maps host port 3801 → container 8000. The bind-mounts ./themes:/app/themes, so any theme JSON files in the repo's themes/ folder are picked up at boot and any UI-edited themes are written back to the same place.

Themes

Each theme is a flat JSON file under themes/<slug>.json:

{
  "name": "Mr Men Characters",
  "words": ["Mr Tickle", "Mr Happy", "Little Miss Sunshine"]
}

Words can include leading honorific tokens (Mr, Mrs, Miss, Dr, Captain, etc.) — they're stripped from the grid form but kept on the PDF word list in parentheses, e.g. TICKLE (Mr).

Deployment

The repo is intended to be deployed via Komodo's git-stack mode: point a stack at this repo, set the compose path to docker-compose.yml, and redeploy. Themes added via the deployed UI live in Komodo's per-stack checkout — they survive normal redeploys but a Komodo "Destroy" wipes them. For lasting changes, edit themes locally and git push.

Generated PDFs

Generated puzzles stream straight to the browser as a download (<slug>_<YYYY-MM-DD_HH-MM-SS>.pdf); the server keeps no copy on disk.