backend/docs/ARCHITECTURE.md

Visione Backend Architecture

Layout

• controllers/: Drogon HttpController classes.
• services/: application/business logic.
• repositories/: database helpers and migrations.
• common/: reusable HTTP, auth, crypto, email and validation utilities.
• migrations/: versioned SQL files.
• scripts/generate_openapi.py: minimal OpenAPI route extractor.
• docs/openapi/: manual OpenAPI contract documents.
• scripts/lab/: local Streamlit frontend for visual endpoint testing.
• docs/: product, API, schema and milestone documentation.

Drogon Usage

Controllers use Drogon route macros and return JSON with HttpResponse::newHttpJsonResponse. Database access uses drogon::orm::DbClient with raw parameterized SQL placeholders.

The codebase does not use Drogon generated models or Mapper<T>. Raw SQL stays in repository/database helpers because the schema is still evolving.

Local Email

OTP emails are sent to Mailpit over SMTP. Mailpit keeps messages local and inspectable through its web UI.

Password Hashing

User passwords use PBKDF2-HMAC-SHA256 with per-password random salts and 210000 iterations. This is intentionally slower than a plain SHA-256 digest and is available through OpenSSL, which is already a Drogon dependency in this project. Legacy sha256$ password hashes are rejected instead of silently accepted.

OpenAPI Generation

scripts/generate_openapi.py scans Drogon ADD_METHOD_TO route macros in controllers/*.h and extracts only paths, HTTP methods, operation ids, tags and path parameters. It merges those route skeletons with docs/openapi/visione.openapi.yaml, which owns summaries, request bodies, responses, schemas and examples. The manual file uses JSON-compatible YAML so the CMake openapi target can run without extra Python packages and writes build/openapi/visione.openapi.json.

If the manual YAML contains an operation that no longer exists in the Drogon route list, generation fails unless that operation is explicitly marked x-manual-only: true.

Visione Lab

scripts/lab/ is a Streamlit dev frontend for visual endpoint testing. It is intentionally separate from the real product frontend and should stay small: forms, uploads and response rendering only. Run it with uv from scripts/lab/.