plm-lottery/docs/architettura.md

# Architettura

Come è fatto il software dall'interno: quali processi girano, come è
organizzato il codice, cosa succede all'avvio, quali attività lavorano in
background, dove sta la configurazione, come le pagine web restano
aggiornate e come è strutturata la suite di test.

Questo documento non descrive i flussi di dominio (scommesse, round,
depositi…): per quelli rimanda ai documenti che li possiedono, elencati in
[come-funziona.md](come-funziona.md). Le tabelle del database sono in
[modello-dati.md](modello-dati.md), gli endpoint in [api.md](api.md), le
difese di sicurezza in [sicurezza.md](sicurezza.md).

## Panoramica del deployment

```mermaid
flowchart LR
    B["Browser<br/>(/, /admin, /report-bug)"] -- "HTTPS 443<br/>(80 → redirect)" --> C["Container caddy<br/>reverse proxy + TLS"]
    C -- "HTTP app:8123<br/>(rete interna compose)" --> A["Container app<br/>1 processo uvicorn<br/>FastAPI + 6 task asyncio"]
    A -- "aiosqlite" --> D[("./data/db/plm_lottery.db<br/>SQLite, WAL")]
    A -- "legge" --> K["./data/keys/master.xprv.enc"]
    A -- "scrive" --> L["./data/logs/app.log"]
    A -- "Electrum (TCP/SSL)<br/>una connessione attiva" --> E["Server Electrum PLM<br/>primario + riserve"]
```

- **[ARC-01]** Il server gira sempre in Docker, con lo stesso
  `docker-compose.yml` in sviluppo e in produzione: due container, `app`
  (questo codice) e `caddy` (reverse proxy con TLS automatico). Cambia solo
  `SITE_ADDRESS`: non impostato vale `localhost` (certificato autofirmato
  dalla CA interna di Caddy), impostato a un dominio produce un certificato
  Let's Encrypt. Non esiste un modo supportato di lanciare `uvicorn` fuori da
  Docker.
  *Codice:* `docker-compose.yml` · `Caddyfile` ·
  *Test:* `tests/unit/test_docs_no_bare_uvicorn.py`
- **[ARC-02]** Il container `app` esegue **un solo processo** uvicorn (nessun
  `--workers`), in ascolto su `0.0.0.0:8123`. Tutto lo stato in memoria
  descritto in [Assunzioni di processo singolo](#assunzioni-di-processo-singolo)
  dipende da questo.
  *Codice:* `Dockerfile` (`CMD`)
- **[ARC-03]** All'avvio il container `app`, nell'ordine: rifiuta di partire
  se il file indicato da `MASTER_KEY_PATH` non esiste (stampando il comando
  per generarlo), poi esegue `alembic upgrade head`, poi avvia uvicorn con
  `exec`. Le migrazioni non si lanciano mai a mano.
  *Codice:* `Dockerfile` (`CMD`) · `migrations/env.py`
- **[ARC-04]** `app` è solo `expose`d sulla rete interna di compose (porta
  8123), mai pubblicato sull'host: l'unico ingresso è Caddy, che pubblica 80 e
  443. Su questo si basa la lettura dell'IP del client (vedi
  [sicurezza.md](sicurezza.md)). Caddy non comprime `/rounds/stream`, perché
  la compressione accumulerebbe gli eventi SSE invece di consegnarli subito.
  *Codice:* `docker-compose.yml` · `Caddyfile` ·
  *Test:* `tests/unit/test_caddyfile_security_headers.py`
- **[ARC-05]** I dati persistenti stanno in `./data/` sull'host, montata nel
  container: `./data/db` → `/app/db_data`, `./data/keys` → `/app/key_data`,
  `./data/logs` → `/app/logs`. Il compose sovrascrive `DATABASE_URL` e
  `MASTER_KEY_PATH` perché puntino a quei percorsi; tutte le altre variabili
  arrivano da `.env` (`env_file`). Entrambi i container hanno
  `restart: unless-stopped`.
  *Codice:* `docker-compose.yml`

### Database

- **[ARC-06]** Il database è SQLite, usato tramite SQLAlchemy 2 in modalità
  asincrona (`create_async_engine` su `aiosqlite`). Una sola `engine` e una
  sola fabbrica di sessioni (`AsyncSessionLocal`, con
  `expire_on_commit=False`) servono sia le richieste HTTP (dipendenza
  `get_session`) sia le attività in background, che aprono ciascuna le
  proprie sessioni.
  *Codice:* `app/db/base.py` · `app/db/session.py:get_session`
- **[ARC-07]** A ogni nuova connessione SQLite vengono impostati
  `journal_mode=WAL`, `synchronous=NORMAL` e `busy_timeout=5000` ms: in WAL
  lettori e scrittori non si bloccano a vicenda, e uno scrittore che trova il
  database occupato aspetta fino a 5 secondi invece di fallire subito. Con un
  dialetto diverso da SQLite le pragma non vengono applicate.
  *Codice:* `app/db/base.py:_register_sqlite_pragmas` ·
  *Test:* `tests/unit/test_db_base.py`
- **[ARC-08]** Lo schema è definito in `app/db/models.py` ed evolve solo
  tramite migrazioni Alembic in `migrations/versions/` (generate con
  `alembic revision --autogenerate`); `migrations/env.py` prende l'URL del
  database da `settings.database_url`. I campi delle tabelle sono descritti
  in [modello-dati.md](modello-dati.md).
  *Codice:* `migrations/env.py` · `app/db/models.py`

### Log

