Files
plm-lottery/CLAUDE.md
T

7.6 KiB
Raw Blame History

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Language

The user communicates in Italian in chat — reply to them in Italian. Everything written to the repository (code, comments, commit messages, docs, this file) must be in English. Reasoning/thinking should also be done in English.

Project status

The migration from FastAPI to Django is in progress on branch django-migration (plan: roadmap.md, steps A1–A10, B1–B2 done). The suite has 1181 tests: the old stack's under tests/unit/, the Django ones under tests/django/ (tests/integration/ is an empty package). Open defects of the old stack are in BUGS.md; accepted limits in docs/limiti-noti.md; every closed B-nn is in docs/storico-bug.md (git log --all --grep 'B-nn' finds its commit).

docs/ is the specification, and it is authoritative. Every verifiable rule there has a stable requirement ID (RND-04, BET-02, …) with *Codice:*/*Test:* pointers to what implements it; the index is docs/come-funziona.md and the ID convention and change workflow are in docs/processo-di-modifica.md. A behaviour change starts in the spec: edit or add the requirement, implement it, cite the ID in the test docstring and the commit message, and ship spec + code + test in one commit. If this file and the spec disagree, the spec wins and this file is the one to fix. Before writing code, read the relevant spec documents and the "Architecture" section below.

Human-facing guides are in docs/, in Italian by explicit request (an exception to the English-only rule): the specification starting at come-funziona.md, the operational guides setup.md, running-the-server.md, guida-utente.md, guida-admin.md. README's Quick start and docs/running-the-server.md are Docker-only, matching this file — a bare uvicorn --reload workflow was removed from both (B-44).

Documentation map (docs-first, SSOT, ADR)

Entry point: docs/README.md — the index of everything under docs/. Three rules, all in docs/processo-di-modifica.md:

  1. Docs-first. Behaviour changes start in docs/, never in the code. Spec + code + test ship in one commit, with the requirement/ADR ID in the test docstring and the commit message.
  2. SSOT. Every fact has one owner; everything else links to its ID instead of restating it. Why → an ADR (docs/adr/); what (verifiable rule) → a PREFIX-NN requirement in the domain document; how → the code; accepted limits → limiti-noti.md (LIM-nn); found/fixed defects → storico-bug.md (B-nn, open ones in BUGS.md). If two documents disagree, the spec wins and the other one gets fixed. This file included: it summarises, it does not own.
  3. One ADR per feature/decision. A new feature, or a change of an existing choice, starts with an ADR from docs/adr/TEMPLATE.md (next free ADR-NN, never reused or rewritten — a superseded one becomes "Sostituita da ADR-MM"), then its requirements, then the code. Add it to the area index and the feature → ADR table in docs/adr/README.md. Before touching a feature, read its ADRs there.
Need Go to
Why is it built this way / alternatives rejected docs/adr/README.md (the old DEC-nn are now ADR-nn, same numbers)
What exactly must it do domain docs listed in docs/README.md (RND, BET, WDR, DEP, REG, TX, ELC, AUD, ARC, DAT, API, SEC, OPS)
Narrative overview docs/come-funziona.md
Accepted limits docs/limiti-noti.md
Fix order for open B-nn docs/piano-correzioni.md

Django migration in progress (branch django-migration)

The repo is being moved from FastAPI to Django — plan in roadmap.md, decisions in ADR-54…60, requirements in docs/sito-e-app.md (WEB). Until roadmap D1 removes it, the old FastAPI stack (described in docs/legacy-fastapi-notes.md) has its code (app/) and its tests/unit/ suite stay in the repo and must keep passing, but it is no longer part of docker-compose.yml or the Docker image.

New layout: config/ (settings, urls, wsgi), apps/accounts (custom User), apps/lottery (round engine and the run_worker command), apps/web (public site and player app), apps/ops (staff console), tests in tests/django/ (settings config.settings_test, pytest-django). The stack is web (gunicorn) + worker (manage.py run_worker) + caddy on one SQLite file in WAL mode (ADR-55); it needs DJANGO_SECRET_KEY in .env (≥ 50 chars) and serves https://localhost with no domain (WEB-07).

DJANGO_DEBUG=true python manage.py runserver   # quick local run, no Docker (http://localhost:8000)
python manage.py makemigrations                # after editing a Django model; tests fail if one is missing
python -m pytest                               # old suite + tests/django together

Legacy FastAPI stack (removed in roadmap D1)

app/ and tests/unit/ still pass but are not deployed. Before touching them, read docs/legacy-fastapi-notes.md: commands (alembic, key scripts), Docker + Caddy, tech stack, PLM network and business parameters, code map, background tasks, the Electrum quorum, the 5 phases, transaction lifecycle, frontends, i18n, non-obvious decisions and known gaps of that stack. Keep python -m pytest green for both suites.

graphify

This project has a knowledge graph at graphify-out/ with god nodes, community structure, and cross-file relationships.

Rules:

  • When graphify-out/graph.json exists, run graphify query "<question>" before your first grep, search or source-file read for a codebase question, and put this rule in every subagent prompt that explores code. Read raw files only for lines the graph or an earlier read already located. Use graphify path "<A>" "<B>" for relationships and graphify explain "<concept>" for focused concepts. These return a scoped subgraph, usually much smaller than GRAPH_REPORT.md or raw grep output.
  • If graphify-out/wiki/index.md exists, use it for broad navigation instead of raw source browsing.
  • Read graphify-out/GRAPH_REPORT.md only for broad architecture review or when query/path/explain do not surface enough context.
  • Whenever you need context (where something lives, what depends on it, how two parts relate, what a change could affect), get it from the graph first — graphify query, path or explain — not by browsing or grepping files blindly. This applies to subagents too.
  • Whenever you modify code, update the graph before the commit: run graphify update . (AST-only, no API cost) so the graph always matches the committed code. Every commit of roadmap.md ends with it.
  • A change to docs only (no code) is not picked up by graphify update .; refresh the graph with /graphify --update when docs were restructured, not for every wording tweak.
  • A committed graphify-out/graph.json is rewritten whole on every build, so a large diff to it in a pull request is expected. Do not flag it as churn or suggest skipping the graph rebuild or its hooks.