# codedrichy/expenso architecture

> Architecture diagram of the GitHub repository codedrichy/expenso, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/codedrichy/expenso
- Repository: https://github.com/codedrichy/expenso

## Overview

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: [`lib/repositories`](https://github.com/codedrichy/expenso/tree/main/lib/repositories) (Repositories), [`lib/main.dart`](https://github.com/codedrichy/expenso/blob/main/lib/main.dart) (App entry), [`lib/services`](https://github.com/codedrichy/expenso/tree/main/lib/services) (Integrations), [`supabase/functions`](https://github.com/codedrichy/expenso/tree/main/supabase/functions) (Edge functions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Flutter client"]
  node_main(("App entry<br/>Flutter bootstrap<br/>[main.dart]"))
  node_auth_ui["Auth flow<br/>screen cluster"]
  node_group_ui["Groups UI<br/>screen cluster"]
  node_expense_ui["Expenses UI<br/>screen cluster"]
  node_settlement_ui["Settlement UI<br/>screen cluster"]
  node_settings_ui["Settings UI<br/>screen cluster"]
  node_repos[("Repositories<br/>client orchestration")]
  node_cycle_repo[("Cycle repo<br/>state coordinator")]
  node_domain["Domain models<br/>entities"]
  node_logic{{"Business logic<br/>pure utils"}}
  node_settle_engine{{"Settlement engine<br/>debt minimizer"}}
  node_services[("Integrations<br/>service layer")]
  node_design_ui["Design system<br/>ui tokens"]
end

subgraph group_backend["Supabase backend"]
  node_supabase_core[("Supabase core<br/>backend platform")]
  node_edge_functions["Edge functions<br/>server actions"]
  node_secure_path{{"Secure path<br/>trust boundary<br/>[index.ts]"}}
end

subgraph group_surfaces["Auxiliary surfaces"]
  node_static_site["Static site<br/>web surface<br/>[index.html]"]
  node_admin_panel["Admin page<br/>web surface<br/>[index.html]"]
  node_docs["Docs archive<br/>architecture memory"]
  node_ci["CI workflows<br/>automation<br/>[workflows]"]
  node_infra["Infra config<br/>deployment<br/>[main.tf]"]
end

node_main -->|"launches"| node_auth_ui
node_main -->|"navigates"| node_group_ui
node_main -->|"navigates"| node_expense_ui
node_main -->|"navigates"| node_settlement_ui
node_main -->|"navigates"| node_settings_ui
node_auth_ui -->|"uses"| node_repos
node_group_ui -->|"uses"| node_repos
node_expense_ui -->|"validates"| node_logic
node_expense_ui -->|"mutates"| node_repos
node_settlement_ui -->|"computes"| node_settle_engine
node_settlement_ui -->|"reads/writes"| node_repos
node_settings_ui -->|"configures"| node_services
node_repos -->|"centralizes"| node_cycle_repo
node_repos -->|"moves data"| node_domain
node_repos -->|"calls"| node_services
node_logic -->|"operates on"| node_domain
node_services -->|"syncs"| node_supabase_core
node_services -->|"invokes"| node_edge_functions
node_secure_path -.->|"guards"| node_services
node_edge_functions -->|"trusts"| node_supabase_core
node_edge_functions -->|"exposes"| node_secure_path
node_supabase_core -->|"persists"| node_cycle_repo
node_docs -.->|"documents"| node_logic
node_ci -->|"builds"| node_main
node_infra -->|"provisions"| node_supabase_core
node_static_site -.->|"supports"| node_services
node_admin_panel -.->|"administers"| node_edge_functions

click node_main "https://github.com/codedrichy/expenso/blob/main/lib/main.dart"
click node_auth_ui "https://github.com/codedrichy/expenso/tree/main/lib/screens/auth"
click node_group_ui "https://github.com/codedrichy/expenso/tree/main/lib/screens/groups"
click node_expense_ui "https://github.com/codedrichy/expenso/tree/main/lib/screens/expenses"
click node_settlement_ui "https://github.com/codedrichy/expenso/tree/main/lib/screens/settlement"
click node_settings_ui "https://github.com/codedrichy/expenso/tree/main/lib/screens/settings"
click node_repos "https://github.com/codedrichy/expenso/tree/main/lib/repositories"
click node_cycle_repo "https://github.com/codedrichy/expenso/blob/main/lib/repositories/cycle_repository.dart"
click node_domain "https://github.com/codedrichy/expenso/tree/main/lib/models"
click node_logic "https://github.com/codedrichy/expenso/tree/main/lib/utils"
click node_settle_engine "https://github.com/codedrichy/expenso/blob/main/lib/utils/settlement_engine.dart"
click node_services "https://github.com/codedrichy/expenso/tree/main/lib/services"
click node_design_ui "https://github.com/codedrichy/expenso/tree/main/lib/design"
click node_supabase_core "https://github.com/codedrichy/expenso/blob/main/supabase/migrations/20260323154308_remote_schema.sql"
click node_edge_functions "https://github.com/codedrichy/expenso/tree/main/supabase/functions"
click node_secure_path "https://github.com/codedrichy/expenso/blob/main/supabase/functions/getUserEncryptionKey/index.ts"
click node_static_site "https://github.com/codedrichy/expenso/blob/main/site/index.html"
click node_admin_panel "https://github.com/codedrichy/expenso/blob/main/admin/index.html"
click node_docs "https://github.com/codedrichy/expenso/tree/main/docs"
click node_ci "https://github.com/codedrichy/expenso/blob/main/.github/workflows"
click node_infra "https://github.com/codedrichy/expenso/blob/main/terraform/main.tf"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_auth_ui,node_group_ui,node_expense_ui,node_settlement_ui,node_settings_ui,node_repos,node_cycle_repo,node_domain,node_logic,node_settle_engine,node_services,node_design_ui toneBlue
class node_supabase_core,node_edge_functions,node_secure_path toneAmber
class node_static_site,node_admin_panel,node_docs,node_ci,node_infra toneMint
```

## Components

### Flutter client

Main app runtime and presentation layer.

- [App entry](https://github.com/codedrichy/expenso/blob/main/lib/main.dart): Flutter bootstrap · Starts the mobile/desktop/web client and wires top-level app state. · `lib/main.dart`
- [Auth flow](https://github.com/codedrichy/expenso/tree/main/lib/screens/auth): screen cluster · Login, onboarding, splash, and initialization error screens. · `lib/screens/auth`
- [Groups UI](https://github.com/codedrichy/expenso/tree/main/lib/screens/groups): screen cluster · Group listing, detail, members, creation, and invitations. · `lib/screens/groups`
- [Expenses UI](https://github.com/codedrichy/expenso/tree/main/lib/screens/expenses): screen cluster · Expense entry and editing screens. · `lib/screens/expenses`
- [Settlement UI](https://github.com/codedrichy/expenso/tree/main/lib/screens/settlement): screen cluster · Cycle history, detail, and settlement confirmation screens. · `lib/screens/settlement`
- [Settings UI](https://github.com/codedrichy/expenso/tree/main/lib/screens/settings): screen cluster · Profile and app settings screens. · `lib/screens/settings`
- [Repositories](https://github.com/codedrichy/expenso/tree/main/lib/repositories): client orchestration · Coordinates screen state, persistence, and backend interactions. · `lib/repositories`
- [Cycle repo](https://github.com/codedrichy/expenso/blob/main/lib/repositories/cycle_repository.dart): state coordinator · Central client-side coordination point for cycle state and mutations. · `lib/repositories/cycle_repository.dart`
- [Domain models](https://github.com/codedrichy/expenso/tree/main/lib/models): entities · Immutable app data structures shared across UI, services, and backend serialization. · `lib/models`
- [Business logic](https://github.com/codedrichy/expenso/tree/main/lib/utils): pure utils · Normalization, validation, revision, money formatting, and settlement math. · `lib/utils`
- [Settlement engine](https://github.com/codedrichy/expenso/blob/main/lib/utils/settlement_engine.dart): debt minimizer · Computes settlement transfers independent of UI and network. · `lib/utils/settlement_engine.dart`
- [Integrations](https://github.com/codedrichy/expenso/tree/main/lib/services): service layer · Side-effectful wrappers for auth, sync, parsing, payments, encryption, and device capabilities. · `lib/services`
- [Design system](https://github.com/codedrichy/expenso/tree/main/lib/design): ui tokens · Theme, colors, spacing, typography, and reusable visual primitives. · `lib/design`

### Supabase backend

Database, auth, realtime, and edge functions.

- [Supabase core](https://github.com/codedrichy/expenso/blob/main/supabase/migrations/20260323154308_remote_schema.sql): backend platform · Postgres, auth, realtime, and storage-backed app backend. · `supabase/migrations/20260323154308_remote_schema.sql`
- [Edge functions](https://github.com/codedrichy/expenso/tree/main/supabase/functions): server actions · Trusted server-side operations for parsing, OCR, payments, encryption keys, admin, and cycle rotation. · `supabase/functions`
- [Secure path](https://github.com/codedrichy/expenso/blob/main/supabase/functions/getUserEncryptionKey/index.ts): trust boundary · 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](https://github.com/codedrichy/expenso/blob/main/site/index.html): web surface · Auxiliary marketing/login pages and scripts separate from the Flutter app. · `site/index.html`
- [Admin page](https://github.com/codedrichy/expenso/blob/main/admin/index.html): web surface · Standalone admin HTML surface. · `admin/index.html`
- [Docs archive](https://github.com/codedrichy/expenso/tree/main/docs): architecture memory · Extensive documentation, audits, and release history. · `docs`
- [CI workflows](https://github.com/codedrichy/expenso/blob/main/.github/workflows): automation · GitHub Actions workflows for build and code scanning. · `.github/workflows`
- [Infra config](https://github.com/codedrichy/expenso/blob/main/terraform/main.tf): deployment · Terraform and platform configuration supporting backend services. · `terraform/main.tf`

## Connections

- 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.
