Files

T

davideandClaude Opus 5 162ceed40f Describe the code the docs actually ship with (B-68)

CLAUDE.md and README still asserted a state the code had moved past:

- JWT "no revocation (B-34)" — token_version implements exactly that
  revocation, and the tv-claim behaviour (including why the deploy did not
  log everyone out) is worth stating instead of denying;
- /report-bug "a placeholder" — it shipped fully implemented and
  translated, with an admin triage section, a reporter-side status view and
  its own audit event; only /guida is still a stub, and /admin has six
  sections now, not five;
- three stale test counts (CLAUDE.md twice, README once);
- a code map missing app/auth/rate_limit.py, app/api/client_ip.py and
  app/api/routes/bug_reports.py;
- README linking flowchart.mmd (the diagrams live in flowchart/), the
  anchor CLAUDE.md#tech-stack-mvp (gone), and describing
  docs/running-the-server.md as "local venv vs. Docker" after B-44 made
  Docker the only supported way to run the server.

The rate-limiting bullet the audit also flagged already reads correctly.

tests/unit/test_docs_current.py pins all of it: the documented counts must
equal what the suite actually collects, the retired claims must stay
retired, the code map must name those modules, and every relative README
link and CLAUDE.md anchor must resolve. None of this is catchable by
reading the code, which is how it drifted in the first place.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

2026-08-04 14:33:32 +02:00

3.2 KiB

Raw Blame History

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)
flowchart/ — the source-of-truth flow diagrams the implementation follows node-by-node: platform-overview.mmd (the 5-phase flow) and round-lifecycle.mmd (the round/draw lifecycle)
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

345 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").