MicoFaith/AHO

a Rwanda-focused digital addressing and delivery platform that gives people a simple digital identity for their physical location. # AHO **A shareable digital address layer for Rwanda** — the simplest way to share where you are. AHO turns a physical location into a persistent, shareable identity: a short code + a map point + the "last-100-metres" details (landmark, gate, floor, instructions) that people actually use to find you. Anyone can open a shared AHO from a link or QR — no app required. > Positioning note: AHO is not a delivery network (that space is served by > ePoBox/MPost). It focuses on the *sharing* and *privacy* engineering problem. > See `docs/DECISIONS.md` (ADR-0008). ## Status **Phase 1 complete — architecture, database, repository foundation.** No product features yet; this is the tested skeleton the MVP is built on. What works today (all verified, see "Testing"): - FastAPI app with `/health` and `/health/db` (the latter proves PostGIS is reachable). - PostgreSQL + PostGIS schema (`users`, `addresses`) via a hand-written Alembic migration. - `Address.location` stored as `geography(Point, 4326)` with a GiST index. - Opaque, checksum'd AHO code generator (`AHO-7QX4M2C`). - 11 passing tests, including DB-enforced code uniqueness and geography-in-metres distance. ## Tech stack | Layer | Choice | |---|---| | Web (Phase 2+) | Next.js, TypeScript, Tailwind, shadcn/ui, MapLibre GL | | API | FastAPI, Pydantic, SQLAlchemy 2.0, Alembic | | Database | PostgreSQL + PostGIS | | Auth (Phase 3) | Self-built JWT (access + refresh), role-based | | Deploy (Phase 12) | Vercel (web) + Railway (api) + managed Postgres/PostGIS | Architecture: **monorepo + modular monolith**. Rationale in `docs/DECISIONS.md`. ## Repository layout ``` aho/ apps/ api/ # FastAPI backend (this phase) web/ # Next.js frontend (Phase 2) docs/ # PRD, ADRs docker-compose.yml ``` ## Run it ### Option A — Docker (one command) ```bash cp .env.example .env docker compose up --build # API on localhost (runs `alembic upgrade head` on start) ``` ### Option B — Local (Postgres/PostGIS al …