# hamsathumar/ai-powered-expense-tracker architecture

> Architecture diagram of the GitHub repository hamsathumar/ai-powered-expense-tracker, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hamsathumar/ai-powered-expense-tracker
- Repository: https://github.com/hamsathumar/ai-powered-expense-tracker

## Overview

#### Purpose and runtime
A local-first personal expense tracker for accounts, transactions, categories, people/shared expenses, recurring payments, reports, backup, and voice entry. It is an Expo/React Native TypeScript app, runnable on Android, iOS, web, and Expo Go. Primary startup/routing is Expo Router’s file-based route tree under `src/app/`, rooted at `src/app/_layout.tsx`.

#### Navigation and screen composition
The application shell establishes shared providers and navigation, while the tab layout is the primary user entry point. Main areas are dashboard, accounts, reports, and settings; stack routes cover create/detail/edit flows.
- `src/app/_layout.tsx`
- `src/app/(tabs)/_layout.tsx`
- `src/app/(tabs)/index.tsx`
- `src/app/transaction/new.tsx`
- `src/app/account/[id].tsx`

#### Persistence boundary
`src/db/` is the persistence layer and should be the exclusive boundary between screens/services and stored financial data. Database initialization, migrations, seed data, and backup logic are separated from entity-specific query modules.
- `src/db/client.ts`
- `src/db/migrations.ts`
- `src/db/queries/transactions.ts`
- `src/db/backup.ts`

#### Financial domain logic
`src/domain/` holds pure business rules and typed models, separate from React UI and database access. It covers money handling, transaction/account activity, recurring schedules, expense splitting, settlements, and backup-format validation—logic that must remain deterministic and reusable across screens and persistence operations.
- `src/domain/types.ts`
- `src/domain/money.ts`
- `src/domain/billSplit.ts`
- `src/domain/recurring.ts`
- `src/domain/settlement.ts`

#### Transaction and account workflows
Transaction creation/editing is composed from reusable financial input components and persists through transaction/account/category/people query boundaries. Account and category routes provide management/detail flows; account activity is calculated by domain logic rather than embedded in presentation.
- `src/components/TransactionForm.tsx`
- `src/app/transaction/[id].tsx`
- `src/db/queries/accounts.ts`
- `src/db/queries/categories.ts`
- `src/db/queries/people.ts`

#### Shared expenses, recurring items, and reporting
People, bill splitting, and settle-up form a shared-expense workflow. Recurring items have dedicated list, detail, edit, payment, display, and query layers. Reports obtain persisted aggregates through a distinct query module and render visual summaries such as donut charts.
- `src/app/bill-split.tsx`
- `src/app/settle-up.tsx`
- `src/app/recurring/[id]/payments.tsx`
- `src/db/queries/recurring.ts`
- `src/db/queries/reports.ts`

#### Voice AI, files, and app-wide presentation state
Voice capture routes through an AI boundary that builds prompts, calls Gemini, validates parsed output, and protects configuration; parsed results should feed normal transaction workflows rather than bypassing domain validation. Backup-file and profile-photo services isolate device/file operations. Theme and currency contexts provide app-wide display configuration, while pending-count state supports queued work indicators.
- `src/app/voice.tsx`
- `src/ai/gemini.ts`
- `src/ai/parseVoice.ts`
- `src/ai/validate.ts`
- `src/services/backupFile.ts`
- `src/theme/CurrencyContext.tsx`

