# 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

```bash
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

```bash
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`:

```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](https://komo.do)'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.