45 lines
2.0 KiB
Markdown
45 lines
2.0 KiB
Markdown
# 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/`.
|