# santhoshk0409/budjet-buddy architecture

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

- Interactive diagram: https://gitdiagram.com/santhoshk0409/budjet-buddy
- Repository: https://github.com/santhoshk0409/budjet-buddy

## Overview

#### Purpose and Entry Points
Wallet Buddy is a mobile-first personal finance tracker with multi-wallet budgets, expenses, history, analytics, reports, backup/restore, offline storage, and Supabase-backed synchronization. The Vite/React client starts at `src/main.tsx`, mounts the application in `src/App.tsx`, and is hosted as a static SPA with deployment routing in `vercel.json`, `netlify.toml`, and `public/_redirects`.

#### Application Shell and Navigation
`src/App.tsx` is the primary UI orchestrator: it selects authenticated versus onboarding/auth states and switches among major finance views. `src/components/layout/BottomNavigation.tsx` provides the mobile-oriented navigation boundary for Home, History, Analytics, Reports, and Settings. Shared visual styling is rooted in `src/index.css` and `src/App.css`.

#### Authentication and User Scope
`src/context/AuthContext.tsx` owns the authenticated-user/session state exposed to the React tree. Authentication screens are separated into `src/components/auth/LoginView.tsx`, `src/components/auth/SignUpView.tsx`, and `src/components/auth/SplashScreen.tsx`. Supabase Auth is the external identity provider; finance data operations should be scoped by the active authenticated user.

#### Persistence, Offline-First, and Sync Boundary
`src/db/database.ts` defines the Dexie/IndexedDB local persistence layer, enabling immediate offline reads and writes. `src/lib/supabase.ts` initializes the Supabase client from Vite environment variables, while `src/services/supabaseService.ts` centralizes cloud CRUD/synchronization behavior. The Supabase PostgreSQL schema and likely row/security contract are captured in `supabase_schema.sql`; this is the principal boundary between local app state and the hosted backend.

#### Finance Domain and Data Flow
Shared domain contracts for wallets, expenses, categories, budgets, and related records live in `src/types/index.ts`. User actions flow from modal editors—`src/components/wallet/WalletModal.tsx`, `src/components/expense/AddExpenseModal.tsx`, and `src/components/category/ExpenseTypeModal.tsx`—to local storage and cloud service operations. Budget-period rollover is explicitly handled by `src/components/budget/NewMonthResetModal.tsx`.

#### Views, Analysis, and Reporting
`src/views/HomeView.tsx` presents the primary budget/wallet status and spending experience. Historical querying is handled by `src/views/HistoryView.tsx`, aided by `src/components/common/CalendarDateSelector.tsx` for single-date and range selection. Derived spending analysis is surfaced through `src/views/AnalyticsView.tsx` and `src/views/ReportsView.tsx`; `src/views/SettingsView.tsx` is the likely control point for preferences and data export/import.

#### Runtime and Infrastructure
The frontend is React 19 + TypeScript built and served by Vite (`vite.config.ts`, `package.json`). Browser IndexedDB is the local runtime datastore; Supabase supplies Auth, PostgreSQL, and real-time/cloud synchronization. Production deployment supports Vercel and Netlify, with `VITE_SUPABASE_URL` and `VITE_SUPABASE_ANON_KEY` required for backend connectivity.

