Add Visione backend foundation

2026-06-02 19:22:00 +02:00
commit 580789ac83
52 changed files with 5008 additions and 0 deletions
@@ -0,0 +1,91 @@
+# Visione Backend
+
+C++20 API backend built with Drogon for the Visione urban reporting project.
+Docker is used only for local external services: MySQL and MailHog.
+
+## Setup
+
+Install native build dependencies first. On Ubuntu:
+
+```bash
+sudo apt install build-essential cmake ninja-build git pkg-config \
+  libjsoncpp-dev uuid-dev zlib1g-dev libssl-dev \
+  libmariadb-dev libmariadb-dev-compat
+```
+
+If CMake prints `MySql was not found`, the backend will compile without MySQL
+support and `/api/v1/ready` will not be useful. Install the MariaDB/MySQL client
+development packages above and re-run CMake.
+
+```bash
+cp .env.example .env
+docker compose up -d
+
+cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Debug
+cmake --build build
+./build/visione-backend config.json
+```
+
+The API listens on `http://localhost:5555`.
+MailHog listens on `http://localhost:8025`.
+
+```bash
+curl http://localhost:5555/api/v1/health
+curl http://localhost:5555/api/v1/ready
+curl -X POST http://localhost:5555/api/v1/echo \
+  -H 'Content-Type: application/json' \
+  -d '{"message":"hello"}'
+```
+
+Use `-DUSE_SYSTEM_DROGON=ON` only if Drogon is already installed and
+discoverable by CMake. The default build uses CPM.cmake and downloads Drogon
+`v1.9.13`.
+
+## Project Docs
+
+- `AGENTS.md`: durable instructions for coding agents.
+- `docs/LLM_CONTEXT.md`: short project context for future LLM sessions.
+- `docs/MILESTONE_01.md`: what this milestone implemented and what comes next.
+- `docs/API_SPEC.md`: API surface.
+- `docs/DATABASE_SCHEMA.md`: schema overview.
+- `docs/ARCHITECTURE.md`: backend structure.
+
+## Development Workflow
+
+1. Keep MySQL running with `docker compose up -d`.
+2. Add API endpoints in `controllers/` using `HttpController`.
+3. Register routes in the controller `METHOD_LIST_BEGIN` block with
+   `ADD_METHOD_TO(Controller::handler, "/api/v1/path", drogon::Get)`.
+4. Implement handlers with the Drogon signature:
+   `void handler(const HttpRequestPtr &, std::function<void(const HttpResponsePtr &)> &&callback)`.
+5. Return JSON with `HttpResponse::newHttpJsonResponse(...)`.
+6. Read app/database settings from `config.json`; do not hardcode connection
+   details in controllers.
+7. Add focused endpoint or helper tests for high-risk behavior, then run:
+
+```bash
+cmake --build build
+ctest --test-dir build --output-on-failure
+```
+
+The `RequestLogger` plugin logs every response as method, path, status and
+client address.
+
+## Current Endpoints
+
+- `GET /api/v1/health`: process health check, no external dependency.
+- `GET /api/v1/ready`: checks MySQL with `SELECT 1`.
+- Auth, reports and admin endpoints are documented in `docs/API_SPEC.md`.
+
+## Drogon Docs
+
+Official docs entrypoint: https://drogonframework.github.io/drogon-docs/
+
+Useful mirrored sections:
+
+- Install and CPM: https://github.com/drogonframework/drogon/wiki/ENG-02-Installation
+- Controller introduction: https://github.com/drogonframework/drogon/wiki/ENG-04-0-Controller-Introduction
+- HttpController: https://github.com/drogonframework/drogon/wiki/ENG-04-2-Controller-HttpController
+- Configuration file: https://github.com/drogonframework/drogon/wiki/ENG-11-Configuration-File
+- Database client: https://github.com/drogonframework/drogon/wiki/ENG-08-1-Database-DbClient
+- Testing: https://github.com/drogonframework/drogon/wiki/ENG-19-Testing-Framework