Skip to content

Developer Guide

Jump to bottom
patilyashh edited this page Aug 6, 2026 · 1 revision

Developer Guide

XPENC is open source (MIT) and welcomes contributions. This page is a quick orientation; the authoritative documents live in the repo.

Read first: structure.md — the full design doc: mental model, data model, every decision and why it was made, plus an adversarial audit that hardened the app's invariants.

Tech stack

Concern Choice
Framework Flutter 3.38.9 · Dart 3.10.8
State Riverpod
Database Drift (SQLite), local-first, reactive queries
Routing go_router
Charts fl_chart
Notifications flutter_local_notifications + timezone

⚠️ Several packages are deliberately pinned — drift/drift_dev/ drift_flutter/sqlite3_flutter_libs at 2.31.0/0.2.8/0.5.24, and flutter_riverpod at 2.6.1. drift ≥ 2.32 silently drops libsqlite3.so from Android release builds — a real crash that once shipped. riverpod 3.x forces a Dart SDK too new for drift_dev here. Don't bump these without reading the "Pinned dependencies" section of CONTRIBUTING.md.

Project structure

lib/
  core/          theme, Money type, branding, notifications
  data/          drift database, tables, DAOs, seed data
  domain/        entities, repository interfaces
  features/      one folder per screen (dashboard, transactions, budgets, …)
website/         landing page (Vercel)
tool/            icon generator, APK verification gate
.github/         CI + release workflows, issue & PR templates
docs/            releasing / maintainer docs

Building from source

git clone https://github.com/PATILYASHH/XPENC.git
cd XPENC
flutter pub get
flutter run

Tests

rm -rf build/native_assets   # Windows only: Flutter native-assets bug
flutter analyze
flutter test

Widget tests render every screen against a real in-memory database at a real phone size (360 × 800 dp) and fail on layout overflows — catching what flutter analyze can't. test/branding_test.dart fails the build if AppInfo.version ever drifts from the version: line in pubspec.yaml.

Shipping an APK

flutter build apk --release --split-per-abi
bash tool/verify_apk.sh build/app/outputs/flutter-apk/app-arm64-v8a-release.apk

verify_apk.sh must pass — it's the only check that catches a release APK shipping with no libsqlite3.so, a failure no unit test can see because every test overrides the database with an in-memory one.

Code generation (Drift)

After changing any table in lib/data/tables.dart:

dart run build_runner build --force-jit --delete-conflicting-outputs

--force-jit is required — without it, build_runner fails with 'dart compile' does not support build hooks on this SDK.

Changing the database schema

  1. Edit lib/data/tables.dart.
  2. Bump schemaVersion in lib/data/database.dart.
  3. Add the onUpgrade migration step.
  4. Regenerate (above).
  5. Verify old backups still restore — importAll skips unknown columns; add a test.

The invariants that keep the money honest

Not preferences — most are guarded by tests, and PRs that break them won't be merged:

  1. Amounts are integer paise/cents. Never double. ₹12.50 is stored as 1250.
  2. Net worth = Σ account balances. Transfers keep it unchanged; income raises it; expense lowers it.
  3. Transfers and person (due/owe) movements are neither income nor expense — they must never appear in budgets or income/expense reports.
  4. Debit cards & UPI are linked instruments, not accounts. They spend their bank's money and hold no balance of their own, or rupees get counted twice.
  5. Auto-Approve only fires from a learned rule (exact match), never a fresh guess — and Undo must reverse the posted transaction, not just hide the card.
  6. Nothing auto-posts silently. Cash Reminders and recurring rules always confirm with, or flag for review by, the user.
  7. SMS never leaves the device. All parsing is on-device, no network calls.

Contributing

You want to… Start here
Report a bug Bug report
Request a feature Feature request
Add SMS support for your bank ⭐ Bank support request — the most valuable "good first issue"
Improve docs / website PRs welcome, no issue needed
Fix a bug / build a feature Comment on the issue first so work isn't duplicated

PR checklist, commit conventions and the full "adding a bank SMS template" walkthrough are in CONTRIBUTING.md. Releases are cut by maintainers pushing a v* tag — see docs/RELEASING.md. Participation is governed by the Code of Conduct.

See also

Home

Using XPENC

Project

Elsewhere

Clone this wiki locally