62 lines
7.6 KiB
Markdown
62 lines
7.6 KiB
Markdown
# 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](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](BUGS.md); accepted limits in [docs/limiti-noti.md](docs/limiti-noti.md); every closed `B-nn` is in [docs/storico-bug.md](docs/storico-bug.md) (`git log --all --grep 'B-nn'` finds its commit).
|
||
|
||
**[docs/](docs/README.md) 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](docs/come-funziona.md) and the ID convention and change workflow are in [docs/processo-di-modifica.md](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/](docs/), in Italian by explicit request (an exception to the English-only rule): the specification starting at [come-funziona.md](docs/come-funziona.md), the operational guides [setup.md](docs/setup.md), [running-the-server.md](docs/running-the-server.md), [guida-utente.md](docs/guida-utente.md), [guida-admin.md](docs/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](docs/README.md)** — the index of everything under `docs/`. Three rules, all in [docs/processo-di-modifica.md](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/](docs/adr/README.md)); *what* (verifiable rule) → a `PREFIX-NN` requirement in the domain document; *how* → the code; accepted limits → [limiti-noti.md](docs/limiti-noti.md) (`LIM-nn`); found/fixed defects → [storico-bug.md](docs/storico-bug.md) (`B-nn`, open ones in [BUGS.md](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](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](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](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](docs/README.md) (`RND`, `BET`, `WDR`, `DEP`, `REG`, `TX`, `ELC`, `AUD`, `ARC`, `DAT`, `API`, `SEC`, `OPS`) |
|
||
| Narrative overview | [docs/come-funziona.md](docs/come-funziona.md) |
|
||
| Accepted limits | [docs/limiti-noti.md](docs/limiti-noti.md) |
|
||
| Fix order for open B-nn | [docs/piano-correzioni.md](docs/piano-correzioni.md) |
|
||
|
||
## Django migration in progress (branch `django-migration`)
|
||
|
||
The repo is being moved from FastAPI to Django — plan in [roadmap.md](roadmap.md), decisions in ADR-54…60, requirements in [docs/sito-e-app.md](docs/sito-e-app.md) (`WEB`). Until roadmap D1 removes it, the **old FastAPI stack** (described in [docs/legacy-fastapi-notes.md](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).
|
||
|
||
```bash
|
||
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](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](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.
|