Quadence

Mobile-first weekly budgeting app. The cycle runs Monday → Sunday (Monday reset); users enter expenses manually or via OCR of receipts; spending is shown against indicative per-category envelopes; a weekly deficit is compensated first from savings, then smoothed across the following weeks.

Status: feature-complete v1 — pure domain → Django/DRF backend → Celery → OCR → Ionic/Angular mobile → self-hosted prod compose. Remaining work is operational (CI, first real deploy, soak test). See docs/roadmap.md.

This repo is orchestrated by a lead Claude session that holds global context, while dev phases/tickets are executed by dedicated agents.

Stack

• Backend: Django 5 / DRF + PostgreSQL + Celery + Redis + MinIO (self-hosted). SimpleJWT + Discord OAuth2 auth (confidential BFF — no mail server). Clean architecture: Views → services → pure domain; services depend on repository Protocols, not the ORM.
• Mobile: Ionic 8 + Angular 22 (zoneless, signals) + Capacitor 8, Android-only in v1.
• OCR: Groq Vision (qwen/qwen3.6-27b, JSON mode) behind a pluggable engine interface.
• Edge: self-hosted MaxMind GeoLite2 country geo-block (France-only by default).

Repository layout

quadence/
├── docs/                      # reference documentation (read docs/README.md first)
├── backend/                   # Django project
│   ├── budget/domain/         #   pure, framework-free calculation engine
│   ├── apps/{accounts,ledger,geoip}/  #   models, services, repositories, mappers, Celery
│   └── config/                #   Django settings + Celery
├── mobile/                    # Ionic + Angular + Capacitor app
│   └── src/{api,auth,core,features,i18n,theme,ui}/
├── docker/                    # Caddyfiles (dev + prod)
├── docker-compose.yml         # full dev stack (primary workflow)
├── docker-compose.prod.yaml   # prod drop-in
└── Makefile

Quick start (dev)

The primary workflow is the full compose stack (not manual ng serve / runserver):

docker compose up -d     # postgres, redis, minio, backend, celery, frontend, caddy
docker compose ps        # check services
make logs                # tail

Caddy is the single entrypoint at http://localhost:80:

URL	Service
http://localhost/	Angular app (HMR)
http://localhost/v1/*	Django/DRF API
http://localhost/admin/	Django admin
http://localhost:9001	MinIO console (quadence / quadence)

Infra-only: make infra (postgres + redis + minio). Backend tests need no infra — pytest auto-applies ENV=test (in-memory SQLite + Celery eager); run them from a host venv:

cd backend && python3.12 -m venv .venv && source .venv/bin/activate && pip install -e ".[dev]"
pytest            # pure domain + integration
python manage.py seed_dev --email you@x.fr   # realistic seed data + a JWT pair

Gotchas and the full runbook (incl. prod deploy + every env var) are in docs/infra/dev-and-deploy.md.

Documentation

See docs/README.md for the reading order. Start with the product overview and the functional workflow; the domain engine holds every calculation rule.