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.

ENVIRONMENT: You are running in a docker container, so it's normal if something doesn't work as expected. You are allowed to install new tools, libraries or dependencies if you think they are necessary to complete your task. Since you are running in a docker container, you could have some build issues sometimes, do not waste tokens over-trying to fix them, just report the issue and move on to the next task if you believe the issue is not related to your task. Prefer using commands to read files, search for patterns ecc... since I have installed a tool that helps reduce token usage for those operations.

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.

2.3 KiB Raw Blame History