# w1ztechsolutions/walletwise architecture

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

- Interactive diagram: https://gitdiagram.com/w1ztechsolutions/walletwise
- Repository: https://github.com/w1ztechsolutions/walletwise

## Overview

WalletWise is a personal-finance application for managing transactions, accounts, budgets, categories, and analytics, with spreadsheet import and receipt storage. The main workflow is sign in, navigate a finance view, load or change data through query hooks and the API, then persist it in the edge-backed database. The graph also includes profile and account recovery, authentication, and import review. Several backend routes are represented from the file tree and SOURCE INDEX; their internal behavior is not claimed beyond the shown references.

Main entry points: [`src/hooks`](https://github.com/w1ztechsolutions/walletwise/tree/main/src/hooks) (Finance data hooks), [`src/App.tsx`](https://github.com/w1ztechsolutions/walletwise/blob/main/src/App.tsx) (Application shell), [`src/components/import/SpreadsheetImport.tsx`](https://github.com/w1ztechsolutions/walletwise/blob/main/src/components/import/SpreadsheetImport.tsx) (Spreadsheet import), [`src/components/auth/AuthGate.tsx`](https://github.com/w1ztechsolutions/walletwise/blob/main/src/components/auth/AuthGate.tsx) (Authentication gate)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Finance client"]
  node_app["Application shell<br/>[App.tsx]"]
  node_authgate["Authentication gate<br/>[AuthGate.tsx]"]
  node_authview["Sign-in view<br/>[AuthView.tsx]"]
  node_dashboard["Dashboard<br/>[DashboardView.tsx]"]
  node_transactionsview["Transactions"]
  node_accountsview["Accounts<br/>[AccountsView.tsx]"]
  node_budgetsview["Budgets<br/>[BudgetsView.tsx]"]
  node_analyticsview["Analytics<br/>[AnalyticsView.tsx]"]
  node_settings["Settings and recovery<br/>[SettingsView.tsx]"]
  node_spreadsheet["Spreadsheet import"]
  node_review["Import review"]
end

subgraph group_clientdata["Client data layer"]
  node_session["Session state<br/>[useSession.ts]"]
  node_datahooks["Finance data hooks"]
  node_bulkimport["Bulk import hook<br/>[useBulkImport.ts]"]
  node_userhook["User profile hook<br/>[useUser.ts]"]
  node_apiclient["API client<br/>[api.ts]"]
  node_authclient["Auth client<br/>[auth-client.ts]"]
  node_importparser["Spreadsheet parser<br/>[importParser.ts]"]
end

subgraph group_edge["Edge services"]
  node_api["Finance API routes"]
  node_importapi["Import API<br/>[index.ts]"]
  node_analyticsapi["Analytics API<br/>[index.ts]"]
  node_authapi["Authentication route<br/>[&#91;&#91;all&#93;&#93;.ts]"]
  node_aiapi["AI spreadsheet parsing"]
  node_storageapi["Storage routes"]
  node_middleware["Request middleware<br/>[_middleware.ts]"]
  node_purge["Account purge worker<br/>[account-purge.ts]"]
end

subgraph group_state["Persistence and storage"]
  node_schema["Finance and auth schema<br/>[schema.ts]"]
  node_storagepolicy["Upload policies<br/>[storagePolicy.ts]"]
  node_objectstorage[("Object storage")]
end

node_user(("Finance user"))

node_user -->|"opens app"| node_authgate
node_app -->|"gates content"| node_authgate
node_app -->|"routes to"| node_dashboard
node_app -->|"routes to"| node_transactionsview
node_app -->|"routes to"| node_accountsview
node_app -->|"routes to"| node_budgetsview
node_app -->|"routes to"| node_analyticsview
node_app -->|"routes to"| node_settings
node_authgate -->|"shows sign-in"| node_authview
node_authgate -->|"checks session"| node_session
node_session -->|"gets session"| node_authclient
node_authview -->|"uses auth"| node_authclient
node_transactionsview -->|"uses data hooks"| node_datahooks
node_accountsview -->|"uses account hooks"| node_datahooks
node_analyticsview -->|"loads analytics"| node_datahooks
node_dashboard -->|"loads summaries"| node_datahooks
node_budgetsview -->|"uses budget hooks"| node_datahooks
node_settings -->|"reads profile"| node_userhook
node_datahooks -->|"requests data"| node_apiclient
node_userhook -->|"requests profile"| node_apiclient
node_apiclient -->|"sends API requests"| node_api
node_datahooks -->|"keys by identity"| node_session
node_datahooks -->|"invalidates related caches"| node_transactionsview
node_spreadsheet -->|"parses file"| node_importparser
node_spreadsheet -->|"opens review"| node_review
node_spreadsheet -->|"previews and commits"| node_bulkimport
node_review -->|"submits decisions"| node_bulkimport
node_bulkimport -->|"posts import"| node_apiclient
node_bulkimport -->|"previews or commits"| node_importapi
node_importapi -->|"references schema"| node_schema
node_analyticsapi -->|"references schema"| node_schema
node_api -.->|"requests pass through"| node_middleware
node_middleware -->|"uses auth"| node_authclient
node_middleware -.->|"protects data routes"| node_authapi
node_storagepolicy -->|"validates uploads"| node_spreadsheet
node_storagepolicy -.->|"server revalidates"| node_storageapi
node_storageapi -.->|"stores objects"| node_objectstorage
node_aiapi -.->|"may parse spreadsheets"| node_importparser
node_purge -.->|"purges account data"| node_schema

click node_app "https://github.com/w1ztechsolutions/walletwise/blob/main/src/App.tsx"
click node_authgate "https://github.com/w1ztechsolutions/walletwise/blob/main/src/components/auth/AuthGate.tsx"
click node_authview "https://github.com/w1ztechsolutions/walletwise/blob/main/src/components/auth/AuthView.tsx"
click node_dashboard "https://github.com/w1ztechsolutions/walletwise/blob/main/src/components/dashboard/DashboardView.tsx"
click node_transactionsview "https://github.com/w1ztechsolutions/walletwise/blob/main/src/components/transactions/TransactionsView.tsx"
click node_accountsview "https://github.com/w1ztechsolutions/walletwise/blob/main/src/components/accounts/AccountsView.tsx"
click node_budgetsview "https://github.com/w1ztechsolutions/walletwise/blob/main/src/components/budgets/BudgetsView.tsx"
click node_analyticsview "https://github.com/w1ztechsolutions/walletwise/blob/main/src/components/analytics/AnalyticsView.tsx"
click node_settings "https://github.com/w1ztechsolutions/walletwise/blob/main/src/components/settings/SettingsView.tsx"
click node_spreadsheet "https://github.com/w1ztechsolutions/walletwise/blob/main/src/components/import/SpreadsheetImport.tsx"
click node_review "https://github.com/w1ztechsolutions/walletwise/blob/main/src/components/settings/ImportReviewModal.tsx"
click node_session "https://github.com/w1ztechsolutions/walletwise/blob/main/src/hooks/useSession.ts"
click node_datahooks "https://github.com/w1ztechsolutions/walletwise/tree/main/src/hooks"
click node_bulkimport "https://github.com/w1ztechsolutions/walletwise/blob/main/src/hooks/useBulkImport.ts"
click node_userhook "https://github.com/w1ztechsolutions/walletwise/blob/main/src/hooks/useUser.ts"
click node_apiclient "https://github.com/w1ztechsolutions/walletwise/blob/main/src/lib/api.ts"
click node_authclient "https://github.com/w1ztechsolutions/walletwise/blob/main/src/lib/auth-client.ts"
click node_importparser "https://github.com/w1ztechsolutions/walletwise/blob/main/src/lib/importParser.ts"
click node_api "https://github.com/w1ztechsolutions/walletwise/tree/main/functions/api"
click node_importapi "https://github.com/w1ztechsolutions/walletwise/blob/main/functions/api/import/index.ts"
click node_analyticsapi "https://github.com/w1ztechsolutions/walletwise/blob/main/functions/api/analytics/index.ts"
click node_authapi "https://github.com/w1ztechsolutions/walletwise/blob/main/functions/api/auth/%5B%5Ball%5D%5D.ts"
click node_aiapi "https://github.com/w1ztechsolutions/walletwise/blob/main/functions/api/ai/parse-spreadsheet.ts"
click node_storageapi "https://github.com/w1ztechsolutions/walletwise/tree/main/functions/api/storage"
click node_middleware "https://github.com/w1ztechsolutions/walletwise/blob/main/functions/_middleware.ts"
click node_purge "https://github.com/w1ztechsolutions/walletwise/blob/main/workers/account-purge.ts"
click node_schema "https://github.com/w1ztechsolutions/walletwise/blob/main/src/db/schema.ts"
click node_storagepolicy "https://github.com/w1ztechsolutions/walletwise/blob/main/src/lib/storagePolicy.ts"

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,node_authgate,node_authview,node_dashboard,node_transactionsview,node_accountsview,node_budgetsview,node_analyticsview,node_settings,node_spreadsheet,node_review,node_user toneBlue
class node_session,node_datahooks,node_bulkimport,node_userhook,node_apiclient,node_authclient,node_importparser toneAmber
class node_api,node_importapi,node_analyticsapi,node_authapi,node_aiapi,node_storageapi,node_middleware,node_purge toneMint
class node_schema,node_storagepolicy,node_objectstorage toneRose
```

## Components

### Finance client

- [Application shell](https://github.com/w1ztechsolutions/walletwise/blob/main/src/App.tsx): `src/App.tsx`
- [Authentication gate](https://github.com/w1ztechsolutions/walletwise/blob/main/src/components/auth/AuthGate.tsx): `src/components/auth/AuthGate.tsx`
- [Sign-in view](https://github.com/w1ztechsolutions/walletwise/blob/main/src/components/auth/AuthView.tsx): `src/components/auth/AuthView.tsx`
- [Dashboard](https://github.com/w1ztechsolutions/walletwise/blob/main/src/components/dashboard/DashboardView.tsx): `src/components/dashboard/DashboardView.tsx`
- [Transactions](https://github.com/w1ztechsolutions/walletwise/blob/main/src/components/transactions/TransactionsView.tsx): `src/components/transactions/TransactionsView.tsx`
- [Accounts](https://github.com/w1ztechsolutions/walletwise/blob/main/src/components/accounts/AccountsView.tsx): `src/components/accounts/AccountsView.tsx`
- [Budgets](https://github.com/w1ztechsolutions/walletwise/blob/main/src/components/budgets/BudgetsView.tsx): `src/components/budgets/BudgetsView.tsx`
- [Analytics](https://github.com/w1ztechsolutions/walletwise/blob/main/src/components/analytics/AnalyticsView.tsx): `src/components/analytics/AnalyticsView.tsx`
- [Settings and recovery](https://github.com/w1ztechsolutions/walletwise/blob/main/src/components/settings/SettingsView.tsx): `src/components/settings/SettingsView.tsx`
- [Spreadsheet import](https://github.com/w1ztechsolutions/walletwise/blob/main/src/components/import/SpreadsheetImport.tsx): `src/components/import/SpreadsheetImport.tsx`
- [Import review](https://github.com/w1ztechsolutions/walletwise/blob/main/src/components/settings/ImportReviewModal.tsx): `src/components/settings/ImportReviewModal.tsx`

### Client data layer

- [Session state](https://github.com/w1ztechsolutions/walletwise/blob/main/src/hooks/useSession.ts): `src/hooks/useSession.ts`
- [Finance data hooks](https://github.com/w1ztechsolutions/walletwise/tree/main/src/hooks): `src/hooks`
- [Bulk import hook](https://github.com/w1ztechsolutions/walletwise/blob/main/src/hooks/useBulkImport.ts): `src/hooks/useBulkImport.ts`
- [User profile hook](https://github.com/w1ztechsolutions/walletwise/blob/main/src/hooks/useUser.ts): `src/hooks/useUser.ts`
- [API client](https://github.com/w1ztechsolutions/walletwise/blob/main/src/lib/api.ts): `src/lib/api.ts`
- [Auth client](https://github.com/w1ztechsolutions/walletwise/blob/main/src/lib/auth-client.ts): `src/lib/auth-client.ts`
- [Spreadsheet parser](https://github.com/w1ztechsolutions/walletwise/blob/main/src/lib/importParser.ts): `src/lib/importParser.ts`

### Edge services

- [Finance API routes](https://github.com/w1ztechsolutions/walletwise/tree/main/functions/api): `functions/api`
- [Import API](https://github.com/w1ztechsolutions/walletwise/blob/main/functions/api/import/index.ts): `functions/api/import/index.ts`
- [Analytics API](https://github.com/w1ztechsolutions/walletwise/blob/main/functions/api/analytics/index.ts): `functions/api/analytics/index.ts`
- [Authentication route](https://github.com/w1ztechsolutions/walletwise/blob/main/functions/api/auth/%5B%5Ball%5D%5D.ts): `functions/api/auth/[[all]].ts`
- [AI spreadsheet parsing](https://github.com/w1ztechsolutions/walletwise/blob/main/functions/api/ai/parse-spreadsheet.ts): `functions/api/ai/parse-spreadsheet.ts`
- [Storage routes](https://github.com/w1ztechsolutions/walletwise/tree/main/functions/api/storage): `functions/api/storage`
- [Request middleware](https://github.com/w1ztechsolutions/walletwise/blob/main/functions/_middleware.ts): `functions/_middleware.ts`
- [Account purge worker](https://github.com/w1ztechsolutions/walletwise/blob/main/workers/account-purge.ts): `workers/account-purge.ts`

### Persistence and storage

- [Finance and auth schema](https://github.com/w1ztechsolutions/walletwise/blob/main/src/db/schema.ts): `src/db/schema.ts`
- [Upload policies](https://github.com/w1ztechsolutions/walletwise/blob/main/src/lib/storagePolicy.ts): `src/lib/storagePolicy.ts`
- **Object storage**

### Other components

- **Finance user**

## Connections

- Finance user → Authentication gate: opens app
- Application shell → Authentication gate: gates content (evidence: `src/App.tsx`)
- Application shell → Dashboard: routes to (evidence: `src/App.tsx`)
- Application shell → Transactions: routes to (evidence: `src/App.tsx`)
- Application shell → Accounts: routes to (evidence: `src/App.tsx`)
- Application shell → Budgets: routes to (evidence: `src/App.tsx`)
- Application shell → Analytics: routes to (evidence: `src/App.tsx`)
- Application shell → Settings and recovery: routes to (evidence: `src/App.tsx`)
- Authentication gate → Sign-in view: shows sign-in (evidence: `src/components/auth/AuthGate.tsx`)
- Authentication gate → Session state: checks session (evidence: `src/components/auth/AuthGate.tsx`)
- Session state → Auth client: gets session (evidence: `src/hooks/useSession.ts`)
- Sign-in view → Auth client: uses auth (evidence: `src/components/auth/AuthView.tsx`)
- Transactions → Finance data hooks: uses data hooks (evidence: `src/components/transactions/TransactionsView.tsx`)
- Accounts → Finance data hooks: uses account hooks (evidence: `src/components/accounts/AccountsView.tsx`)
- Analytics → Finance data hooks: loads analytics (evidence: `src/components/analytics/AnalyticsView.tsx`)
- Dashboard → Finance data hooks: loads summaries (evidence: `src/components/dashboard/DashboardView.tsx`)
- Budgets → Finance data hooks: uses budget hooks (evidence: `src/components/budgets/BudgetsView.tsx`)
- Settings and recovery → User profile hook: reads profile
- Finance data hooks → API client: requests data (evidence: `src/hooks/useTransactions.ts`)
- User profile hook → API client: requests profile (evidence: `src/hooks/useUser.ts`)
- API client → Finance API routes: sends API requests (evidence: `src/lib/api.ts`)
- Finance data hooks → Session state: keys by identity (evidence: `src/hooks/useTransactions.ts`)
- Finance data hooks → Transactions: invalidates related caches (evidence: `src/hooks/useTransactions.ts`)
- Spreadsheet import → Spreadsheet parser: parses file (evidence: `src/components/import/SpreadsheetImport.tsx`)
- Spreadsheet import → Import review: opens review (evidence: `src/components/import/SpreadsheetImport.tsx`)
- Spreadsheet import → Bulk import hook: previews and commits (evidence: `src/components/import/SpreadsheetImport.tsx`)
- Import review → Bulk import hook: submits decisions (evidence: `src/components/settings/ImportReviewModal.tsx`)
- Bulk import hook → API client: posts import (evidence: `src/hooks/useBulkImport.ts`)
- Bulk import hook → Import API: previews or commits (evidence: `src/hooks/useBulkImport.ts`)
- Import API → Finance and auth schema: references schema (evidence: `functions/api/import/index.ts`)
- Analytics API → Finance and auth schema: references schema (evidence: `functions/api/analytics/index.ts`)
- Finance API routes → Request middleware: requests pass through
- Request middleware → Auth client: uses auth (evidence: `functions/_middleware.ts`)
- Request middleware → Authentication route: protects data routes
- Upload policies → Spreadsheet import: validates uploads (evidence: `src/components/import/SpreadsheetImport.tsx`)
- Upload policies → Storage routes: server revalidates (evidence: `src/lib/storagePolicy.ts`)
- Storage routes → Object storage: stores objects
- AI spreadsheet parsing → Spreadsheet parser: may parse spreadsheets
- Account purge worker → Finance and auth schema: purges account data
