davideandClaude Sonnet 5
aae0961c94
CLAUDE.md: bumped the stale test count (54 -> 76), added "Balance display" and "Real-time updates (SSE)" sections, and rewrote the DRAW section's frontend-reveal paragraph to describe the actual current behavior (dual status/result boxes gated by user_played, closes_at-anchored reveal delay, localStorage persistence, the last-round-result backstop) instead of the older single-box design. Refined the "no history endpoints" known gap now that GET /users/me/last-round-result exists (still not general history). README.md: same test count fix, expanded coverage list. docs/: fixed a pre-existing broken link in setup.md (admin-guide.md -> guida-admin.md), added a note in running-the-server.md that editing the bind-mounted Caddyfile needs an explicit `docker compose restart caddy` (discovered while adding the SSE Caddy config in a prior change), and rewrote guida-utente.md's draw/reveal section plus the balance/withdrawal sections to match what the UI actually does now. guida-admin.md was reviewed but needed no changes. app/static/style.css: dropped `.toast.info`, dead since the toast-based loss notification it styled was replaced by the persistent result box. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
70 lines
2.8 KiB
Markdown
70 lines
2.8 KiB
Markdown
# 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](CLAUDE.md) for the full
|
|
architecture, domain decisions, and known gaps before treating this as
|
|
production-ready.
|
|
|
|
## Quick start
|
|
|
|
```bash
|
|
cp .env.example .env # then fill in the generated secrets, see docs/setup.md
|
|
python3 -m venv .venv && source .venv/bin/activate
|
|
pip install -e ".[dev]"
|
|
PYTHONPATH=. python scripts/generate_master_key.py
|
|
alembic upgrade head
|
|
uvicorn app.main:app --reload --port 8123
|
|
```
|
|
|
|
Open `http://127.0.0.1:8123/` for the test UI, `http://127.0.0.1:8123/admin`
|
|
for the admin dashboard, `http://127.0.0.1:8123/docs` for the interactive API
|
|
docs.
|
|
|
|
Or run the whole stack (app + Caddy reverse proxy with automatic TLS) via
|
|
Docker:
|
|
|
|
```bash
|
|
mkdir -p data/db data/keys data/logs
|
|
docker compose run --rm app python scripts/generate_master_key.py
|
|
docker compose up -d --build
|
|
```
|
|
|
|
See [docs/setup.md](docs/setup.md) and
|
|
[docs/running-the-server.md](docs/running-the-server.md) for the full
|
|
walkthrough (both workflows, dev vs. production TLS).
|
|
|
|
## Documentation
|
|
|
|
- [CLAUDE.md](CLAUDE.md) — architecture, commands, domain decisions, known gaps (for anyone/anything working on the code)
|
|
- [flowchart.mmd](flowchart.mmd) — the source-of-truth flow diagram the implementation follows node-by-node
|
|
- [docs/setup.md](docs/setup.md) — one-time setup (secrets, master key, migrations)
|
|
- [docs/running-the-server.md](docs/running-the-server.md) — how to launch it (local venv vs. Docker+Caddy, dev vs. production TLS)
|
|
- [docs/guida-utente.md](docs/guida-utente.md) — end-user guide to the test UI (Italian)
|
|
- [docs/guida-admin.md](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](CLAUDE.md#tech-stack-mvp) for the complete list
|
|
and the reasoning behind each choice.
|
|
|
|
## Testing
|
|
|
|
```bash
|
|
python -m pytest # all tests
|
|
python -m pytest tests/unit/test_hd.py # one file
|
|
```
|
|
|
|
76 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").
|