# 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/swagger-drogon/`: OpenAPI generator package.
- `scripts/generate_openapi.py`: compatibility wrapper for the generator.
- `docs/openapi/`: app-specific OpenAPI schema registry.
- `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 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
`scripts/swagger-drogon/` scans Drogon `ADD_METHOD_TO` route macros and the
adjacent `openapi:` metadata blocks in `controllers/*.h`. It also inspects
controller/service `.cc` files for simple query, JSON field and response field
patterns, then merges the app-specific registry in `docs/openapi/visione.yaml`.
The CMake `openapi` target writes `build/openapi/visione.openapi.json`.

This is a hybrid generator: C++ is the source of truth for routes and metadata,
while YAML provides schemas that cannot be safely inferred from dynamic
`Json::Value` payloads and raw SQL result rows. Generation fails if a route lacks
metadata, has unresolved schema refs, emits `/photos`, or leaves operation
request/response schemas as generic objects.

## 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/`.