- **[ARC-09]** Tutti i log dell'applicazione e di uvicorn (`uvicorn.error`,
  `uvicorn.access`) finiscono in `logs/app.log` (nel container
  `/app/logs/app.log`, cioè `./data/logs/app.log` sull'host), a rotazione da
  10 MB con 5 file di storico, livello `INFO`. La configurazione avviene
  all'import di `app/main.py`, prima di qualunque altro modulo applicativo.
  *Codice:* `app/logging_config.py:setup_logging`

## Mappa del codice

Ogni file sotto `app/`, raggruppato per pacchetto. I file `__init__.py`
sono vuoti e non sono elencati.

### Radice e infrastruttura

| File | Responsabilità |
|---|---|
| `app/main.py` | Punto d'ingresso: `lifespan` (validazione segreti, avvio e arresto dei sei task), inclusione dei router, gestore degli errori non previsti, pagine HTML, `/health`, mount dei file statici |
| `app/config.py` | `Settings` (variabili d'ambiente / `.env`), istanza `settings`, `validate_runtime_secrets`, `ConfigError` |
| `app/logging_config.py` | `setup_logging`: file di log a rotazione |
| `app/db/base.py` | `engine`, `AsyncSessionLocal`, pragma SQLite, `Base` dichiarativa |
| `app/db/session.py` | `get_session`, dipendenza FastAPI che apre una sessione per richiesta |
| `app/db/models.py` | Tutte le tabelle (`User`, `UtxoEvent`, `Round`, `RoundParticipant`, `RoundConfig`, `PendingTransaction`, `Withdrawal`, `BugReport`, `AuditLog`) e l'indice del round attivo unico — vedi [modello-dati.md](modello-dati.md) |
| `app/audit/log.py` | `write_audit_log`: aggiunge una riga al registro di audit nella sessione del chiamante (il commit resta al chiamante) — catalogo eventi in [audit-log.md](audit-log.md) |

### API HTTP

| File | Responsabilità |
|---|---|
| `app/api/errors.py` | `ApiError` (codice + messaggio inglese + parametri), `http_error`, `from_api_error`: il formato strutturato di `detail` — vedi [api.md](api.md) |
| `app/api/client_ip.py` | `client_ip`: IP reale del chiamante (ultimo elemento di `X-Forwarded-For`), usato da tutti i controlli basati sull'IP |
| `app/api/timeutil.py` | `isoformat_utc`: serializza le date come UTC esplicito (SQLite le restituisce senza fuso) |
| `app/api/routes/admin.py` | `/admin/*`: `require_admin` (token condiviso), configurazione, pausa/ripresa, utenti, export WIF, reset password, round, transazioni pendenti, audit log, bug report |
| `app/api/routes/bets.py` | `POST /bets`: controllo connessione, lock per utente, chiamata a `place_bet` |
| `app/api/routes/withdrawals.py` | `POST /withdrawals`: stessa struttura, chiama `request_withdrawal` |
| `app/api/routes/rounds.py` | `GET /rounds/current` e il canale SSE `GET /rounds/stream` |
| `app/api/routes/users.py` | `GET /users/me`, cambio password, `GET /users/me/last-round-result` |
| `app/api/routes/qr.py` | `GET /qr/{address}`: PNG del QR, indirizzo validato, rendering memorizzato e fuori dall'event loop |
| `app/api/routes/bug_reports.py` | `POST /bug-reports`, `GET /bug-reports/mine` |

### Autenticazione

| File | Responsabilità |
|---|---|
| `app/auth/routes.py` | `/auth/register`, `/auth/login`; notifica al listener il nuovo indirizzo da osservare |
| `app/auth/security.py` | Argon2 (versioni sincrone e `*_async` su threadpool), creazione e decodifica JWT, `MIN_PASSWORD_LENGTH` |
| `app/auth/dependencies.py` | `get_current_user`, `get_optional_user` (controllo del claim `tv`) |
| `app/auth/rate_limit.py` | `RateLimiter`, `RollingQuota`, `AuthRateLimiters` (tenuti su `app.state`) — vedi [sicurezza.md](sicurezza.md) |

### Wallet e chiavi

| File | Responsabilità |
|---|---|
| `app/wallet/plm_network.py` | Parametri della rete PLM per embit (`PLM_MAINNET`), coin type 746, `ACCOUNT_PATH` |
| `app/wallet/keystore.py` | Cifratura/decifratura Fernet della master xprv |
| `app/wallet/hd.py` | Generazione della master key, derivazione di indirizzi/chiavi utente (`0/i`) e del pool (`1/0`), export WIF; la chiave d'account decifrata resta in cache nel processo |
| `app/wallet/address.py` | `is_valid_plm_address`: checksum bech32 + HRP `plm` |
| `app/wallet/balance.py` | `recompute_balance` (saldo confermato), `compute_pending_balance` (saldo mostrato) — vedi [registrazione-e-depositi.md](registrazione-e-depositi.md) |
| `app/wallet/psbt_builder.py` | Selezione UTXO, costruzione e firma di scommessa, prelievo e pagamento; limiti `MAX_TX_INPUTS`, `MAX_PAYOUT_TX_INPUTS`, `MAX_PARTICIPANTS_PER_ROUND`, `DUST_LIMIT_SATS` |

### Rete Electrum

| File | Responsabilità |
|---|---|
| `app/electrum/client.py` | `ElectrumClient` (JSON-RPC, timeout per richiesta), `ElectrumEndpoint`, `parse_endpoints` |
| `app/electrum/listener.py` | `ElectrumListener`: l'unica connessione, rotazione, keepalive, validazione header, corroborazione, sottoscrizioni e accredito — vedi [connessione-electrum.md](connessione-electrum.md) |
| `app/electrum/scripthash.py` | `address_to_scripthash`: scripthash Electrum di un indirizzo |

### Dominio

| File | Responsabilità |
|---|---|
| `app/deposits/service.py` | Accredito dei depositi, UTXO spesi fuori piattaforma e loro ripristino |
| `app/deposits/reconcile.py` | `DepositReconciler`: ricontrollo periodico di tutti gli indirizzi |
| `app/bets/service.py` | `place_bet`, `BetError`, rilascio di una scommessa fallita |
| `app/bets/confirmation.py` | Gestore di conferma per il tipo `bet` |
| `app/withdrawals/service.py` | `request_withdrawal`, `WithdrawalError`, rilascio di un prelievo fallito |
| `app/withdrawals/confirmation.py` | Gestore di conferma per il tipo `withdrawal` |
| `app/rounds/service.py` | Round attivo, scadenza, accettazione scommesse, `rounds_can_open`, apertura del round, quota del vincitore |
| `app/rounds/scheduler.py` | `RoundScheduler`: chiusura, estrazione, pagamento e suoi tentativi |
| `app/rounds/draw.py` | Matematica degli header (hash, prev-hash, target) e scelta del vincitore |
| `app/rounds/config.py` | `get_round_config`: la riga unica di `round_config`, creata se manca |
| `app/rounds/confirmation.py` | Gestore di conferma per il tipo `payout` |
| `app/rounds/events.py` | `RoundEventBroadcaster` e il singleton `broadcaster` (SSE) |

Flussi descritti in [scommesse-e-prelievi.md](scommesse-e-prelievi.md),
[ciclo-di-vita-del-round.md](ciclo-di-vita-del-round.md) e
[registrazione-e-depositi.md](registrazione-e-depositi.md).

### Transazioni

| File | Responsabilità |
|---|---|
| `app/tx/confirmation.py` | `ConfirmationPoller`, `poll_once`, registro dei gestori (`register_handler`) |
| `app/tx/broadcast.py` | `RbfBumper`, `should_bump`, `bump_fee` |
| `app/tx/reconcile.py` | `PendingTransactionReconciler`, `reconcile_once`: promozione o abbandono delle righe `building`/`pending` |
| `app/tx/pending_address.py` | `own_address_for`: indirizzo proprietario degli input di una transazione (utente o pool) |
| `app/tx/locks.py` | `UserLocks`: lock asincrono per utente |

Dettagli in [transazioni-e-riconciliazione.md](transazioni-e-riconciliazione.md).

### Frontend statici

| File | Responsabilità |
|---|---|
| `app/static/index.html` | Pagina `/` per i giocatori |
| `app/static/app.js` | Logica di `/`: autenticazione, pannelli, polling, SSE, rivelazione del risultato |
| `app/static/style.css` | Stile di `/` (e di `/report-bug`) |
| `app/static/i18n.js` | Tabella `TRANSLATIONS` in 7 lingue, `t()`, `tOrNull()`, `setLanguage()`, `applyStaticTranslations()` |
| `app/static/report-bug.html` | Pagina `/report-bug`, con il proprio script inline |
| `app/static/admin.html` | Pannello `/admin` |
| `app/static/admin.js` | Logica del pannello: token, sezioni, polling dello stato catena, SSE |
| `app/static/admin.css` | Stile del pannello |
| `app/static/guida.html` | Pagina `/guida`, per ora un segnaposto |

### Dipendenze tra pacchetti

Il grafo riporta gli import tra i pacchetti di `app/` (a livello di pacchetto,
non di singolo modulo). `db` e `config` sono importati quasi ovunque e sono
omessi dalle frecce per leggibilità.

```mermaid
flowchart TD
    main["main"] --> routes["api.routes"]
    main --> auth
    main --> tx
    main --> rounds
    main --> electrum
    main --> deposits
    main --> bets
    main --> withdrawals

    routes --> auth
    routes --> bets
    routes --> withdrawals
    routes --> rounds
    routes --> wallet
    routes --> audit
    routes --> apiutil["api (errors, client_ip, timeutil)"]
    auth --> apiutil
    auth --> wallet

    bets --> apiutil
    bets --> rounds
    bets --> wallet
    bets --> audit
    bets -- "register_handler" --> tx
    withdrawals --> apiutil
    withdrawals --> rounds
    withdrawals --> wallet
    withdrawals --> audit
    withdrawals -- "register_handler" --> tx

    rounds --> electrum
    rounds --> wallet
    rounds --> audit
    rounds -- "register_handler" --> tx

    electrum --> deposits
    electrum -- "draw (header math), events" --> rounds
    deposits --> electrum
    deposits --> wallet
    deposits --> audit
    deposits -- "events" --> rounds

    tx --> wallet
    tx --> electrum
    tx --> audit
    tx -- "events, config" --> rounds
```

- **[ARC-10]** Il poller delle conferme (`app/tx/confirmation.py`) non importa
  i moduli di dominio: sono `app/bets/confirmation.py`,
  `app/rounds/confirmation.py` e `app/withdrawals/confirmation.py` a
  registrarsi con `register_handler(kind, handler)` al momento dell'import,
  per i tipi `bet`, `payout` e `withdrawal`.
  *Codice:* `app/tx/confirmation.py:register_handler` ·
  `app/bets/confirmation.py` · `app/rounds/confirmation.py` ·
  `app/withdrawals/confirmation.py` ·
  *Test:* `tests/unit/test_confirmation.py`
- **[ARC-11]** Gli errori di dominio destinati all'utente sono sottoclassi di
  `ApiError` (`BetError`, `WithdrawalError`) sollevate direttamente dai
  servizi, con il codice che il frontend traduce; le route li convertono in
  `HTTPException` scegliendo lo stato HTTP. Per questo `bets` e
  `withdrawals` dipendono da `app/api/errors.py`.
  *Codice:* `app/api/errors.py:ApiError` · `app/bets/service.py:BetError` ·
  `app/withdrawals/service.py:WithdrawalError`

## Avvio del processo

`app/main.py` fa due cose distinte: **all'import** costruisce l'applicazione
FastAPI; **all'avvio del server** (il `lifespan`) prepara lo stato condiviso
e lancia le attività in background.

```mermaid
sequenceDiagram
    participant U as uvicorn
    participant M as app/main.py (import)
    participant L as lifespan
    U->>M: import app.main
    M->>M: setup_logging()
    M->>M: import dei gestori di conferma (bet, payout, withdrawal)
    M->>M: FastAPI(...), include_router ×8, exception handler, route HTML, mount /
    U->>L: startup
    L->>L: validate_runtime_secrets()
    L->>L: parse_endpoints(...)
    L->>L: app.state.electrum_listener, app.state.user_locks
    L->>L: create_task ×6
    Note over L: il server serve richieste
    U->>L: shutdown
    L->>L: cancel() dei 6 task, chiusura del client Electrum
```

### All'import

- **[ARC-12]** `setup_logging()` è chiamata come prima istruzione applicativa
  di `app/main.py`, prima di importare qualunque altro modulo `app.*`, così
  anche i log emessi durante gli import finiscono nel file.
  *Codice:* `app/main.py` · `app/logging_config.py:setup_logging`
- **[ARC-13]** `app/main.py` importa `app.bets.confirmation`,
  `app.rounds.confirmation` e `app.withdrawals.confirmation` **solo per il
  loro effetto collaterale** (la registrazione del gestore, vedi
  [ARC-10]). Questi import non vanno rimossi: senza gestore, il poller
  segnerebbe comunque la `PendingTransaction` come `confirmed`, ma senza
  aggiornare il partecipante, il round o il prelievo corrispondente.
  *Codice:* `app/main.py` · `app/tx/confirmation.py:poll_once`
- **[ARC-14]** La documentazione automatica (`/docs`, `/redoc`,
  `/openapi.json`) è disattivata a meno che `ENABLE_API_DOCS` sia vero.
  *Codice:* `app/main.py` · *Test:* `tests/unit/test_docs_disabled.py`
- **[ARC-15]** I router vengono inclusi in quest'ordine: `auth`, `users`,
  `bets`, `withdrawals`, `admin`, `bug_reports`, `qr`, `rounds`. Gli endpoint
  sono in [api.md](api.md).
  *Codice:* `app/main.py`
- **[ARC-16]** Qualunque eccezione non gestita produce una risposta 500 con
  lo stesso formato degli errori voluti
  (`{"detail": {"code": "internal_error", "message": "internal server error", "params": {}}}`);
  il dettaglio dell'eccezione va solo nel log, mai nella risposta.
  *Codice:* `app/main.py:log_unhandled_exception` ·
  *Test:* `tests/unit/test_rounds_route.py`
- **[ARC-17]** `GET /health` risponde `{"status": "ok"}` senza toccare
  database né rete.
  *Codice:* `app/main.py:health`
- **[ARC-18]** Le quattro pagine HTML hanno route esplicite che servono il
  file con `Cache-Control: no-store`: `/` → `index.html`, `/admin` →
  `admin.html`, `/guida` → `guida.html`, `/report-bug` → `report-bug.html`.
  Per ultimo, l'intera cartella `app/static/` è montata su `/` con
  `StaticFiles(html=True)`: JS, CSS e ogni altro file vi sono serviti con il
  loro nome (`/app.js`, `/i18n.js`, `/admin.css`…). I percorsi sono relativi
  alla directory di lavoro, che nel container è `/app`.
  *Codice:* `app/main.py:index_page` · `app/main.py:admin_panel` ·
  `app/main.py:user_guide` · `app/main.py:report_bug_page`

### Nel lifespan

- **[ARC-19]** Come primo passo, `validate_runtime_secrets()` fa rifiutare
  l'avvio (solleva `ConfigError`) se `JWT_SECRET` è più corto di 32
  caratteri o `XPRV_ENCRYPTION_KEY` è vuota, riportando tutti i problemi
  insieme. `ADMIN_TOKEN` vuoto **non** blocca l'avvio: il pannello resta
  semplicemente chiuso. Il controllo sta nel lifespan e non in un validatore
  di `Settings`, così import e test non hanno bisogno di segreti veri.
  *Codice:* `app/config.py:validate_runtime_secrets` ·
  *Test:* `tests/unit/test_config.py`
- **[ARC-20]** Gli endpoint Electrum vengono letti da `ELECTRUM_HOST`,
  `ELECTRUM_PORT`, `ELECTRUM_USE_SSL` ed `ELECTRUM_FALLBACK_SERVERS`; un
  elenco di riserva malformato blocca l'avvio. L'ordine di rotazione viene
  scritto nel log.
  *Codice:* `app/electrum/client.py:parse_endpoints` ·
  *Test:* `tests/unit/test_electrum_client.py`
- **[ARC-21]** Lo stato condiviso con le route vive su `app.state`:
  `electrum_listener` (l'`ElectrumListener`) e `user_locks` (un
  `UserLocks`), creati nel lifespan; `auth_rate_limiters` viene invece creato
  alla prima richiesta di registrazione o login che ne ha bisogno.
  *Codice:* `app/main.py:lifespan` · `app/auth/routes.py:_rate_limiters`
- **[ARC-22]** Il lifespan crea esattamente sei task asyncio, nell'ordine
  `ElectrumListener`, `RoundScheduler`, `ConfirmationPoller`, `RbfBumper`,
  `PendingTransactionReconciler`, `DepositReconciler`. Allo spegnimento
  ciascun task riceve `cancel()` (senza attenderne la fine) e il client
  Electrum, se presente, viene chiuso.
  *Codice:* `app/main.py:lifespan` · *Test:* `tests/unit/test_code_comments.py`

## Attività in background

| Task | Costruito con | Cadenza | Ruolo |
|---|---|---|---|
| `ElectrumListener` | `_make_electrum_client`, `AsyncSessionLocal`, endpoint | ciclo di riconnessione; ping ogni 60s | L'unica connessione Electrum: header, sottoscrizioni, accredito depositi |
| `RoundScheduler` | `AsyncSessionLocal`, `listener` | 5s | Apre/chiude i round, estrae, avvia e ritenta i pagamenti |
| `ConfirmationPoller` | `AsyncSessionLocal`, `lambda: listener.client` | 10s | `pending` → `confirmed` e gestore per tipo |
| `RbfBumper` | `AsyncSessionLocal`, `lambda: listener.client` | 30s | Aumenta la commissione di ciò che è `pending` oltre `rbf_timeout_seconds` |
| `PendingTransactionReconciler` | `AsyncSessionLocal`, `lambda: listener.client` | subito, poi 120s | Promuove o abbandona le righe `building`/`pending` |
| `DepositReconciler` | `AsyncSessionLocal`, `listener` | 300s, attende prima del primo giro | `refresh_user` su ogni indirizzo |

- **[ARC-23]** **Accesso al client Electrum.** Nessun task tiene un
  riferimento fisso al client: `ConfirmationPoller`, `RbfBumper` e
  `PendingTransactionReconciler` ricevono `lambda: listener.client` e lo
  rileggono a ogni giro; `RoundScheduler` e `DepositReconciler` ricevono il
  listener intero e leggono `listener.client` (il secondo anche per chiamare
  `refresh_user`). Così una riconnessione sostituisce il client sotto tutti.
  Un client non nullo implica che l'altezza della catena sia già nota (vedi
  [connessione-electrum.md](connessione-electrum.md)).
  *Codice:* `app/main.py:lifespan`
- **[ARC-24]** **Client assente.** Quando `listener.client` è `None` ogni task
  salta il giro e riprova alla cadenza successiva; `DepositReconciler`
  interrompe anche una scansione in corso. Le route che devono trasmettere
  (`POST /bets`, `POST /withdrawals`) rispondono invece `503`
  `network_unavailable`.
  *Codice:* `app/rounds/scheduler.py:RoundScheduler._tick` ·
  `app/tx/confirmation.py:ConfirmationPoller.run` ·
  `app/tx/broadcast.py:RbfBumper.run` ·
  `app/tx/reconcile.py:PendingTransactionReconciler.run` ·
  `app/deposits/reconcile.py:DepositReconciler._sweep_once` ·
  `app/api/routes/bets.py:create_bet` ·
  `app/api/routes/withdrawals.py:create_withdrawal` ·
  *Test:* `tests/unit/test_deposit_reconcile.py`
- **[ARC-25]** **Errori.** Ogni ciclo intercetta qualunque `Exception` di un
  giro, la scrive nel log con lo stack e riprende alla cadenza successiva;
  solo `CancelledError` (lo spegnimento) esce dal ciclo. All'interno di un
  giro, poller, bumper, riconciliatore e `DepositReconciler` isolano anche il
  singolo elemento: una transazione o un utente che fallisce non ferma gli
  altri. Non esiste un supervisore: un task che terminasse non verrebbe
  riavviato (l'unico caso previsto è il listener senza alcun endpoint, che
  scrive un errore ed esce; `parse_endpoints` include però sempre il server
  primario).
  *Codice:* `app/rounds/scheduler.py:RoundScheduler.run` ·
  `app/tx/confirmation.py:poll_once` · `app/tx/broadcast.py:RbfBumper._tick` ·
  `app/tx/reconcile.py:reconcile_once` ·
  `app/deposits/reconcile.py:DepositReconciler.run` ·
  `app/electrum/listener.py:ElectrumListener.run` ·
  *Test:* `tests/unit/test_confirmation.py` · `tests/unit/test_reconcile.py` ·
  `tests/unit/test_deposit_reconcile.py`
- **[ARC-26]** **`ElectrumListener`.** Dopo ogni sessione terminata passa
  subito al server successivo; l'attesa crescente (1s raddoppiando fino a 30s)
  scatta solo quando tutti i server hanno fallito nello stesso giro.
  Rotazione, keepalive, validazione e corroborazione sono in
  [connessione-electrum.md](connessione-electrum.md).
  *Codice:* `app/electrum/listener.py:ElectrumListener.run` ·
  *Test:* `tests/unit/test_electrum_listener.py`
- **[ARC-27]** **`RoundScheduler`.** A ogni giro (5s) chiama
  `open_new_round_if_needed` e poi avanza il round attivo. L'estrazione
  (`_close_and_draw`, con l'attesa del blocco successivo) viene eseguita
  **dentro** il giro: finché dura, lo scheduler non fa altro. Dopo un riavvio
  un round rimasto in `drawing` non viene ripreso (limite accettato, vedi
  [decisioni-e-limiti.md](decisioni-e-limiti.md)). Logica del round in
  [ciclo-di-vita-del-round.md](ciclo-di-vita-del-round.md).
  *Codice:* `app/rounds/scheduler.py:RoundScheduler._tick` ·
  `app/rounds/scheduler.py:RoundScheduler._close_and_draw` ·
  *Test:* `tests/unit/test_scheduler.py`
- **[ARC-28]** **`ConfirmationPoller`** (10s), **`RbfBumper`** (30s) e
  **`PendingTransactionReconciler`** (al primo giro subito, poi ogni 120s)
  lavorano sulla tabella `pending_transactions`; il riconciliatore parte
  subito perché un crash durante un invio lascia proprio una riga `building`
  da risolvere al riavvio. Regole in
  [transazioni-e-riconciliazione.md](transazioni-e-riconciliazione.md).
  *Codice:* `app/tx/confirmation.py:ConfirmationPoller` ·
  `app/tx/broadcast.py:RbfBumper` ·
  `app/tx/reconcile.py:PendingTransactionReconciler` ·
  *Test:* `tests/unit/test_confirmation.py` · `tests/unit/test_broadcast.py` ·
  `tests/unit/test_reconcile.py`
- **[ARC-29]** **`DepositReconciler`** attende 300s, poi scorre tutti gli
  utenti e chiama `listener.refresh_user` su ciascuno: lo stesso codice usato
  dalle notifiche, così i due percorsi non possono divergere.
  *Codice:* `app/deposits/reconcile.py:DepositReconciler._sweep_once` ·
  *Test:* `tests/unit/test_deposit_reconcile.py`

## Configurazione

La configurazione è divisa in due posti con regole diverse.

- **[ARC-30]** **Segreti e collegamenti infrastrutturali** stanno nelle
  variabili d'ambiente (file `.env`, letto da `Settings`; variabili sconosciute
  ignorate). `settings` è costruito una volta all'import di `app/config.py`:
  una modifica richiede il riavvio del container. I campi sono:

  | Campo (`Settings`) | Variabile | Predefinito | Uso |
  |---|---|---|---|
  | `database_url` | `DATABASE_URL` | `sqlite+aiosqlite:///./plm_lottery.db` | URL SQLAlchemy (in Docker sovrascritto dal compose) |
  | `electrum_host` | `ELECTRUM_HOST` | `santantonio.sytes.net` | Server Electrum primario |
  | `electrum_port` | `ELECTRUM_PORT` | `50002` | Porta del primario |
  | `electrum_use_ssl` | `ELECTRUM_USE_SSL` | `True` | TLS verso il primario |
  | `electrum_fallback_servers` | `ELECTRUM_FALLBACK_SERVERS` | `""` | Riserve, `host:porta[:notls]` separati da virgola |
  | `xprv_encryption_key` | `XPRV_ENCRYPTION_KEY` | `""` | Chiave Fernet della master xprv (obbligatoria, [ARC-19]) |
  | `master_key_path` | `MASTER_KEY_PATH` | `./master.xprv.enc` | File della master xprv cifrata (in Docker sovrascritto dal compose) |
  | `jwt_secret` | `JWT_SECRET` | `""` | Chiave HS256 dei token (≥ 32 caratteri, [ARC-19]) |
  | `jwt_algorithm` | `JWT_ALGORITHM` | `HS256` | Algoritmo JWT |
  | `jwt_expire_minutes` | `JWT_EXPIRE_MINUTES` | `1440` (24h) | Durata del token |
  | `admin_token` | `ADMIN_TOKEN` | `""` | Token del pannello `/admin`; vuoto = pannello chiuso |
  | `enable_api_docs` | `ENABLE_API_DOCS` | `False` | Espone Swagger/ReDoc/OpenAPI ([ARC-14]) |

  *Codice:* `app/config.py:Settings` · *Test:* `tests/unit/test_config.py`
- **[ARC-31]** **Parametri operativi e di business** (costo della scommessa,
  durata e pausa del round, animazione, commissione di rete, timeout RBF,
  indirizzo commissioni, pausa di manutenzione) stanno nell'unica riga della
  tabella `round_config`, modificabile a caldo da `/admin` senza riavvio. I
  valori iniziali sono i default delle colonne di `RoundConfig`, non
  `app/config.py`. Se la riga manca, viene creata al primo accesso con
  `fee_address` vuoto. Campi in [modello-dati.md](modello-dati.md), effetti
  in [ciclo-di-vita-del-round.md](ciclo-di-vita-del-round.md).
  *Codice:* `app/rounds/config.py:get_round_config` ·
  `app/db/models.py:RoundConfig`
- **[ARC-32]** Alcuni valori sono costanti nel codice e non configurabili:
  la ripartizione 70/30, le conferme richieste (1), i limiti di input e di
  partecipanti, le cadenze dei task. Si cambiano solo con una modifica al
  codice (vedi [decisioni-e-limiti.md](decisioni-e-limiti.md)).
  *Codice:* `app/rounds/service.py:winner_share` ·
  `app/wallet/psbt_builder.py` · `app/tx/confirmation.py`

## Aggiornamenti in tempo reale (SSE)

Le pagine si aggiornano da sole in due modi sovrapposti: il polling
periodico e, in più, un canale **Server-Sent Events** che le avvisa appena
qualcosa cambia.

```mermaid
flowchart LR
    subgraph Processo
        P1["round aperto / cambio di stato"] --> BR
        P2["scommessa o prelievo inviato / annullato"] --> BR
        P3["transazione confermata / abbandonata"] --> BR
        P4["deposito accreditato / UTXO spesa o ripristinata"] --> BR
        P5["nuovo header"] --> BR
        BR["broadcaster.publish()"] --> Q1["coda client 1<br/>(maxsize 1)"]
        BR --> Q2["coda client N"]
    end
    Q1 -- "event: update" --> S1["EventSource /"]
    Q2 -- "event: update" --> S2["EventSource /admin"]
    S1 -. "rifà le GET REST" .-> API["/rounds/current, /users/me, …"]
```

- **[ARC-33]** Il canale è pub/sub **in-process**: `broadcaster` è un unico
  `RoundEventBroadcaster` per processo, con una `asyncio.Queue(maxsize=1)`
  per client. `publish()` mette una notifica in ogni coda non piena; se la
  coda è già piena la nuova notifica viene scartata, perché quella in attesa
  basta già a far ricaricare tutto (notifiche ridondanti si fondono).
  *Codice:* `app/rounds/events.py:RoundEventBroadcaster` ·
  *Test:* `tests/unit/test_round_events.py`
- **[ARC-34]** Il messaggio non ha contenuto e lo stream non ha
  autenticazione: è solo un segnale "è cambiato qualcosa, ricarica". Ogni
  dato, compresa la personalizzazione (come `user_played`), arriva dagli
  endpoint REST autenticati. Il segnale è globale: ogni client viene avvisato
  di ogni evento, anche di quelli che non lo riguardano.
  *Codice:* `app/api/routes/rounds.py:round_stream`
- **[ARC-35]** Limiti di sottoscrizione: al massimo `MAX_SUBSCRIBERS` (500)
  stream in tutto, oltre i quali `GET /rounds/stream` risponde `503` e il
  browser ricade sul polling; e al massimo `MAX_SUBSCRIBERS_PER_IP` (5) per
  IP client, oltre i quali la connessione **più vecchia** di quello stesso IP
  viene chiusa (le si invia il segnale `EVICTED`) invece di rifiutare la
  nuova. L'IP è quello di `client_ip` (vedi [sicurezza.md](sicurezza.md)).
  *Codice:* `app/rounds/events.py:RoundEventBroadcaster.subscribe` ·
  `app/api/routes/rounds.py:round_stream` ·
  *Test:* `tests/unit/test_round_events.py`
- **[ARC-36]** Lo stream invia `event: update` con `data: {}` per ogni
  notifica. Da fermo controlla `request.is_disconnected()` ogni 5 secondi e
  invia un commento `: keep-alive` ogni 20 secondi (4 controlli), così né un
  client sparito senza chiudere né il timeout di inattività di un proxy lo
  lasciano appeso. La risposta porta `Cache-Control: no-store` e
  `X-Accel-Buffering: no`. Alla chiusura il client viene sempre rimosso.
  *Codice:* `app/api/routes/rounds.py:round_stream`
- **[ARC-37]** `publish()` viene chiamato in questi punti, e ogni nuovo
  cambiamento di stato visibile deve aggiungersi a questo elenco:
  - apertura di un round — `app/rounds/service.py:open_new_round_if_needed`;
  - ogni transizione di stato del round (`closing`, `closed` senza
    partecipanti, `drawing`, `paying_out`) —
    `app/rounds/scheduler.py:RoundScheduler._tick`,
    `app/rounds/scheduler.py:RoundScheduler._close_and_draw`;
  - scommessa inviata e scommessa annullata —
    `app/bets/service.py:place_bet`, `app/bets/service.py:_release_failed_bet`;
  - prelievo inviato e prelievo annullato —
    `app/withdrawals/service.py:request_withdrawal`,
    `app/withdrawals/service.py:_release_failed_withdrawal`;
  - transazione confermata — `app/tx/confirmation.py:poll_once`;
  - riga promossa o abbandonata dal riconciliatore —
    `app/tx/reconcile.py:reconcile_once`;
  - deposito accreditato, UTXO segnata come spesa fuori piattaforma, UTXO
    ripristinata — `app/deposits/service.py:credit_confirmed_utxos`,
    `app/deposits/service.py:mark_utxos_spent_externally`,
    `app/deposits/service.py:reinstate_reappeared_utxos`;
  - nuovo header ricevuto — `app/electrum/listener.py:ElectrumListener._consume_headers`.

  *Test:* `tests/unit/test_bets.py` (verifica la notifica di una scommessa)

## Lock per utente

- **[ARC-38]** `UserLocks` tiene un `asyncio.Lock` per `user_id` (creato alla
  prima richiesta di quell'utente e mai rimosso). `POST /bets` e
  `POST /withdrawals` eseguono l'intera costruzione e trasmissione dentro
  `app.state.user_locks.acquire(user.id)`: per lo stesso utente una scommessa
  e un prelievo non sono mai in costruzione insieme, perché spendono dallo
  stesso insieme di UTXO. È l'unica esclusione reciproca tra i due flussi;
  cosa implica è in [scommesse-e-prelievi.md](scommesse-e-prelievi.md). Il
  controllo "client connesso" avviene prima di acquisire il lock.
  *Codice:* `app/tx/locks.py:UserLocks.acquire` ·
  `app/api/routes/bets.py:create_bet` ·
  `app/api/routes/withdrawals.py:create_withdrawal`

## Frontend

- **[ARC-39]** Le interfacce sono pagine statiche in `app/static/`, servite
  direttamente da FastAPI ([ARC-18]): HTML, JavaScript e CSS scritti a mano,
  senza passo di build, framework né bundler. Parlano tutte con la stessa API
  JSON; l'unica separazione tra utente e amministratore è `require_admin` sul
  lato server.
  *Codice:* `app/main.py` · `app/static/`

### `/` — giocatori

- **[ARC-40]** **Polling.** Da non autenticati, la pagina interroga
  `GET /rounds/current` ogni 15s solo per la barra di stato della catena. Da
  autenticati: `refreshRound` ogni 15s, ogni 3s mentre il round è in
  `closing`/`drawing`/`paying_out`; `checkLastRoundResult`
  (`GET /users/me/last-round-result`) ogni 20s; il conto alla rovescia
  locale ogni secondo. Quando la scheda torna visibile i dati si ricaricano
  subito (i timer delle schede in background vengono rallentati dal
  browser).
  *Codice:* `app/static/app.js:startChainOnlyPolling` ·
  `app/static/app.js:scheduleNextRoundPoll` ·
  `app/static/app.js:showDashboard`
- **[ARC-41]** **Richieste.** Ogni chiamata API di `/` ha un timeout di 15s;
  dopo 2 fallimenti consecutivi del polling la pagina mostra "connessione
  persa". Una risposta `401` con codice `session_expired` riporta al login.
  *Codice:* `app/static/app.js:call` · `app/static/app.js:noteFetchOutcome`
- **[ARC-42]** **SSE.** La pagina apre un solo `EventSource('/rounds/stream')`
  e reagisce sia agli eventi `update` sia a `open` (che scatta alla prima
  connessione e a ogni riconnessione automatica): da autenticati ricarica
  round, profilo e ultimo risultato, altrimenti solo lo stato della catena.
  Il polling resta attivo comunque: se lo stream cade o è bloccato la pagina
  funziona come prima, solo senza l'avviso immediato.
  *Codice:* `app/static/app.js:connectRoundEvents` ·
  `app/static/app.js:onRoundServerEvent`
- **[ARC-43]** **Chiavi di `localStorage`** usate da `/`:

  | Chiave | Contenuto |
  |---|---|
  | `plm_token` | JWT della sessione |
  | `plm_username` | Nome utente mostrato |
  | `plm_address` | Indirizzo di deposito |
  | `plm_persisted_result` | Risultato del round rivelato (`round_id`, `won`, `amount_sats`), per ridisegnarlo dopo un ricaricamento |
  | `plm_lang` | Lingua scelta (condivisa con `/report-bug`) |

  Il logout svuota `localStorage` tranne `plm_lang`. La rimozione di
  `plm_token` in una scheda riporta al login anche le altre schede aperte
  (evento `storage`). La logica della rivelazione del risultato è in
  [ciclo-di-vita-del-round.md](ciclo-di-vita-del-round.md).
  *Codice:* `app/static/app.js:logout` · `app/static/app.js:persistResult` ·
  `app/static/i18n.js:setLanguage`

### `/admin` — operatore

- **[ARC-44]** Il pannello chiede il token operatore, lo verifica con
  `GET /admin/config` e lo conserva in `sessionStorage` (`plm_admin_token`,
  quindi si perde chiudendo la scheda); ogni chiamata lo invia
  nell'intestazione `X-Admin-Token`. Non è collegato da `/` né lo collega.
  *Codice:* `app/static/admin.js:callAdmin`
- **[ARC-45]** Il pannello interroga `GET /rounds/current` ogni 15s per la
  barra di stato (stato del round e altezza della catena). Le sezioni Utenti,
  Round, Transazioni pendenti, Audit log e Bug report si caricano quando le
  si apre e si ricaricano a ogni evento SSE (`update` o `open`) mentre sono
  aperte; non hanno un polling periodico proprio. La sezione Parametri non
  viene ricaricata dagli eventi.
  *Codice:* `app/static/admin.js:startChainStatusPolling` ·
  `app/static/admin.js:connectAdminEvents` ·
  `app/static/admin.js:onAdminServerEvent`

### `/report-bug` e `/guida`

- **[ARC-46]** `/report-bug` è una pagina autonoma, raggiungibile con o senza
  login: se in `localStorage` c'è `plm_token` lo usa per allegare l'autore e
  per mostrare i propri report (`GET /bug-reports/mine`). Non usa SSE né
  polling. Il flusso di triage è descritto in [api.md](api.md) e in
  [guida-admin.md](guida-admin.md).
  *Codice:* `app/static/report-bug.html`
- **[ARC-47]** `/guida` è un segnaposto statico in italiano ("la guida
  completa sarà pubblicata qui a breve").
  *Codice:* `app/static/guida.html`

## Internazionalizzazione

Riguarda `/` e `/report-bug`. `/admin` e `/guida` sono volutamente solo in
italiano.

- **[ARC-48]** Le lingue supportate sono sette: `en`, `it`, `es`, `fr`, `de`,
  `ru`, `zh`. Tutte le stringhe stanno in un'unica tabella `TRANSLATIONS` in
  `app/static/i18n.js`, caricato prima dello script della pagina; non ci sono
  file separati né richieste di rete.
  *Codice:* `app/static/i18n.js`
- **[ARC-49]** La lingua iniziale è, nell'ordine: il valore di
  `localStorage.plm_lang` se supportato, le prime due lettere di
  `navigator.language` se supportate, altrimenti `en`. `setLanguage` salva la
  scelta in `plm_lang`, ritraduce la pagina e chiama `onLanguageChange` se la
  pagina la definisce. Su `/` il selettore sta nella barra di stato della
  catena, non nella barra di navigazione, perché quest'ultima è nascosta fino
  al login.
  *Codice:* `app/static/i18n.js:detectDefaultLang` ·
  `app/static/i18n.js:setLanguage` · `app/static/index.html`
- **[ARC-50]** Il markup statico si traduce con attributi: `data-i18n`
  (testo), `data-i18n-html`, `data-i18n-placeholder`, `data-i18n-title`,
  `data-i18n-aria-label`, `data-i18n-alt`, applicati da
  `applyStaticTranslations` al caricamento e a ogni cambio di lingua. Ciò che
  nasce da dati del server usa `t(chiave, parametri)` e viene ridisegnato da
  `onLanguageChange`. Un elemento usa **uno solo** dei due meccanismi, mai
  entrambi (per esempio `#bet-btn` non ha `data-i18n`, perché la sua
  etichetta contiene il costo configurabile).
  *Codice:* `app/static/i18n.js:applyStaticTranslations` ·
  `app/static/app.js:onLanguageChange` ·
  `app/static/app.js:renderBetButton`
- **[ARC-51]** Ogni lingua ha **esattamente lo stesso insieme di chiavi**.
  `t()` cerca la chiave nella lingua corrente, poi in `en`, e se manca anche
  lì restituisce la chiave stessa; `tOrNull()` restituisce invece `null`,
  così il chiamante può usare un testo di riserva. I parametri si
  sostituiscono nei segnaposto `{nome}`.
  *Codice:* `app/static/i18n.js:t` · `app/static/i18n.js:tOrNull`
- **[ARC-52]** L'API risponde in una sola lingua (inglese) con un `detail`
  strutturato `{code, message, params}` (vedi [api.md](api.md)); la
  traduzione spetta al client. Per un `detail` oggetto il frontend mostra
  `error.<code>` nella lingua corrente, con i parametri; a ogni parametro
  `*_sats` numerico affianca un `*_plm` già formattato; se il codice non ha
  traduzione mostra `message`. Un `detail` stringa viene mostrato così com'è;
  un `detail` lista (errore di validazione 422 di FastAPI) diventa
  `error.invalid_request`. Aggiungere un errore rivolto all'utente significa
  dargli un codice e aggiungere `error.<codice>` in tutte e sette le lingue.
  *Codice:* `app/static/app.js:apiErrorMessage` ·
  `app/static/app.js:errorParams` · `app/api/errors.py:ApiError`
- **[ARC-53]** Su `/report-bug` l'avviso `bugReport.englishNotice` è tradotto
  in tutte le lingue, ma dice sempre di scrivere la segnalazione in inglese,
  perché il pannello di triage non è tradotto.
  *Codice:* `app/static/report-bug.html` · `app/static/i18n.js`

## Test

- **[ARC-54]** La suite è tutta in `tests/unit/` (351 test raccolti);
  `tests/integration/` contiene solo `__init__.py`. Si esegue con
  `python -m pytest` dal venv. `pyproject.toml` imposta `testpaths = ["tests"]`
  e `asyncio_mode = "auto"`, quindi i test asincroni non richiedono
  `@pytest.mark.asyncio`. Dipendenze di sviluppo: `pytest`, `pytest-asyncio`,
  `httpx`.
  *Codice:* `pyproject.toml` · *Test:* `tests/unit/test_docs_current.py`
- **[ARC-55]** Non esiste un `conftest.py`: ogni file definisce le proprie
  fixture. Lo schema tipico di una fixture `session_factory` è: master key
  generata in una directory temporanea con una chiave Fernet casuale (e
  cache `hd._account_key` azzerata), engine SQLite in memoria con
  `Base.metadata.create_all` (le migrazioni Alembic non vengono eseguite),
  una riga `RoundConfig` con un `fee_address` valido dove serve aprire round.
  I test HTTP costruiscono un'app FastAPI minima con i soli router
  necessari, un `ElectrumListener` senza connessione su `app.state`, e la
  interrogano con `httpx.AsyncClient` su `ASGITransport`: il `lifespan` di
  `app/main.py` non viene eseguito.
  *Test:* `tests/unit/test_bets.py` · `tests/unit/test_rounds_route.py`
- **[ARC-56]** La rete non viene mai contattata: al posto del client e del
  listener Electrum ogni file usa classi finte locali, ad esempio
  `FakeElectrumClient` (`test_bets.py`, `test_withdrawals.py`,
  `test_balance.py`), `RejectingElectrumClient` (`test_bets.py`),
  `FakeClient` e `ExplodingClient` (`test_confirmation.py`), `FakeClient`
  (`test_broadcast.py`), `UnknownTxClient`, `KnownTxClient`, `BrokenClient`
  (`test_reconcile.py`), `FakeListener`, `FakePayoutClient`,
  `FakePayoutListener`, `CorroboratingListener`, `LateTipListener`,
  `StallingListener` (`test_scheduler.py`), `FakeListener`
  (`test_deposit_reconcile.py`), `FakeWriter` (`test_electrum_client.py`).
  *Test:* i file citati
- **[ARC-57]** Alcuni test verificano file che non sono codice Python,
  perché nessun altro test li eserciterebbe:
  - `test_docs_current.py`: il numero di test dichiarato in `CLAUDE.md` e
    `README.md` coincide con quello raccolto; `CLAUDE.md` non contiene
    affermazioni superate note; la mappa del codice di `CLAUDE.md` cita
    `rate_limit.py`, `client_ip.py` e `bug_reports`; i link relativi del
    README e le ancore verso `CLAUDE.md` esistono;
  - `test_docs_no_bare_uvicorn.py`: README e `docs/running-the-server.md`
    non documentano un `uvicorn --reload` fuori da Docker;
  - `test_code_comments.py`: alcuni commenti nel codice restano veri (per
    esempio il numero di task avviati dal lifespan, sei, citato in
    `app/db/base.py`);
  - `test_caddyfile_security_headers.py`: il `Caddyfile` mantiene le
    intestazioni di sicurezza e la sovrascrittura di `X-Forwarded-For`;
  - `test_withdrawals.py::test_the_docs_no_longer_claim_bets_and_withdrawals_are_exclusive`:
    [scommesse-e-prelievi.md](scommesse-e-prelievi.md) descrive correttamente
    la convivenza di scommessa e prelievo.

  Chi modifica questi file (compresi i documenti in `docs/`) deve tenerne
  conto.
  *Test:* `tests/unit/test_docs_current.py` ·
  `tests/unit/test_docs_no_bare_uvicorn.py` ·
  `tests/unit/test_code_comments.py` ·
  `tests/unit/test_caddyfile_security_headers.py` ·
  `tests/unit/test_withdrawals.py`
- **[ARC-58]** Ciò che la suite **non** copre: nessun test contro una
  connessione Electrum reale; il `lifespan` e l'avvio dei sei task; la route
  SSE `round_stream` (è testato solo il broadcaster); `UserLocks` e la sua
  acquisizione nelle route di scommessa e prelievo; il codice JavaScript dei
  frontend; la parità delle chiavi tra le lingue di `i18n.js`. Le verifiche
  dal vivo sono state manuali (`scripts/electrum_smoke_test.py` e transazioni
  reali su mainnet; prelievo e RBF mai trasmessi dal vivo, vedi
  [decisioni-e-limiti.md](decisioni-e-limiti.md)).

## Assunzioni di processo singolo

- **[ARC-59]** Diversi componenti tengono stato nella memoria del processo e
  funzionano correttamente solo con un unico processo uvicorn ([ARC-02]):
  - il canale SSE (`broadcaster`): un evento pubblicato in un processo non
    raggiungerebbe i client collegati a un altro;
  - i lock per utente (`UserLocks`): due processi potrebbero costruire
    insieme una scommessa e un prelievo dello stesso utente;
  - i limitatori di login e registrazione (`AuthRateLimiters` su
    `app.state`): ogni processo conterebbe separatamente;
  - l'`ElectrumListener` e i sei task: ogni processo aprirebbe la propria
    connessione e il proprio scheduler, con due scheduler che avanzano lo
    stesso round;
  - le cache locali (chiave d'account decifrata in `app/wallet/hd.py`, QR
    memorizzati in `app/api/routes/qr.py`), che sarebbero solo duplicate.

  Un deployment multi-processo richiederebbe un canale condiviso (per
  esempio Redis pub/sub) e un lock su database o Redis. Fa eccezione
  l'invariante "al massimo un round attivo", garantita da un indice del
  database e quindi valida anche con più processi (vedi
  [modello-dati.md](modello-dati.md)). La scelta è discussa in
  [decisioni-e-limiti.md](decisioni-e-limiti.md).
  *Codice:* `app/rounds/events.py:RoundEventBroadcaster` ·
  `app/tx/locks.py:UserLocks` · `app/auth/rate_limit.py:AuthRateLimiters` ·
  `app/main.py:lifespan`