Clean up OpenAPI scripts

docs/ARCHITECTURE.md

@@ -6,17 +6,17 @@
 - `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.
+- `scripts/generate_openapi.py`: OpenAPI generator.
+- `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's MySQL client
-with parameterized SQL placeholders.
+`HttpResponse::newHttpJsonResponse`. Database access uses
+`drogon::orm::DbClient` with raw 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.
+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
@@ -29,16 +29,17 @@ 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`.
+`scripts/generate_openapi.py` scans Drogon `ADD_METHOD_TO` route macros and the
+adjacent `openapi:` metadata blocks in `controllers/*.h`, then 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.
+generates paths, methods, path parameters, summaries, descriptions, auth hints
+and common JSON or multipart request bodies. Generation fails if a route lacks
+metadata.
 
 ## Visione Lab
-`lab/` is a Streamlit dev frontend for visual endpoint testing. It is
+`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 `lab/`.
+forms, uploads and response rendering only. Run it with uv from `scripts/lab/`.

docs/DATABASE_SCHEMA.md

@@ -2,6 +2,10 @@
 
 The schema is stored in `migrations/001_initial_schema.sql`.
 
+Persistence currently uses `drogon::orm::DbClient` with raw parameterized SQL.
+The project does not use Drogon generated models or `Mapper<T>` while the schema
+is still evolving.
+
 Important tables:
 
 - `users`: identity, personal data, password hash, points and moderation flags.

docs/MILESTONE_03.md

@@ -7,14 +7,15 @@
   than plain SHA-256 and available through the existing OpenSSL dependency.
 - Added report media uploads at `POST /api/v1/reports/{id}/media`.
 - Supported JPEG, PNG, WebP, MP4, WebM and QuickTime uploads.
-- Removed the old `/photos` upload path; report attachments now use `/media`.
-- Added generated OpenAPI JSON from Drogon controller route macros.
+- Report attachments now use the `/media` upload path.
+- Added generated OpenAPI JSON from Drogon controller route macros and adjacent
+  metadata blocks.
 - Exposed `/api/v1/openapi.json` and `/api/v1/docs`.
 - Added a small Streamlit API lab for visual endpoint testing.
 
 ## To do next
 - Add richer OpenAPI schema metadata for request and response bodies.
-- Consider extracting `generate_openapi.py` into an open-source standalone
+- Consider extracting `scripts/generate_openapi.py` into an open-source standalone
   project once the conventions stabilize.
 - Add minimal media upload integration tests after endpoint contracts settle.
 - Keep API and docs on `media` terminology only.