# lochan87/spenza architecture

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

- Interactive diagram: https://gitdiagram.com/lochan87/spenza
- Repository: https://github.com/lochan87/spenza

## Overview

Spenza is a personal expense-tracking PWA. A signed-in user enters or imports expenses, then reviews spending through dashboard, budgets, trips, recurring items, and insights; feature services persist and retrieve user-scoped data in Firebase. The graph preserves the distinct transaction, import, recurring, budgeting, trip, and analysis areas. The excerpts confirm app routing, dashboard fetching, recurring confirmation, and import calls; other feature-to-service links reflect documented capabilities and module structure, not inspected call sites.

Main entry points: [`src/firebase/firestore.ts`](https://github.com/lochan87/spenza/blob/main/src/firebase/firestore.ts) (Firestore data store), [`src/App.tsx`](https://github.com/lochan87/spenza/blob/main/src/App.tsx) (App routes), [`src/features/recurring/useRecurringCheck.ts`](https://github.com/lochan87/spenza/blob/main/src/features/recurring/useRecurringCheck.ts) (Due-item prompts), [`src/services/transactions.ts`](https://github.com/lochan87/spenza/blob/main/src/services/transactions.ts) (Transaction services)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App and access"]
  node_app["App routes<br/>[App.tsx]"]
  node_auth["Authentication state<br/>[useAuth.tsx]"]
  node_login["Google sign-in<br/>[LoginPage.tsx]"]
  node_layout["Protected app shell<br/>[AppLayout.tsx]"]
end

subgraph group_spending["Expense tracking"]
  node_dashboard["Dashboard<br/>[DashboardPage.tsx]"]
  node_dashboarddata["Dashboard data"]
  node_transactions["Transactions and categories"]
  node_import["Bulk import<br/>[ImportPage.tsx]"]
  node_trips["Trip tracking<br/>[TripsPage.tsx]"]
end

subgraph group_planning["Planning and analysis"]
  node_recurring["Recurring expenses<br/>[RecurringPage.tsx]"]
  node_duecheck["Due-item prompts"]
  node_budgets["Monthly budgets<br/>[BudgetPage.tsx]"]
  node_insights["Spending insights<br/>[InsightsPage.tsx]"]
  node_export["CSV export<br/>[exportCsv.ts]"]
end

subgraph group_data["Data services"]
  node_seed["Onboarding seeds<br/>[seed.ts]"]
  node_transactionservice["Transaction services<br/>[transactions.ts]"]
  node_importservice["Import processing<br/>[importExcel.ts]"]
  node_tripservice["Trip services<br/>[trips.ts]"]
  node_recurringservice["Recurring services<br/>[recurring.ts]"]
  node_budgetservice["Budget services<br/>[budgets.ts]"]
  node_insightservice["Insight computation<br/>[insights.ts]"]
  node_firestore[("Firestore data store<br/>[firestore.ts]")]
end

node_user(("User"))
node_google(("Firebase Auth"))

node_user -->|"signs in"| node_login
node_login -->|"authenticates"| node_google
node_app -->|"provides auth"| node_auth
node_app -->|"routes to"| node_login
node_app -->|"wraps protected pages"| node_layout
node_app -->|"runs on login"| node_seed
node_app -->|"checks due items"| node_duecheck
node_user -->|"reviews spending"| node_dashboard
node_dashboard -->|"requests data"| node_dashboarddata
node_dashboarddata -->|"fetches transactions"| node_transactionservice
node_dashboarddata -->|"reads data"| node_firestore
node_user -->|"records expenses"| node_transactions
node_transactions -->|"manages transactions"| node_transactionservice
node_user -->|"uploads spreadsheet"| node_import
node_import -->|"parses and imports"| node_importservice
node_importservice -->|"writes transactions"| node_firestore
node_user -->|"tracks trip spend"| node_trips
node_trips -->|"manages trips"| node_tripservice
node_user -->|"manages recurring items"| node_recurring
node_app -->|"mounts prompt check"| node_duecheck
node_duecheck -->|"loads and advances items"| node_recurringservice
node_duecheck -->|"logs confirmed expense"| node_transactionservice
node_user -->|"sets budgets"| node_budgets
node_budgets -->|"manages budgets"| node_budgetservice
node_user -->|"reviews insights"| node_insights
node_insights -->|"requests analysis"| node_insightservice
node_user -->|"exports transactions"| node_export
node_seed -->|"seeds user data"| node_firestore
node_transactionservice -->|"reads and writes"| node_firestore
node_tripservice -->|"reads and writes"| node_firestore
node_recurringservice -->|"reads and writes"| node_firestore
node_budgetservice -->|"reads and writes"| node_firestore
node_insightservice -->|"reads and caches"| node_firestore

click node_app "https://github.com/lochan87/spenza/blob/main/src/App.tsx"
click node_auth "https://github.com/lochan87/spenza/blob/main/src/hooks/useAuth.tsx"
click node_login "https://github.com/lochan87/spenza/blob/main/src/pages/LoginPage.tsx"
click node_layout "https://github.com/lochan87/spenza/blob/main/src/components/layout/AppLayout.tsx"
click node_dashboard "https://github.com/lochan87/spenza/blob/main/src/features/dashboard/DashboardPage.tsx"
click node_dashboarddata "https://github.com/lochan87/spenza/blob/main/src/features/dashboard/useDashboardData.ts"
click node_transactions "https://github.com/lochan87/spenza/blob/main/src/features/transactions/TransactionsPage.tsx"
click node_import "https://github.com/lochan87/spenza/blob/main/src/features/import/ImportPage.tsx"
click node_trips "https://github.com/lochan87/spenza/blob/main/src/features/trips/TripsPage.tsx"
click node_recurring "https://github.com/lochan87/spenza/blob/main/src/features/recurring/RecurringPage.tsx"
click node_duecheck "https://github.com/lochan87/spenza/blob/main/src/features/recurring/useRecurringCheck.ts"
click node_budgets "https://github.com/lochan87/spenza/blob/main/src/features/budgets/BudgetPage.tsx"
click node_insights "https://github.com/lochan87/spenza/blob/main/src/features/insights/InsightsPage.tsx"
click node_export "https://github.com/lochan87/spenza/blob/main/src/services/exportCsv.ts"
click node_seed "https://github.com/lochan87/spenza/blob/main/src/services/seed.ts"
click node_transactionservice "https://github.com/lochan87/spenza/blob/main/src/services/transactions.ts"
click node_importservice "https://github.com/lochan87/spenza/blob/main/src/services/importExcel.ts"
click node_tripservice "https://github.com/lochan87/spenza/blob/main/src/services/trips.ts"
click node_recurringservice "https://github.com/lochan87/spenza/blob/main/src/services/recurring.ts"
click node_budgetservice "https://github.com/lochan87/spenza/blob/main/src/services/budgets.ts"
click node_insightservice "https://github.com/lochan87/spenza/blob/main/src/services/insights.ts"
click node_firestore "https://github.com/lochan87/spenza/blob/main/src/firebase/firestore.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_auth,node_login,node_layout,node_user toneBlue
class node_dashboard,node_dashboarddata,node_transactions,node_import,node_trips toneAmber
class node_recurring,node_duecheck,node_budgets,node_insights,node_export toneMint
class node_seed,node_transactionservice,node_importservice,node_tripservice,node_recurringservice,node_budgetservice,node_insightservice,node_firestore toneRose
class node_google toneIndigo
```

## Components

### App and access

- [App routes](https://github.com/lochan87/spenza/blob/main/src/App.tsx): `src/App.tsx`
- [Authentication state](https://github.com/lochan87/spenza/blob/main/src/hooks/useAuth.tsx): `src/hooks/useAuth.tsx`
- [Google sign-in](https://github.com/lochan87/spenza/blob/main/src/pages/LoginPage.tsx): `src/pages/LoginPage.tsx`
- [Protected app shell](https://github.com/lochan87/spenza/blob/main/src/components/layout/AppLayout.tsx): `src/components/layout/AppLayout.tsx`

### Expense tracking

- [Dashboard](https://github.com/lochan87/spenza/blob/main/src/features/dashboard/DashboardPage.tsx): `src/features/dashboard/DashboardPage.tsx`
- [Dashboard data](https://github.com/lochan87/spenza/blob/main/src/features/dashboard/useDashboardData.ts): `src/features/dashboard/useDashboardData.ts`
- [Transactions and categories](https://github.com/lochan87/spenza/blob/main/src/features/transactions/TransactionsPage.tsx): `src/features/transactions/TransactionsPage.tsx`
- [Bulk import](https://github.com/lochan87/spenza/blob/main/src/features/import/ImportPage.tsx): `src/features/import/ImportPage.tsx`
- [Trip tracking](https://github.com/lochan87/spenza/blob/main/src/features/trips/TripsPage.tsx): `src/features/trips/TripsPage.tsx`

### Planning and analysis

- [Recurring expenses](https://github.com/lochan87/spenza/blob/main/src/features/recurring/RecurringPage.tsx): `src/features/recurring/RecurringPage.tsx`
- [Due-item prompts](https://github.com/lochan87/spenza/blob/main/src/features/recurring/useRecurringCheck.ts): `src/features/recurring/useRecurringCheck.ts`
- [Monthly budgets](https://github.com/lochan87/spenza/blob/main/src/features/budgets/BudgetPage.tsx): `src/features/budgets/BudgetPage.tsx`
- [Spending insights](https://github.com/lochan87/spenza/blob/main/src/features/insights/InsightsPage.tsx): `src/features/insights/InsightsPage.tsx`
- [CSV export](https://github.com/lochan87/spenza/blob/main/src/services/exportCsv.ts): `src/services/exportCsv.ts`

### Data services

- [Onboarding seeds](https://github.com/lochan87/spenza/blob/main/src/services/seed.ts): `src/services/seed.ts`
- [Transaction services](https://github.com/lochan87/spenza/blob/main/src/services/transactions.ts): `src/services/transactions.ts`
- [Import processing](https://github.com/lochan87/spenza/blob/main/src/services/importExcel.ts): `src/services/importExcel.ts`
- [Trip services](https://github.com/lochan87/spenza/blob/main/src/services/trips.ts): `src/services/trips.ts`
- [Recurring services](https://github.com/lochan87/spenza/blob/main/src/services/recurring.ts): `src/services/recurring.ts`
- [Budget services](https://github.com/lochan87/spenza/blob/main/src/services/budgets.ts): `src/services/budgets.ts`
- [Insight computation](https://github.com/lochan87/spenza/blob/main/src/services/insights.ts): `src/services/insights.ts`
- [Firestore data store](https://github.com/lochan87/spenza/blob/main/src/firebase/firestore.ts): `src/firebase/firestore.ts`

### Other components

- **User**
- **Firebase Auth**

## Connections

- User → Google sign-in: signs in
- Google sign-in → Firebase Auth: authenticates
- App routes → Authentication state: provides auth
- App routes → Google sign-in: routes to
- App routes → Protected app shell: wraps protected pages
- App routes → Onboarding seeds: runs on login
- App routes → Due-item prompts: checks due items
- User → Dashboard: reviews spending
- Dashboard → Dashboard data: requests data
- Dashboard data → Transaction services: fetches transactions
- Dashboard data → Firestore data store: reads data
- User → Transactions and categories: records expenses
- Transactions and categories → Transaction services: manages transactions
- User → Bulk import: uploads spreadsheet
- Bulk import → Import processing: parses and imports
- Import processing → Firestore data store: writes transactions
- User → Trip tracking: tracks trip spend
- Trip tracking → Trip services: manages trips
- User → Recurring expenses: manages recurring items
- App routes → Due-item prompts: mounts prompt check
- Due-item prompts → Recurring services: loads and advances items
- Due-item prompts → Transaction services: logs confirmed expense
- User → Monthly budgets: sets budgets
- Monthly budgets → Budget services: manages budgets
- User → Spending insights: reviews insights
- Spending insights → Insight computation: requests analysis
- User → CSV export: exports transactions
- Onboarding seeds → Firestore data store: seeds user data
- Transaction services → Firestore data store: reads and writes
- Trip services → Firestore data store: reads and writes
- Recurring services → Firestore data store: reads and writes
- Budget services → Firestore data store: reads and writes
- Insight computation → Firestore data store: reads and caches