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
| Directory | Contents |
|---|---|
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.