mitchell1972/pinpoint-addressing-api

Verified digital addressing & geocoding API for Nigeria — MVP backend spine (FastAPI + PostGIS, layer-first MVC) # Pinpoint Addressing API Verified digital addresses + geocoding, verification, analytics and an offline-tolerant capture flow for Nigerian logistics, e-commerce and fintech. Scoped from `Pinpoint_Addressing_API_Spec.docx`. A B2B API with three web surfaces (dispatch dashboard, embeddable checkout widget, field-capture PWA), a Python SDK, connector examples, and a Docker/CI-CD setup. ## Stack - **FastAPI** (async) — JSON-Schema contracts + OpenAPI at `/docs`. - **PostGIS** — spatial source of truth; forward match via `pg_trgm` + query cleaning, reverse via KNN. - **psycopg 3** (async pool) + **raw SQL** — no ORM; spatial queries read clearly as SQL. - **pytest + httpx** (real PostGIS, no mocks) and **Playwright** (browser E2E). - **Docker** + a tiny SQL migration runner; **GitHub Actions** gates lint + tests + E2E and publishes the image. ## Architecture Layer-first MVC, one deployable. Request flow: ``` controller (HTTP) -> service (business logic) -> repository (SQL) -> PostGIS schema (Pydantic) = the View / JSON serialization ``` - **Model** → `repositories/` (all SQL) + `db/schema.sql` - **View** → `schemas/` (Pydantic models) - **Controller** → `controllers/` (thin APIRouters) - **+ Service** → `services/` (business logic) ``` src/app/ main.py app factory; routers + middleware + error handlers core/ config · db (async pool) · security · errors · rate_limit lib/ olc · geohash · codes · normalize · scoring · ledger controllers/ addresses · geocode · verify · usage · accounts · imports · analytics · sync · data services/ (one per controller) + auth repositories/ (all SQL) schemas/ (Pydantic DTOs) middleware/ idempotency · metering · audit dependencies/ auth (require_principal / require_admin) web/ dashboard/ · widget/ · capture/ (static surfaces) db/schema.sql canonical schema · db/migrations/ deltas clients/python/ Python SDK · connector …