# 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`.
Local CORS allows `http://localhost:5173` by default for the Vue frontend.

Local seeded admin:

- email: `admin@visione.local`
- 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:

```bash
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;"
```

```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