backend/README.md

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:

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.

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. Local CORS allows http://localhost:5173 by default for the future Vue frontend. Multipart uploads currently accept report images and videos up to the app body limit configured in config.json.

Local seeded admin:

• email: [email protected]
• password: ChangeMe123!
• the account has must_change_password = true and is for local development only.

If you already had a MySQL volume from the old scaffold, create the local database/user once:

docker compose exec -T mysql mysql -uroot -proot -e \
  "CREATE DATABASE IF NOT EXISTS visione CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; \
   CREATE USER IF NOT EXISTS 'visione'@'%' IDENTIFIED BY 'visione'; \
   ALTER USER 'visione'@'%' IDENTIFIED BY 'visione'; \
   GRANT ALL PRIVILEGES ON visione.* TO 'visione'@'%'; \
   FLUSH PRIVILEGES;"

curl http://localhost:5555/api/v1/health
curl http://localhost:5555/api/v1/ready
curl -X POST http://localhost:5555/api/v1/auth/login/password \
  -H 'Content-Type: application/json' \
  -d '{"email":"[email protected]","password":"ChangeMe123!"}'

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:

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