backend/AGENTS.md

Visione Backend Agent Guide

Project Context

• This repository is the backend for Visione, an urban issue reporting webapp.
• The backend is C++20 with Drogon. Keep code, symbols, API fields, database names and comments in English.
• User-facing product labels may be Italian when they represent UI/business vocabulary.
• Docker is for local external services only: MySQL, Mailpit and future Redis-like dependencies.

Authoritative References

• Local Drogon source: /home/gabdevele/Projects/snitchitaly/backend/drogon
• Official Drogon docs: https://drogonframework.github.io/drogon-docs/
• Project docs start from docs/LLM_CONTEXT.md.

Architecture Rules

• Controllers parse HTTP input and shape HTTP responses only.
• Services own business rules.
• Repositories/database helpers own SQL access.
• Prefer small, readable C++ over clever abstractions.
• Use parameterized SQL; do not concatenate user input into SQL.
• Keep local development simple. Do not introduce production infrastructure unless requested.

Commands

• Configure: cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Debug
• Build: cmake --build build
• Test: ctest --test-dir build --output-on-failure
• OpenAPI: cmake --build build --target openapi
• Lab frontend: cd scripts/lab && uv run streamlit run app.py
• Local services: docker compose up -d
• App: ./build/visione-backend

Development Workflow

• Update docs when behavior, schema, setup or API contracts change.
• After each completed and verified feature, create a short commit.
• Keep commit messages concise, for example Add Mailpit config or Add report API.
• Do not spend excessive time on exhaustive tests; cover high-risk behavior and regressions.