Main entry points: [`src/db/database.ts`](https://github.com/santhoshk0409/budjet-buddy/blob/main/src/db/database.ts) (Dexie database), [`src/components/layout/BottomNavigation.tsx`](https://github.com/santhoshk0409/budjet-buddy/blob/main/src/components/layout/BottomNavigation.tsx) (Bottom navigation), [`src/App.tsx`](https://github.com/santhoshk0409/budjet-buddy/blob/main/src/App.tsx) (App shell), [`src/views/HomeView.tsx`](https://github.com/santhoshk0409/budjet-buddy/blob/main/src/views/HomeView.tsx) (Home view)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["React Client"]
  node_entry["Vite entry<br/>bootstrap<br/>[main.tsx]"]
  node_app["App shell<br/>UI orchestrator<br/>[App.tsx]"]
  node_auth_context["Auth context<br/>session state<br/>[AuthContext.tsx]"]
  node_auth_screens["Auth screens<br/>authentication UI<br/>[LoginView.tsx]"]
  node_navigation["Bottom navigation<br/>mobile navigation"]
  node_home["Home view<br/>budget dashboard<br/>[HomeView.tsx]"]
  node_history["History view<br/>transaction history<br/>[HistoryView.tsx]"]
  node_date_selector["Date selector<br/>history filter"]
  node_analytics["Analytics view<br/>spending analysis<br/>[AnalyticsView.tsx]"]
  node_reports["Reports view<br/>reporting<br/>[ReportsView.tsx]"]
  node_settings["Settings view<br/>preferences and data transfer<br/>[SettingsView.tsx]"]
  node_finance_editors["Wallet editor<br/>finance input<br/>[WalletModal.tsx]"]
  node_month_reset["New-month reset<br/>budget rollover"]
  node_domain_types["Finance contracts<br/>TypeScript domain models<br/>[index.ts]"]
end

subgraph group_local["Offline Data"]
  node_local_db[("Dexie database<br/>IndexedDB persistence<br/>[database.ts]")]
end

subgraph group_cloud["Supabase Backend"]
  node_supabase_client["Supabase client<br/>backend SDK setup<br/>[supabase.ts]"]
  node_sync_service["Sync service<br/>cloud CRUD and sync<br/>[supabaseService.ts]"]
  node_supabase_auth["Supabase Auth<br/>identity provider"]
  node_postgres[("Supabase PostgreSQL<br/>hosted finance data")]
end

node_static_hosting["Static SPA hosting<br/>Vercel and Netlify deployment<br/>[vercel.json]"]

node_entry -->|"mounts"| node_app
node_app -->|"reads session"| node_auth_context
node_app -->|"shows when unauthenticated"| node_auth_screens
node_app -->|"renders"| node_navigation
node_navigation -->|"opens"| node_home
node_navigation -->|"opens"| node_history
node_navigation -->|"opens"| node_analytics
node_navigation -->|"opens"| node_reports
node_navigation -->|"opens"| node_settings
node_history -->|"filters with"| node_date_selector
node_home -->|"edits finance data"| node_finance_editors
node_home -->|"triggers rollover"| node_month_reset
node_finance_editors -->|"uses records"| node_domain_types
node_finance_editors -->|"writes offline"| node_local_db
node_month_reset -->|"updates budgets"| node_local_db
node_home -->|"reads status"| node_local_db
node_history -->|"queries records"| node_local_db
node_analytics -->|"derives spending"| node_local_db
node_reports -->|"derives reports"| node_local_db
node_auth_context -->|"uses"| node_supabase_client
node_supabase_client -->|"authenticates"| node_supabase_auth
node_local_db -.->|"syncs changes"| node_sync_service
node_sync_service -->|"uses client"| node_supabase_client
node_sync_service -->|"scoped cloud CRUD"| node_postgres
node_static_hosting -->|"serves SPA"| node_entry

click node_entry "https://github.com/santhoshk0409/budjet-buddy/blob/main/src/main.tsx"
click node_app "https://github.com/santhoshk0409/budjet-buddy/blob/main/src/App.tsx"
click node_auth_context "https://github.com/santhoshk0409/budjet-buddy/blob/main/src/context/AuthContext.tsx"
click node_auth_screens "https://github.com/santhoshk0409/budjet-buddy/blob/main/src/components/auth/LoginView.tsx"
click node_navigation "https://github.com/santhoshk0409/budjet-buddy/blob/main/src/components/layout/BottomNavigation.tsx"
click node_home "https://github.com/santhoshk0409/budjet-buddy/blob/main/src/views/HomeView.tsx"
click node_history "https://github.com/santhoshk0409/budjet-buddy/blob/main/src/views/HistoryView.tsx"
click node_date_selector "https://github.com/santhoshk0409/budjet-buddy/blob/main/src/components/common/CalendarDateSelector.tsx"
click node_analytics "https://github.com/santhoshk0409/budjet-buddy/blob/main/src/views/AnalyticsView.tsx"
click node_reports "https://github.com/santhoshk0409/budjet-buddy/blob/main/src/views/ReportsView.tsx"
click node_settings "https://github.com/santhoshk0409/budjet-buddy/blob/main/src/views/SettingsView.tsx"
click node_finance_editors "https://github.com/santhoshk0409/budjet-buddy/blob/main/src/components/wallet/WalletModal.tsx"
click node_month_reset "https://github.com/santhoshk0409/budjet-buddy/blob/main/src/components/budget/NewMonthResetModal.tsx"
click node_domain_types "https://github.com/santhoshk0409/budjet-buddy/blob/main/src/types/index.ts"
click node_local_db "https://github.com/santhoshk0409/budjet-buddy/blob/main/src/db/database.ts"
click node_supabase_client "https://github.com/santhoshk0409/budjet-buddy/blob/main/src/lib/supabase.ts"
click node_sync_service "https://github.com/santhoshk0409/budjet-buddy/blob/main/src/services/supabaseService.ts"
click node_postgres "https://github.com/santhoshk0409/budjet-buddy/blob/main/supabase_schema.sql"
click node_static_hosting "https://github.com/santhoshk0409/budjet-buddy/blob/main/vercel.json"

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_entry,node_app,node_auth_context,node_auth_screens,node_navigation,node_home,node_history,node_date_selector,node_analytics,node_reports,node_settings,node_finance_editors,node_month_reset,node_domain_types toneBlue
class node_local_db toneAmber
class node_supabase_client,node_sync_service,node_supabase_auth,node_postgres toneMint
class node_static_hosting toneNeutral
```

## Components

### React Client

- [Vite entry](https://github.com/santhoshk0409/budjet-buddy/blob/main/src/main.tsx): bootstrap · `src/main.tsx`
- [App shell](https://github.com/santhoshk0409/budjet-buddy/blob/main/src/App.tsx): UI orchestrator · Selects auth/onboarding states and primary finance views. · `src/App.tsx`
- [Auth context](https://github.com/santhoshk0409/budjet-buddy/blob/main/src/context/AuthContext.tsx): session state · `src/context/AuthContext.tsx`
- [Auth screens](https://github.com/santhoshk0409/budjet-buddy/blob/main/src/components/auth/LoginView.tsx): authentication UI · `src/components/auth/LoginView.tsx`
- [Bottom navigation](https://github.com/santhoshk0409/budjet-buddy/blob/main/src/components/layout/BottomNavigation.tsx): mobile navigation · `src/components/layout/BottomNavigation.tsx`
- [Home view](https://github.com/santhoshk0409/budjet-buddy/blob/main/src/views/HomeView.tsx): budget dashboard · `src/views/HomeView.tsx`
- [History view](https://github.com/santhoshk0409/budjet-buddy/blob/main/src/views/HistoryView.tsx): transaction history · `src/views/HistoryView.tsx`
- [Date selector](https://github.com/santhoshk0409/budjet-buddy/blob/main/src/components/common/CalendarDateSelector.tsx): history filter · `src/components/common/CalendarDateSelector.tsx`
- [Analytics view](https://github.com/santhoshk0409/budjet-buddy/blob/main/src/views/AnalyticsView.tsx): spending analysis · `src/views/AnalyticsView.tsx`
- [Reports view](https://github.com/santhoshk0409/budjet-buddy/blob/main/src/views/ReportsView.tsx): reporting · `src/views/ReportsView.tsx`
- [Settings view](https://github.com/santhoshk0409/budjet-buddy/blob/main/src/views/SettingsView.tsx): preferences and data transfer · `src/views/SettingsView.tsx`
- [Wallet editor](https://github.com/santhoshk0409/budjet-buddy/blob/main/src/components/wallet/WalletModal.tsx): finance input · Modal-based user actions create and update finance records. · `src/components/wallet/WalletModal.tsx`
- [New-month reset](https://github.com/santhoshk0409/budjet-buddy/blob/main/src/components/budget/NewMonthResetModal.tsx): budget rollover · `src/components/budget/NewMonthResetModal.tsx`
- [Finance contracts](https://github.com/santhoshk0409/budjet-buddy/blob/main/src/types/index.ts): TypeScript domain models · `src/types/index.ts`

### Offline Data

- [Dexie database](https://github.com/santhoshk0409/budjet-buddy/blob/main/src/db/database.ts): IndexedDB persistence · Offline-first local reads and writes. · `src/db/database.ts`

### Supabase Backend

- [Supabase client](https://github.com/santhoshk0409/budjet-buddy/blob/main/src/lib/supabase.ts): backend SDK setup · `src/lib/supabase.ts`
- [Sync service](https://github.com/santhoshk0409/budjet-buddy/blob/main/src/services/supabaseService.ts): cloud CRUD and sync · `src/services/supabaseService.ts`
- **Supabase Auth**: identity provider
- [Supabase PostgreSQL](https://github.com/santhoshk0409/budjet-buddy/blob/main/supabase_schema.sql): hosted finance data · Schema and row/security contract are defined in the SQL schema. · `supabase_schema.sql`

### Other components

- [Static SPA hosting](https://github.com/santhoshk0409/budjet-buddy/blob/main/vercel.json): Vercel and Netlify deployment · `vercel.json`

## Connections

- Vite entry → App shell: mounts
- App shell → Auth context: reads session
- App shell → Auth screens: shows when unauthenticated
- App shell → Bottom navigation: renders
- Bottom navigation → Home view: opens
- Bottom navigation → History view: opens
- Bottom navigation → Analytics view: opens
- Bottom navigation → Reports view: opens
- Bottom navigation → Settings view: opens
- History view → Date selector: filters with
- Home view → Wallet editor: edits finance data
- Home view → New-month reset: triggers rollover
- Wallet editor → Finance contracts: uses records
- Wallet editor → Dexie database: writes offline
- New-month reset → Dexie database: updates budgets
- Home view → Dexie database: reads status
- History view → Dexie database: queries records
- Analytics view → Dexie database: derives spending
- Reports view → Dexie database: derives reports
- Auth context → Supabase client: uses
- Supabase client → Supabase Auth: authenticates
- Dexie database → Sync service: syncs changes
- Sync service → Supabase client: uses client
- Sync service → Supabase PostgreSQL: scoped cloud CRUD
- Static SPA hosting → Vite entry: serves SPA