# mustaphi-dev/subscription-tracker architecture

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

- Interactive diagram: https://gitdiagram.com/mustaphi-dev/subscription-tracker
- Repository: https://github.com/mustaphi-dev/subscription-tracker

## Overview

Wince is a Flutter app for tracking subscriptions, free trials, BNPL installments and bank balances, backed by Supabase. Users can enter or import billing items, link a bank for balance and transaction-based discovery, then monitor renewals, trial conversions and upcoming account shortfalls. Receipt parsing also accepts forwarded email, while scheduled backend functions send alerts and refresh exchange rates. The app’s UI and several backend branches are represented from README capabilities and repository paths; their internal calls are not shown in the excerpts, so those links are left unverified.

Main entry points: [`supabase/functions/bank-sync/index.ts`](https://github.com/mustaphi-dev/subscription-tracker/blob/main/supabase/functions/bank-sync/index.ts) (Bank sync), [`lib/home.dart`](https://github.com/mustaphi-dev/subscription-tracker/blob/main/lib/home.dart) (Overview), [`supabase/functions/parse-trial-receipt/index.ts`](https://github.com/mustaphi-dev/subscription-tracker/blob/main/supabase/functions/parse-trial-receipt/index.ts) (Receipt parsing), [`supabase/migrations/20261104000000_init.sql`](https://github.com/mustaphi-dev/subscription-tracker/blob/main/supabase/migrations/20261104000000_init.sql) (Supabase database)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Mobile app"]
  node_app_shell["App shell<br/>[main.dart]"]
  node_dashboard["Overview<br/>[home.dart]"]
  node_bank_ui["Bank linking UI<br/>[accounts.dart]"]
end

subgraph group_tracking["Billing tracking"]
  node_item_entry["Item entry<br/>[add.dart]"]
  node_item_data["Financial items<br/>[data.dart]"]
  node_renewals["Renewals calendar<br/>[calendar.dart]"]
  node_insights["Spending insights<br/>[insights.dart]"]
end

subgraph group_backend["Supabase backend"]
  node_bank_sync["Bank sync<br/>[index.ts]"]
  node_bank_tokens["Encrypted bank tokens<br/>[tokens.ts]"]
  node_transaction_detection["Recurring detection<br/>[detect.ts]"]
  node_receipt_parse["Receipt parsing<br/>[index.ts]"]
  node_alerts["Alert dispatch<br/>[index.ts]"]
  node_fx_sync["FX rate sync<br/>[index.ts]"]
  node_shared["Backend shared services<br/>[mod.ts]"]
  node_database[("Supabase database")]
end

subgraph group_integrations["External integrations"]
  node_bank_provider["TrueLayer adapter<br/>[truelayer.ts]"]
  node_email_worker["Inbound email worker<br/>[index.js]"]
  node_anthropic["Anthropic Claude"]
  node_truelayer_service["TrueLayer API"]
  node_push_service["Firebase Cloud Messaging"]
end

node_user(("Wince user"))

node_user -.->|"uses"| node_app_shell
node_app_shell -.->|"opens"| node_dashboard
node_user -.->|"records items"| node_item_entry
node_item_entry -.->|"saves items"| node_item_data
node_dashboard -.->|"displays items"| node_item_data
node_dashboard -.->|"shows renewals"| node_renewals
node_dashboard -.->|"shows insights"| node_insights
node_user -.->|"links bank"| node_bank_ui
node_bank_ui -.->|"requests sync"| node_bank_sync
node_bank_sync -->|"calls provider"| node_bank_provider
node_bank_provider -->|"stores tokens"| node_bank_tokens
node_bank_sync -->|"uses token store"| node_bank_tokens
node_bank_sync -->|"detects recurrence"| node_transaction_detection
node_bank_sync -->|"reads and writes"| node_database
node_bank_provider -->|"fetches bank data"| node_truelayer_service
node_bank_tokens -->|"stores encrypted tokens"| node_database
node_email_worker -->|"posts receipt"| node_receipt_parse
node_user -.->|"submits receipt"| node_receipt_parse
node_receipt_parse -->|"extracts billing data"| node_anthropic
node_receipt_parse -->|"records item"| node_database
node_alerts -->|"queries and claims alerts"| node_database
node_alerts -->|"sends push"| node_shared
node_shared -->|"delivers notification"| node_push_service
node_fx_sync -->|"uses backend services"| node_shared
node_alerts -.->|"notifies"| node_user

click node_app_shell "https://github.com/mustaphi-dev/subscription-tracker/blob/main/lib/main.dart"
click node_dashboard "https://github.com/mustaphi-dev/subscription-tracker/blob/main/lib/home.dart"
click node_item_entry "https://github.com/mustaphi-dev/subscription-tracker/blob/main/lib/add.dart"
click node_item_data "https://github.com/mustaphi-dev/subscription-tracker/blob/main/lib/data.dart"
click node_renewals "https://github.com/mustaphi-dev/subscription-tracker/blob/main/lib/calendar.dart"
click node_insights "https://github.com/mustaphi-dev/subscription-tracker/blob/main/lib/insights.dart"
click node_bank_ui "https://github.com/mustaphi-dev/subscription-tracker/blob/main/lib/accounts.dart"
click node_bank_sync "https://github.com/mustaphi-dev/subscription-tracker/blob/main/supabase/functions/bank-sync/index.ts"
click node_bank_provider "https://github.com/mustaphi-dev/subscription-tracker/blob/main/supabase/functions/bank-sync/aggregators/truelayer.ts"
click node_bank_tokens "https://github.com/mustaphi-dev/subscription-tracker/blob/main/supabase/functions/bank-sync/tokens.ts"
click node_transaction_detection "https://github.com/mustaphi-dev/subscription-tracker/blob/main/supabase/functions/bank-sync/detect.ts"
click node_receipt_parse "https://github.com/mustaphi-dev/subscription-tracker/blob/main/supabase/functions/parse-trial-receipt/index.ts"
click node_email_worker "https://github.com/mustaphi-dev/subscription-tracker/blob/main/workers/inbound-email/index.js"
click node_alerts "https://github.com/mustaphi-dev/subscription-tracker/blob/main/supabase/functions/dispatch-alerts/index.ts"
click node_fx_sync "https://github.com/mustaphi-dev/subscription-tracker/blob/main/supabase/functions/fx-sync/index.ts"
click node_shared "https://github.com/mustaphi-dev/subscription-tracker/blob/main/supabase/functions/_shared/mod.ts"
click node_database "https://github.com/mustaphi-dev/subscription-tracker/blob/main/supabase/migrations/20261104000000_init.sql"

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_app_shell,node_dashboard,node_bank_ui,node_user toneBlue
class node_item_entry,node_item_data,node_renewals,node_insights toneAmber
class node_bank_sync,node_bank_tokens,node_transaction_detection,node_receipt_parse,node_alerts,node_fx_sync,node_shared,node_database toneMint
class node_bank_provider,node_email_worker,node_anthropic,node_truelayer_service,node_push_service toneRose
```

## Components

### Mobile app

- [App shell](https://github.com/mustaphi-dev/subscription-tracker/blob/main/lib/main.dart): `lib/main.dart`
- [Overview](https://github.com/mustaphi-dev/subscription-tracker/blob/main/lib/home.dart): `lib/home.dart`
- [Bank linking UI](https://github.com/mustaphi-dev/subscription-tracker/blob/main/lib/accounts.dart): `lib/accounts.dart`

### Billing tracking

- [Item entry](https://github.com/mustaphi-dev/subscription-tracker/blob/main/lib/add.dart): `lib/add.dart`
- [Financial items](https://github.com/mustaphi-dev/subscription-tracker/blob/main/lib/data.dart): `lib/data.dart`
- [Renewals calendar](https://github.com/mustaphi-dev/subscription-tracker/blob/main/lib/calendar.dart): `lib/calendar.dart`
- [Spending insights](https://github.com/mustaphi-dev/subscription-tracker/blob/main/lib/insights.dart): `lib/insights.dart`

### Supabase backend

- [Bank sync](https://github.com/mustaphi-dev/subscription-tracker/blob/main/supabase/functions/bank-sync/index.ts): `supabase/functions/bank-sync/index.ts`
- [Encrypted bank tokens](https://github.com/mustaphi-dev/subscription-tracker/blob/main/supabase/functions/bank-sync/tokens.ts): `supabase/functions/bank-sync/tokens.ts`
- [Recurring detection](https://github.com/mustaphi-dev/subscription-tracker/blob/main/supabase/functions/bank-sync/detect.ts): `supabase/functions/bank-sync/detect.ts`
- [Receipt parsing](https://github.com/mustaphi-dev/subscription-tracker/blob/main/supabase/functions/parse-trial-receipt/index.ts): `supabase/functions/parse-trial-receipt/index.ts`
- [Alert dispatch](https://github.com/mustaphi-dev/subscription-tracker/blob/main/supabase/functions/dispatch-alerts/index.ts): `supabase/functions/dispatch-alerts/index.ts`
- [FX rate sync](https://github.com/mustaphi-dev/subscription-tracker/blob/main/supabase/functions/fx-sync/index.ts): `supabase/functions/fx-sync/index.ts`
- [Backend shared services](https://github.com/mustaphi-dev/subscription-tracker/blob/main/supabase/functions/_shared/mod.ts): `supabase/functions/_shared/mod.ts`
- [Supabase database](https://github.com/mustaphi-dev/subscription-tracker/blob/main/supabase/migrations/20261104000000_init.sql): `supabase/migrations/20261104000000_init.sql`

### External integrations

- [TrueLayer adapter](https://github.com/mustaphi-dev/subscription-tracker/blob/main/supabase/functions/bank-sync/aggregators/truelayer.ts): `supabase/functions/bank-sync/aggregators/truelayer.ts`
- [Inbound email worker](https://github.com/mustaphi-dev/subscription-tracker/blob/main/workers/inbound-email/index.js): `workers/inbound-email/index.js`
- **Anthropic Claude**
- **TrueLayer API**
- **Firebase Cloud Messaging**

### Other components

- **Wince user**

## Connections

- Wince user → App shell: uses
- App shell → Overview: opens
- Wince user → Item entry: records items
- Item entry → Financial items: saves items
- Overview → Financial items: displays items
- Overview → Renewals calendar: shows renewals
- Overview → Spending insights: shows insights
- Wince user → Bank linking UI: links bank
- Bank linking UI → Bank sync: requests sync
- Bank sync → TrueLayer adapter: calls provider (evidence: `supabase/functions/bank-sync/index.ts`)
- TrueLayer adapter → Encrypted bank tokens: stores tokens (evidence: `supabase/functions/bank-sync/aggregators/truelayer.ts`)
- Bank sync → Encrypted bank tokens: uses token store (evidence: `supabase/functions/bank-sync/index.ts`)
- Bank sync → Recurring detection: detects recurrence (evidence: `supabase/functions/bank-sync/index.ts`)
- Bank sync → Supabase database: reads and writes (evidence: `supabase/functions/bank-sync/index.ts`)
- TrueLayer adapter → TrueLayer API: fetches bank data (evidence: `supabase/functions/bank-sync/aggregators/truelayer.ts`)
- Encrypted bank tokens → Supabase database: stores encrypted tokens (evidence: `supabase/functions/bank-sync/tokens.ts`)
- Inbound email worker → Receipt parsing: posts receipt (evidence: `workers/inbound-email/index.js`)
- Wince user → Receipt parsing: submits receipt
- Receipt parsing → Anthropic Claude: extracts billing data (evidence: `supabase/functions/parse-trial-receipt/index.ts`)
- Receipt parsing → Supabase database: records item (evidence: `supabase/functions/parse-trial-receipt/index.ts`)
- Alert dispatch → Supabase database: queries and claims alerts (evidence: `supabase/functions/dispatch-alerts/index.ts`)
- Alert dispatch → Backend shared services: sends push (evidence: `supabase/functions/dispatch-alerts/index.ts`)
- Backend shared services → Firebase Cloud Messaging: delivers notification (evidence: `supabase/functions/_shared/mod.ts`)
- FX rate sync → Backend shared services: uses backend services (evidence: `supabase/functions/fx-sync/index.ts`)
- Alert dispatch → Wince user: notifies