61 lines
1.7 KiB
Markdown
61 lines
1.7 KiB
Markdown
# 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.
|