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

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. Swagger UI is available at http://localhost:5555/api/v1/docs after the app has been built.

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/MILESTONE_02.md: workflow and authorization milestone.
• docs/MILESTONE_03.md: media upload, OpenAPI generator and API lab milestone.
• docs/API_SPEC.md: API surface.
• docs/DATABASE_SCHEMA.md: schema overview.
• docs/ARCHITECTURE.md: backend structure.

OpenAPI

The OpenAPI spec is generated from Drogon controller route macros, not written as a static Swagger file.

cmake --build build --target openapi
python3 -m json.tool build/openapi/visione.openapi.json >/dev/null

The app serves the generated JSON at /api/v1/openapi.json and Swagger UI at /api/v1/docs.

Visione Lab

scripts/lab/ is a small Streamlit frontend used only to test the backend visually while the real frontend is not ready.

cd scripts/lab
uv sync
uv run streamlit run app.py

Keep the backend running on http://127.0.0.1:5555. The lab calls the API from Python, so it is not blocked by browser CORS settings.

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

8. After each completed and verified feature, create a short commit.

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