From b52a8023de675296d6079c92d1ea220204fa6667 Mon Sep 17 00:00:00 2001
From: Davide Grilli <davide.grilli@outlook.com>
Date: Tue, 21 Jul 2026 15:38:42 +0200
Subject: [PATCH] Add README.md
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Project overview, quick start (local venv and Docker+Caddy), and a
documentation index pointing to CLAUDE.md, flowchart.mmd and docs/ —
none of that existed as an entry point before this.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 README.md | 69 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 69 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..85d2547
--- /dev/null
+++ b/README.md
@@ -0,0 +1,69 @@
+# 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
+```
+
+54 unit tests cover HD derivation, PSBT building, the Electrum client, bets,
+deposits, withdrawals, the round/draw engine, RBF fee-bumping, and admin
+config. No automated integration tests against a live Electrum connection —
+mainnet verification so far has been manual (see CLAUDE.md's "Project
+status").