92 lines
3.2 KiB
Markdown
92 lines
3.2 KiB
Markdown
# 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
|