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.
• 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's MySQL client with parameterized SQL placeholders.

The codebase starts with raw SQL repositories because the schema is still evolving. Drogon ORM/codegen can be introduced later after the database model stabilizes.

Local Email

OTP emails are sent to MailHog over SMTP. MailHog 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

generate_openapi.py scans Drogon ADD_METHOD_TO route macros in controllers/*.h and generates build/openapi/visione.openapi.json.

This is a contract-last generator: the source of truth is the C++ controller route list, not a manually maintained static Swagger document. The current tool generates paths, methods, path parameters, bearer auth hints and common JSON or multipart request bodies. Deeper request/response schemas can be added later by teaching the generator project-specific conventions or comments.

Visione Lab

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 lab/.