Skip to main content

Conventions

Language​

Code, comments, commit messages and identifiers are in English. This public site is also in English. Internal operational runbooks and historical records live under the repository's docs/; they may contain English or Italian and are not included in the public build.

Commits​

type(scope): description, for example feat(drone): drone media. A commit message says what changed and, where it is not obvious, why.

Branches​

Work happens on a branch off develop and is merged back into develop. main is what CI deploys to production, so merging into it is a deploy and happens deliberately.

Where code goes​

DirectoryContents
app/[lang]/localized pages
app/api/route handlers, annotated for the OpenAPI document
models/shared shapes, and the pure functions that carry a business rule
lib/shared logic
lib/server/server-only; server-only is imported so a client bundle cannot pull it in
data/server actions that read and write
migrations/SQLite migrations, applied by hand

Rules live in functions, not only in queries​

Where a rule decides who may see what, it exists as a pure function with its own tests, and the result of the database query passes through it before leaving. A query can be read but not verified; a function that is too strict breaks a test, while one that is too generous is noticed by nobody until a customer sees a vehicle that is not theirs.

Documentation​

  • Describe contracts and boundaries rather than pasting large code blocks.
  • Never put a secret, key or private hostname in this site.
  • Describe current behavior; label historical migrations and retired procedures explicitly rather than presenting them as active instructions.
  • For documentation-only changes, build the documentation with npm run docs:build; application test suites are a separate concern.
  • Keep acceptance criteria and evidence in issues, and priority, status and execution order in the Suite roadmap.