PLM Lottery

A periodic-round lottery system built on PLM, a Bitcoin-like coin (mainnet). Each user gets a dedicated server-derived P2WPKH address; they deposit PLM to that address, place a fixed-cost bet to enter the current round, and when the round closes a winner is drawn who receives 70% of the prize pool (the remaining 30% goes to fees).

This is a custodial system: private keys are generated and held server-side, encrypted at rest. See CLAUDE.md for the full architecture, domain decisions, and known gaps before treating this as production-ready.

Quick start

The server always runs via Docker (app + Caddy reverse proxy with automatic TLS) — in dev and production alike, with only SITE_ADDRESS differing between the two. There's no supported way to run uvicorn directly; the venv is only for local tooling (tests, Alembic migrations, the one-time key scripts) — see CLAUDE.md.

cp .env.example .env               # then fill in the generated secrets, see docs/setup.md
mkdir -p data/db data/keys data/logs
docker compose run --rm app python scripts/generate_master_key.py
docker compose up -d --build

Open https://localhost/ for the test UI, https://localhost/admin for the admin dashboard (a self-signed-certificate warning on first visit is expected in dev — accept it, or use curl -k). The interactive API docs at /docs are disabled by default (they'd otherwise expose the whole API surface, admin endpoints included) — set ENABLE_API_DOCS=true in .env to enable them.

See docs/setup.md and docs/running-the-server.md for the full walkthrough (secrets, master key generation, production TLS with a real domain).

Documentation

• CLAUDE.md — architecture, commands, domain decisions, known gaps (for anyone/anything working on the code)
• docs/README.md — index of all documentation (docs-first, single source of truth, one ADR per decision: docs/adr/)
• docs/come-funziona.md — the specification (Italian): how the platform works, with diagrams and traceable requirement IDs; it indexes every per-topic document (flows, architecture, data model, API, security, audit log, operations, decisions and limits, bug history). docs/processo-di-modifica.md describes how a change goes from the spec to the code
• docs/setup.md — one-time setup (secrets, master key, migrations)
• docs/running-the-server.md — how to launch it with Docker+Caddy (dev vs. production TLS)
• docs/guida-utente.md — end-user guide to the test UI (Italian)
• docs/guida-admin.md — admin dashboard guide (Italian)

Tech stack

Python (FastAPI, SQLAlchemy async + Alembic, Argon2 + JWT auth), Electrum protocol for PLM network access (no full node), Docker + Caddy for deployment. See CLAUDE.md for the complete list and the reasoning behind each choice.

Testing

python -m pytest                    # all tests
python -m pytest tests/unit/test_hd.py   # one file

738 unit tests cover HD derivation, PSBT building, the Electrum client, bets, deposits, withdrawals, the round/draw engine, RBF fee-bumping, admin config, the pending-inclusive balance calculation, and the SSE push channel. No automated integration tests against a live Electrum connection — mainnet verification so far has been manual (see CLAUDE.md's "Project status").