feat: implement backend/ — FastAPI backend API (Front 2)

[guidevit-dealsmartai]

Context

Part of the Application Layer design (Issue #7). Front 2 of 4.

Scope

Implement the FastAPI backend API under backend/. This is a read-only REST API that serves mandatário profiles, SCI scores, inconsistency cards, timelines, and search to the frontend.

Deliverables

Endpoints (backend/app/routers/)

Endpoint	Method	Description
/health	GET	Health check (DB connectivity)
/readiness	GET	Readiness probe
/mandatarios	GET	List mandatários (paginated, filterable by UF, partido, cargo)
/mandatarios/{id}	GET	Full mandatário profile
/mandatarios/{id}/sci	GET	SCI score breakdown (total + per-dimension)
/mandatarios/{id}/inconsistencias	GET	Inconsistency cards (paginated, sortable)
/mandatarios/{id}/timeline	GET	Chronological timeline of public acts
/mandatarios/{id}/patrimonio	GET	Wealth evolution across elections
/search	GET	Full-text search by name (PG tsvector)

Architecture

• Routers → Services → DB queries
• app/services/ — business logic layer
• app/schemas/ — Pydantic response schemas (API contract for frontend)
• app/db/ — PostgreSQL (async via asyncpg) + Neo4j (async driver)
• app/config.py — pydantic-settings for env-based config
• app/dependencies.py — FastAPI dependency injection for DB sessions

Key Concerns

• Async all the way (asyncpg + async Neo4j)
• Cursor-based pagination on list endpoints
• Response schemas follow FATO/MÉTRICA/FONTE pattern for inconsistencies
• Read-only API (no write endpoints in MVP)
• Rate limiting (slowapi)
• CORS configured for frontend origin
• OpenAPI docs auto-generated at /docs

Dependencies

• Depends on: pipeline/schemas/ (merged), scoring/ (Front 1) for pre-computed scores
• No direct scoring import at runtime — reads from DB only

Branch

feat/9-fastapi-backend (from develop)