davideandClaude Opus 5.5
61efbb0e37
The two Mermaid diagrams under flowchart/ described the intended flow but had drifted from the code and carried no link back to it. docs/ now holds the specification instead: 15 Italian documents (flows, architecture, data model, API, security, audit log, operations, decisions and limits, bug history) with 472 numbered requirements, each pointing at the function that implements it and the test that covers it. docs/processo-di-modifica.md defines the ID convention and the spec -> code -> test change workflow, and CLAUDE.md now names docs/ as authoritative. Writing the spec from the code also corrected stale claims in CLAUDE.md (B-41's get_history check, BUGS.md still tracking B-71/B-72, Cache-Control scope, the error contract's bare-string exceptions) and in the operator guides (payouts do retry, only `drawing` fails to resume, rounds do not open without fee_address). The B-70 doc test now pins the prose in docs/scommesse-e-prelievi.md instead of the deleted diagram. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
69 lines
3.4 KiB
Markdown
69 lines
3.4 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
|
|
|
|
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](CLAUDE.md#commands).
|
|
|
|
```bash
|
|
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](docs/setup.md) and
|
|
[docs/running-the-server.md](docs/running-the-server.md) for the full
|
|
walkthrough (secrets, master key generation, production TLS with a real
|
|
domain).
|
|
|
|
## Documentation
|
|
|
|
- [CLAUDE.md](CLAUDE.md) — architecture, commands, domain decisions, known gaps (for anyone/anything working on the code)
|
|
- [docs/come-funziona.md](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](docs/processo-di-modifica.md) describes how a change goes from the spec to the code
|
|
- [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 with 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) 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
|
|
```
|
|
|
|
351 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").
|