How codedrichy/expenso works
1. Overall shape
Expenso is a Flutter client application backed by Supabase, with a small set of TypeScript edge functions and a few static auxiliary web pages. The main runtime is the Flutter app under lib/, while backend responsibilities are split between Supabase Postgres/Auth/Realtime and supabase/functions/.
2. Primary UI entry and platform shells
The app starts in lib/main.dart and is packaged for Android, iOS, web, macOS, Linux, and Windows. The native platform folders are mostly standard Flutter host shells; they matter for deployment, not business logic.
3. Feature-oriented screen layer
UI is organized by feature in lib/screens/: auth, groups, expenses, settlement, and settings. These screens are the presentation boundary and should be treated as thin consumers of repositories/services rather than direct data access points.
4. Repository layer as the client-side backbone
lib/repositories/ is the main orchestration layer. CycleRepository is the central state and data coordination point, with adjacent repositories for auth, groups, cycles, and settlement. The repository layer mediates between UI and all network/storage side effects.
5. Domain model boundary
lib/models/ holds the immutable entities that flow through the app: expense, group, cycle, member, invitations, settlements, payment attempts, system messages, and normalized expense structures. These models are the shared contract between screens, repositories, utilities, and backend serialization.
6. Pure business logic and calculations
lib/utils/ contains the non-UI logic that should remain backend-agnostic: settlement math, expense normalization/revision/validation, money formatting, route arguments, and ID helpers. SettlementEngine is especially important for diagramming because it drives debt minimization and settlement outputs independently of the UI.
7. External-service wrappers
lib/services/ contains the side-effectful integrations: Supabase access, auth/profile/identity, connectivity, theme/locale, sync status, pinned groups/cache, encryption, FCM token handling, Groq expense parsing, OCR scanning, Razorpay order creation, and UPI payment launching. This is the layer that connects the app to third-party systems and device capabilities.
8. Main data flows
The key product flow is: user input in a screen or widget → parsing/validation/normalization utilities and services → repository mutation → Supabase persistence/realtime sync → UI refresh. For settlement, the flow is: cycle state → settlement engine → settlement repository and/or backend function → archived/restarted cycle state. The app also uses optimistic UI and sync indicators to mask network latency.
9. Backend functions and secure operations
supabase/functions/ contains the server-side actions that are too sensitive or atomic for the client: Groq parsing proxy, OCR proxy, Razorpay order creation, encryption-key retrieval, admin API, and the settleAndRestart cycle rotation flow. supabase/migrations/ defines the database schema that those client and function paths operate against. This is the main trust boundary for authenticated data and key handling.
10. Security and encryption boundary
The presence of data_encryption_service, getUserEncryptionKey, and getGroupEncryptionKey indicates optional at-rest encryption for sensitive group data. In an architecture diagram, this should be shown as a separate secure path spanning Flutter client, Supabase auth, and edge functions rather than as ordinary CRUD.
11. Design system and reusable UI primitives
lib/design/ and lib/widgets/ define the app’s reusable visual system: colors, spacing, typography, theme tokens, animated cards, loaders, banners, sheets, avatars, charts, and empty/error states. These are shared presentation components used across the feature screens to keep the premium UI consistent.
12. Auxiliary surfaces and documentation
site/ and admin/ are static web surfaces separate from the main Flutter app. docs/ is unusually extensive and acts as an architectural memory and release history, while test/, integration_test/, and tool/ provide verification and parser-training utilities. CI is handled by GitHub Actions (build.yml, codeql.yml), and terraform/ suggests additional infrastructure management, likely for supporting cloud services such as messaging.
Main entry points: repositories Repositories · main.dart App entry · services Integrations · functions Edge functions
Components 21
Flutter client
Main app runtime and presentation layer.
- App entry · Starts the mobile/desktop/web client and wires top-level app state.
lib/main.dart - Auth flow · Login, onboarding, splash, and initialization error screens.
lib/screens/auth - Groups UI · Group listing, detail, members, creation, and invitations.
lib/screens/groups - Expenses UI · Expense entry and editing screens.
lib/screens/expenses - Settlement UI · Cycle history, detail, and settlement confirmation screens.
lib/screens/settlement - Settings UI · Profile and app settings screens.
lib/screens/settings - Repositories · Coordinates screen state, persistence, and backend interactions.
lib/repositories - Cycle repo · Central client-side coordination point for cycle state and mutations.
lib/repositories/cycle_repository.dart - Domain models · Immutable app data structures shared across UI, services, and backend serialization.
lib/models - Business logic · Normalization, validation, revision, money formatting, and settlement math.
lib/utils - Settlement engine · Computes settlement transfers independent of UI and network.
lib/utils/settlement_engine.dart - Integrations · Side-effectful wrappers for auth, sync, parsing, payments, encryption, and device capabilities.
lib/services - Design system · Theme, colors, spacing, typography, and reusable visual primitives.
lib/design
Supabase backend
Database, auth, realtime, and edge functions.
- Supabase core · Postgres, auth, realtime, and storage-backed app backend.
supabase/migrations/20260323154308_remote_schema.sql - Edge functions · Trusted server-side operations for parsing, OCR, payments, encryption keys, admin, and cycle rotation.
supabase/functions - Secure path · Encryption-key and sensitive-data flow spanning client auth and trusted functions.
supabase/functions/getUserEncryptionKey/index.ts
Auxiliary surfaces
Static web surfaces, docs, and supporting tooling.
- Static site · Auxiliary marketing/login pages and scripts separate from the Flutter app.
site/index.html - Admin page · Standalone admin HTML surface.
admin/index.html - Docs archive · Extensive documentation, audits, and release history.
docs - CI workflows · GitHub Actions workflows for build and code scanning.
.github/workflows - Infra config · Terraform and platform configuration supporting backend services.
terraform/main.tf
Connections 27
- App entry → Auth flow: launches · App entry routes into auth and shell screens.
- App entry → Groups UI: navigates · Primary app shell reaches group-centric screens.
- App entry → Expenses UI: navigates · Main flow includes expense capture and editing.
- App entry → Settlement UI: navigates · Main flow includes settlement review and confirmation.
- App entry → Settings UI: navigates · Main flow exposes profile and settings.
- Auth flow → Repositories: uses · Auth screens delegate state and persistence to repositories.
- Groups UI → Repositories: uses · Group screens consume repository-backed state.
- Expenses UI → Business logic: validates · Expense input is normalized and validated before mutation.
- Expenses UI → Repositories: mutates · Expense screens persist changes through repositories.
- Settlement UI → Settlement engine: computes · Settlement views depend on debt minimization logic.
- Settlement UI → Repositories: reads/writes · Settlement screens coordinate with repository state.
- Settings UI → Integrations: configures · Settings update profile, locale, theme, and connectivity-adjacent services.
- Repositories → Cycle repo: centralizes · Cycle repository is the main coordination backbone.
- Repositories → Domain models: moves data · Repositories transform domain entities between UI and persistence.
- Repositories → Integrations: calls · Repositories depend on service wrappers for side effects.
- Business logic → Domain models: operates on · Pure utilities work on shared model types.
- Integrations → Supabase core: syncs · Client services connect to Supabase auth, realtime, and storage.
- Integrations → Edge functions: invokes · Sensitive and heavy operations are proxied through functions.
- Secure path → Integrations: guards · Encryption-key and sensitive-data services rely on trusted access paths.
- Edge functions → Supabase core: trusts · Edge functions execute against the Supabase backend.
- Edge functions → Secure path: exposes · Encryption key retrieval and secure operations are served here.
- Supabase core → Cycle repo: persists · Backend persistence and realtime drive cycle state.
- Docs archive → Business logic: documents · Architecture docs capture the app's business rules and calculations.
- CI workflows → App entry: builds · CI validates the Flutter application and supporting checks.
- Infra config → Supabase core: provisions · Infrastructure config supports backend dependencies and deployment.
- Static site → Integrations: supports · Auxiliary pages complement the main client and backend services.
- Admin page → Edge functions: administers · Admin surface likely depends on trusted server-side actions.