2.4 KiB
Visione Backend Architecture
Layout
controllers/: DrogonHttpControllerclasses.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/.