crnjihia/Matumizi-API

A personal finance tracking API built around Kenyan spending habits — mpesa transactions, SACCO contributions, utility bills and groceries. Production-grade with JWT auth, role-based access, and full test coverage. Matumizi API Personal-finance REST API built around Kenyan spending habits M-Pesa transactions · SACCO contributions · Utility bills · Groceries JWT auth · Role-based access · Budget overspend alerts · Webhook integrations --- ## Features - **JWT Authentication** — access tokens (15 min) + rotating refresh tokens (30 days) - **M-Pesa SMS Parsing** — `POST /transactions/parse-sms` extracts structured data from M-Pesa confirmation messages (sent, received, paybill, buy-goods, withdrawal) - **Kenyan-centric Categories** — `MPESA`, `SACCO`, `UTILITIES`, `GROCERIES`, `TRANSPORT`, `RENT`, `ENTERTAINMENT`, `HEALTH`, `EDUCATION` - **Budget Tracking with Overspend Alerts** — set spending limits per category and period; exceeded budgets trigger webhook notifications via Celery - **Role-Based Access Control** — `USER` and `ADMIN` roles with protected endpoints - **Webhook Delivery** — HMAC-SHA256 signed payloads with exponential backoff retries - **Pagination** — all list endpoints support `limit`/`offset` query params - **Async PostgreSQL** — via SQLAlchemy 2.0 async engine (SQLite for local dev/testing) - **Alembic Migrations** — full schema versioning for all 6 tables - **Docker Compose** — API + PostgreSQL + Redis + Celery worker with healthchecks - **CI/CD** — GitHub Actions for lint, type-check, tests, and Docker image publishing with Trivy scanning - **OpenAPI Docs** — interactive Swagger UI at `/docs` and ReDoc at `/redoc` ## Tech Stack | Layer | Technology | |-------|-----------| | Framework | FastAPI | | ORM | SQLAlchemy 2.0 (async) | | Database | PostgreSQL 16 / SQLite (dev) | | Validation | Pydantic v2 | | Migrations | Alembic | | Auth | PyJWT + Passlib (bcrypt) | | Background Tasks | Celery + Redis | | Containerisation | Docker + Docker Compose | | Testing | pytest + httpx (async) | | CI/CD | GitHub Actions | ## Project Structure ``` Matumizi-API/ ├── app/ │ ├── core/ # JWT, security, enums, exceptions │ │ ├── enums. …