Architecture Overview
High-Level Design
Design Principles
-
Offline-first -- The mobile app functions fully without internet for core features (expense tracking, budget viewing, manual entry). The device SQLite database is the source of truth.
-
Sync-optional -- Users opt in to server sync. When enabled, data is end-to-end encrypted before leaving the device.
-
AI as enhancement -- Core functionality works without AI. AI features (receipt parsing, agent chat) require connectivity but degrade gracefully.
-
Low data usage -- Minimize payload sizes. Compress images before upload. Paginate API responses.
-
Simple infrastructure -- Single Django server is sufficient for the target scale. No premature scaling or task queues.
Technology Stack
Backend
| Layer | Technology |
|---|---|
| Framework | Django 5.2 + DRF |
| Language | Python 3.12+ (managed with uv) |
| Database | PostgreSQL 16 (Docker) or SQLite (local dev) |
| Auth | SimpleJWT (15-min access, 30-day refresh tokens) |
| OCR | EasyOCR |
| AI | OpenAI GPT-4o (function calling + vision) |
| Encryption | PyNaCl (libsodium bindings) |
| API Docs | drf-spectacular (OpenAPI 3.0) |
| Testing | pytest + pytest-django |
Mobile Client
| Layer | Technology |
|---|---|
| Framework | React Native 0.76 + Expo 52 |
| Language | TypeScript (strict) |
| Local DB | Drizzle ORM + expo-sqlite |
| UI State | Zustand |
| Server State | React Query + react-query-kit |
| Styling | NativeWind (Tailwind CSS) |
| Forms | react-hook-form + Zod |
| Encryption | tweetnacl + expo-secure-store |
| Networking | Axios with JWT interceptors |
| Testing | Jest + React Testing Library |
Infrastructure
| Component | Technology |
|---|---|
| Containerization | Docker + Docker Compose |
| Database | PostgreSQL 16 (Docker volume) |
| CI/CD | GitHub Actions |
| Task Runner | just (Justfile) |
| Monorepo | pnpm workspaces |