Main entry points: [`src/domain/money.ts`](https://github.com/hamsathumar/ai-powered-expense-tracker/blob/main/src/domain/money.ts) (Financial rules), [`src/db/client.ts`](https://github.com/hamsathumar/ai-powered-expense-tracker/blob/main/src/db/client.ts) (Database lifecycle), [`src/app/(tabs)/_layout.tsx`](https://github.com/hamsathumar/ai-powered-expense-tracker/blob/main/src/app/(tabs)/_layout.tsx) (Main tabs), [`src/components/TransactionForm.tsx`](https://github.com/hamsathumar/ai-powered-expense-tracker/blob/main/src/components/TransactionForm.tsx) (Transaction form)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["App UI"]
  node_root_layout["App shell<br/>Expo Router layout<br/>[_layout.tsx]"]
  node_tabs_layout["Main tabs<br/>tab layout<br/>[_layout.tsx]"]
  node_dashboard["Dashboard<br/>screen<br/>[index.tsx]"]
  node_transaction_routes["Transaction flows<br/>create/detail screens<br/>[new.tsx]"]
  node_account_detail["Account detail<br/>screen<br/>[&#91;id&#93;.tsx]"]
  node_shared_expenses["Shared expenses<br/>split and settle screens<br/>[bill-split.tsx]"]
  node_recurring_payments["Recurring payments<br/>screen<br/>[payments.tsx]"]
  node_voice_screen["Voice entry<br/>screen<br/>[voice.tsx]"]
  node_currency_context["Currency display<br/>app context"]
end

subgraph group_logic["Domain &amp; workflows"]
  node_transaction_form["Transaction form<br/>UI component"]
  node_financial_domain{{"Financial rules<br/>pure domain logic<br/>[money.ts]"}}
  node_domain_models["Domain models<br/>typed models<br/>[types.ts]"]
end

subgraph group_data["Persistence"]
  node_database_client[("Database lifecycle<br/>client and migrations<br/>[client.ts]")]
  node_transaction_queries[("Transaction queries<br/>query module<br/>[transactions.ts]")]
  node_account_queries[("Account queries<br/>query module<br/>[accounts.ts]")]
  node_recurring_queries[("Recurring queries<br/>query module<br/>[recurring.ts]")]
  node_report_queries[("Report aggregates<br/>query module<br/>[reports.ts]")]
end

subgraph group_integration["Device &amp; AI"]
  node_backup_service["Backup and files<br/>file service<br/>[backupFile.ts]"]
  node_voice_ai{{"Voice parsing AI<br/>Gemini integration<br/>[parseVoice.ts]"}}
end

node_root_layout -->|"hosts"| node_tabs_layout
node_root_layout -->|"provides"| node_currency_context
node_tabs_layout -->|"opens"| node_dashboard
node_tabs_layout -->|"navigates to"| node_account_detail
node_tabs_layout -->|"navigates to"| node_transaction_routes
node_transaction_routes -->|"composes"| node_transaction_form
node_transaction_form -->|"applies rules"| node_financial_domain
node_financial_domain -->|"uses"| node_domain_models
node_transaction_form -->|"persists through"| node_transaction_queries
node_account_detail -->|"loads activity"| node_account_queries
node_account_detail -->|"calculates activity with"| node_financial_domain
node_shared_expenses -->|"splits and settles with"| node_financial_domain
node_shared_expenses -->|"uses people data"| node_account_queries
node_recurring_payments -->|"reads and records"| node_recurring_queries
node_recurring_payments -->|"evaluates schedules"| node_financial_domain
node_dashboard -->|"reads summaries"| node_report_queries
node_voice_screen -->|"submits capture"| node_voice_ai
node_voice_ai -->|"returns validated draft"| node_transaction_form
node_transaction_queries -->|"uses"| node_database_client
node_account_queries -->|"uses"| node_database_client
node_recurring_queries -->|"uses"| node_database_client
node_report_queries -->|"uses"| node_database_client
node_backup_service -->|"backs up and restores"| node_database_client

click node_root_layout "https://github.com/hamsathumar/ai-powered-expense-tracker/blob/main/src/app/_layout.tsx"
click node_tabs_layout "https://github.com/hamsathumar/ai-powered-expense-tracker/blob/main/src/app/(tabs)/_layout.tsx"
click node_dashboard "https://github.com/hamsathumar/ai-powered-expense-tracker/blob/main/src/app/(tabs)/index.tsx"
click node_transaction_routes "https://github.com/hamsathumar/ai-powered-expense-tracker/blob/main/src/app/transaction/new.tsx"
click node_account_detail "https://github.com/hamsathumar/ai-powered-expense-tracker/blob/main/src/app/account/%5Bid%5D.tsx"
click node_shared_expenses "https://github.com/hamsathumar/ai-powered-expense-tracker/blob/main/src/app/bill-split.tsx"
click node_recurring_payments "https://github.com/hamsathumar/ai-powered-expense-tracker/blob/main/src/app/recurring/%5Bid%5D/payments.tsx"
click node_voice_screen "https://github.com/hamsathumar/ai-powered-expense-tracker/blob/main/src/app/voice.tsx"
click node_transaction_form "https://github.com/hamsathumar/ai-powered-expense-tracker/blob/main/src/components/TransactionForm.tsx"
click node_financial_domain "https://github.com/hamsathumar/ai-powered-expense-tracker/blob/main/src/domain/money.ts"
click node_domain_models "https://github.com/hamsathumar/ai-powered-expense-tracker/blob/main/src/domain/types.ts"
click node_database_client "https://github.com/hamsathumar/ai-powered-expense-tracker/blob/main/src/db/client.ts"
click node_transaction_queries "https://github.com/hamsathumar/ai-powered-expense-tracker/blob/main/src/db/queries/transactions.ts"
click node_account_queries "https://github.com/hamsathumar/ai-powered-expense-tracker/blob/main/src/db/queries/accounts.ts"
click node_recurring_queries "https://github.com/hamsathumar/ai-powered-expense-tracker/blob/main/src/db/queries/recurring.ts"
click node_report_queries "https://github.com/hamsathumar/ai-powered-expense-tracker/blob/main/src/db/queries/reports.ts"
click node_backup_service "https://github.com/hamsathumar/ai-powered-expense-tracker/blob/main/src/services/backupFile.ts"
click node_voice_ai "https://github.com/hamsathumar/ai-powered-expense-tracker/blob/main/src/ai/parseVoice.ts"
click node_currency_context "https://github.com/hamsathumar/ai-powered-expense-tracker/blob/main/src/theme/CurrencyContext.tsx"

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_root_layout,node_tabs_layout,node_dashboard,node_transaction_routes,node_account_detail,node_shared_expenses,node_recurring_payments,node_voice_screen,node_currency_context toneBlue
class node_transaction_form,node_financial_domain,node_domain_models toneAmber
class node_database_client,node_transaction_queries,node_account_queries,node_recurring_queries,node_report_queries toneMint
class node_backup_service,node_voice_ai toneRose
```

## Components

### App UI

Expo Router screens and shared composition.

- [App shell](https://github.com/hamsathumar/ai-powered-expense-tracker/blob/main/src/app/_layout.tsx): Expo Router layout · Establishes shared providers and navigation. · `src/app/_layout.tsx`
- [Main tabs](https://github.com/hamsathumar/ai-powered-expense-tracker/blob/main/src/app/(tabs)/_layout.tsx): tab layout · Primary dashboard, accounts, reports, and settings entry. · `src/app/(tabs)/_layout.tsx`
- [Dashboard](https://github.com/hamsathumar/ai-powered-expense-tracker/blob/main/src/app/(tabs)/index.tsx): screen · `src/app/(tabs)/index.tsx`
- [Transaction flows](https://github.com/hamsathumar/ai-powered-expense-tracker/blob/main/src/app/transaction/new.tsx): create/detail screens · `src/app/transaction/new.tsx`
- [Account detail](https://github.com/hamsathumar/ai-powered-expense-tracker/blob/main/src/app/account/%5Bid%5D.tsx): screen · `src/app/account/[id].tsx`
- [Shared expenses](https://github.com/hamsathumar/ai-powered-expense-tracker/blob/main/src/app/bill-split.tsx): split and settle screens · `src/app/bill-split.tsx`
- [Recurring payments](https://github.com/hamsathumar/ai-powered-expense-tracker/blob/main/src/app/recurring/%5Bid%5D/payments.tsx): screen · `src/app/recurring/[id]/payments.tsx`
- [Voice entry](https://github.com/hamsathumar/ai-powered-expense-tracker/blob/main/src/app/voice.tsx): screen · `src/app/voice.tsx`
- [Currency display](https://github.com/hamsathumar/ai-powered-expense-tracker/blob/main/src/theme/CurrencyContext.tsx): app context · App-wide currency presentation state. · `src/theme/CurrencyContext.tsx`

### Domain & workflows

Deterministic financial rules and reusable input flow.

- [Transaction form](https://github.com/hamsathumar/ai-powered-expense-tracker/blob/main/src/components/TransactionForm.tsx): UI component · Reusable financial input composition. · `src/components/TransactionForm.tsx`
- [Financial rules](https://github.com/hamsathumar/ai-powered-expense-tracker/blob/main/src/domain/money.ts): pure domain logic · Money, activity, recurring schedules, splits, and settlements. · `src/domain/money.ts`
- [Domain models](https://github.com/hamsathumar/ai-powered-expense-tracker/blob/main/src/domain/types.ts): typed models · `src/domain/types.ts`

### Persistence

Exclusive stored-financial-data boundary.

- [Database lifecycle](https://github.com/hamsathumar/ai-powered-expense-tracker/blob/main/src/db/client.ts): client and migrations · Initializes, migrates, and seeds local storage. · `src/db/client.ts`
- [Transaction queries](https://github.com/hamsathumar/ai-powered-expense-tracker/blob/main/src/db/queries/transactions.ts): query module · `src/db/queries/transactions.ts`
- [Account queries](https://github.com/hamsathumar/ai-powered-expense-tracker/blob/main/src/db/queries/accounts.ts): query module · Also supports category and people persistence workflows. · `src/db/queries/accounts.ts`
- [Recurring queries](https://github.com/hamsathumar/ai-powered-expense-tracker/blob/main/src/db/queries/recurring.ts): query module · `src/db/queries/recurring.ts`
- [Report aggregates](https://github.com/hamsathumar/ai-powered-expense-tracker/blob/main/src/db/queries/reports.ts): query module · Provides persisted aggregates for visual summaries. · `src/db/queries/reports.ts`

### Device & AI

External AI and local file boundaries.

- [Backup and files](https://github.com/hamsathumar/ai-powered-expense-tracker/blob/main/src/services/backupFile.ts): file service · Isolates backup-file and device file operations. · `src/services/backupFile.ts`
- [Voice parsing AI](https://github.com/hamsathumar/ai-powered-expense-tracker/blob/main/src/ai/parseVoice.ts): Gemini integration · Builds prompts, parses and validates voice-derived transactions. · `src/ai/parseVoice.ts`

## Connections

- App shell → Main tabs: hosts
- App shell → Currency display: provides
- Main tabs → Dashboard: opens
- Main tabs → Account detail: navigates to
- Main tabs → Transaction flows: navigates to
- Transaction flows → Transaction form: composes
- Transaction form → Financial rules: applies rules
- Financial rules → Domain models: uses
- Transaction form → Transaction queries: persists through
- Account detail → Account queries: loads activity
- Account detail → Financial rules: calculates activity with
- Shared expenses → Financial rules: splits and settles with
- Shared expenses → Account queries: uses people data
- Recurring payments → Recurring queries: reads and records
- Recurring payments → Financial rules: evaluates schedules
- Dashboard → Report aggregates: reads summaries
- Voice entry → Voice parsing AI: submits capture
- Voice parsing AI → Transaction form: returns validated draft
- Transaction queries → Database lifecycle: uses
- Account queries → Database lifecycle: uses
- Recurring queries → Database lifecycle: uses
- Report aggregates → Database lifecycle: uses
- Backup and files → Database lifecycle: backs up and restores