# theboywai/blackbook architecture

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

- Interactive diagram: https://gitdiagram.com/theboywai/blackbook
- Repository: https://github.com/theboywai/blackbook

## Overview

1. **Overall shape**  
   This is a Vite + React single-page app with a small serverless API surface under `api/`, backed by Supabase. The browser app handles all user-facing finance workflows; Supabase is the system of record for auth and persisted finance data.

2. **Application shell and routing**  
   `src/main.jsx`, `src/App.jsx`, and `src/pages/*` define the client app’s route-level structure. `src/components/Layout.jsx` is the persistent shell: it provides navigation, the sticky status area, and shared chrome around all pages.

3. **Authentication boundary**  
   `src/hooks/useAuth.js` plus `src/lib/supabase.js` implement email/password login, session persistence, and protected-route behavior. `src/pages/Login.jsx`, `Setup.jsx`, and `Settings.jsx` sit on the auth/onboarding edge, while the rest of the pages assume an authenticated session.

4. **State access and domain hooks**  
   The app uses feature-specific hooks as the main data-access layer: `useDashboard`, `useTransactions`, `useBudgets`, `useCategories`, `useCorpus`, `useReview`, `useLastUpload`, and `useTrips`. These hooks encapsulate fetching, mutation, and derived state so pages stay mostly declarative.

5. **Domain model and schema-aligned data files**  
   `src/data/*` mirrors the finance domain: accounts, budgets, categories, investments, merchants, splits, transactions, trips, and uploads. These files act as canonical shapes/seed data for the UI and analytics logic, while `src/constants/categories.js` centralizes categorization taxonomy.

6. **Analytics and metric computation layer**  
   `src/analytics/*` is the calculation engine for dashboards and reports. It computes summaries such as overview KPIs, spend breakdowns, budget performance, trends, corpus/investment views, and insights; the UI consumes these derived outputs rather than raw rows.

7. **Dashboard and shared UI components**  
   `src/pages/Dashboard.jsx` combines KPI cards, charts, insight cards, budget bars, top merchants, and weekly history. Shared primitives in `src/components/*`—for example `KPICard`, `SpendChart`, `InsightCard`, `TxnRow`, `Tooltip`, and `Card`—form the reusable presentation layer across the app.

8. **Transaction and review workflow**  
   `src/pages/Transactions.jsx` shows the full ledger with search, category/direction filtering, and running net. `src/pages/Review.jsx` is the exception-handling queue where uncategorized or uncertain transactions are assigned categories; it also supports merchant promotion, which writes UPI/merchant metadata back to the database.

9. **Budget control and configuration**  
   `src/pages/Budget.jsx` and `src/pages/Settings.jsx` are the budget-management boundary. The budget page aggregates corpus, account-level cards, month-to-date totals, safe-to-spend, and projection; settings lets users edit budget limits inline and persist them immediately.

10. **Ingestion, assistant, and deployment surfaces**  
   The repo includes `api/upload.js` and `api/finance-chat.js` as serverless endpoints, with a separate `api/package.json` indicating a Node runtime boundary distinct from the SPA. The README also describes an upstream ingestion pipeline that converts PDFs through validation/categorization into Supabase, with reconciliation, deduplication, and internal-transfer detection; the UI’s sync indicator and review badge reflect that ingestion state. Deployment is configured for Vercel via `vercel.json`, and the app expects environment-backed Supabase credentials from `.env.example`.

Main entry points: [`src/App.jsx`](https://github.com/theboywai/blackbook/blob/main/src/App.jsx) (Router), [`src/pages/Dashboard.jsx`](https://github.com/theboywai/blackbook/blob/main/src/pages/Dashboard.jsx) (Dashboard), [`src/pages/Budget.jsx`](https://github.com/theboywai/blackbook/blob/main/src/pages/Budget.jsx) (Budget), [`src/pages/Review.jsx`](https://github.com/theboywai/blackbook/blob/main/src/pages/Review.jsx) (Review)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_shell["App shell"]
  node_main["Entry<br/>[main.jsx]"]
  node_app["Router<br/>spa routes<br/>[App.jsx]"]
  node_layout["Layout<br/>shared shell<br/>[Layout.jsx]"]
end

subgraph group_auth["Auth boundary"]
  node_login["Login<br/>auth page<br/>[Login.jsx]"]
  node_setup["Setup<br/>onboarding page<br/>[Setup.jsx]"]
  node_settings["Settings<br/>preferences page<br/>[Settings.jsx]"]
  node_authhook{{"Auth hook<br/>session logic<br/>[useAuth.js]"}}
  node_supabase[("Supabase<br/>backend client<br/>[supabase.js]")]
end

subgraph group_domain["Domain layer"]
  node_dashboard["Dashboard<br/>overview page<br/>[Dashboard.jsx]"]
  node_transactions["Transactions<br/>ledger page<br/>[Transactions.jsx]"]
  node_review["Review<br/>exception queue<br/>[Review.jsx]"]
  node_budget["Budget<br/>[Budget.jsx]"]
  node_investments["Investments<br/>portfolio page<br/>[Investments.jsx]"]
  node_travel["Travel<br/>trip page<br/>[Travel.jsx]"]
  node_upload["Upload<br/>ingestion page<br/>[Upload.jsx]"]
  node_assistant["Assistant<br/>chat page"]
  node_usehooks{{"Feature hooks<br/>data access"}}
  node_domainfiles[("Finance data<br/>domain shapes")]
  node_taxonomy["Categories<br/>taxonomy<br/>[categories.js]"]
end

subgraph group_analytics["Analytics engine"]
  node_overviewcalc{{"Overview calc<br/>metrics engine<br/>[overview.js]"}}
  node_spendcalc{{"Spend calc<br/>metrics engine<br/>[spend.js]"}}
  node_budgetcalc{{"Budget calc<br/>metrics engine<br/>[budget.js]"}}
  node_trendcalc{{"Trend calc<br/>metrics engine<br/>[trends.js]"}}
  node_corpuscalc{{"Corpus calc<br/>metrics engine<br/>[corpus.js]"}}
  node_insightcalc{{"Insights<br/>metrics engine<br/>[insights.js]"}}
  node_investcalc{{"Invest calc<br/>metrics engine<br/>[investments.js]"}}
end

subgraph group_server["API and deploy"]
  node_uploadapi["Upload API<br/>serverless fn<br/>[upload.js]"]
  node_chatapi["Chat API<br/>serverless fn<br/>[finance-chat.js]"]
  node_apipkg["API runtime<br/>node boundary<br/>[package.json]"]
  node_vitecfg["Vite config<br/>build config<br/>[vite.config.js]"]
  node_vercelcfg["Vercel config<br/>deploy config<br/>[vercel.json]"]
end

node_main -->|"mounts"| node_app
node_app -->|"wraps"| node_layout
node_app -->|"routes"| node_login
node_app -->|"routes"| node_setup
node_app -->|"routes"| node_settings
node_app -->|"routes"| node_dashboard
node_app -->|"routes"| node_transactions
node_app -->|"routes"| node_review
node_app -->|"routes"| node_budget
node_app -->|"routes"| node_investments
node_app -->|"routes"| node_travel
node_app -->|"routes"| node_upload
node_app -->|"routes"| node_assistant
node_login -->|"uses"| node_authhook
node_setup -->|"uses"| node_authhook
node_settings -->|"uses"| node_authhook
node_authhook -->|"authenticates"| node_supabase
node_usehooks -->|"reads/writes"| node_supabase
node_dashboard -->|"consumes"| node_usehooks
node_dashboard -->|"derives"| node_overviewcalc
node_dashboard -->|"derives"| node_spendcalc
node_dashboard -->|"derives"| node_trendcalc
node_dashboard -->|"derives"| node_insightcalc
node_transactions -->|"consumes"| node_usehooks
node_review -->|"consumes"| node_usehooks
node_review -->|"applies"| node_taxonomy
node_budget -->|"consumes"| node_usehooks
node_budget -->|"derives"| node_budgetcalc
node_budget -->|"derives"| node_corpuscalc
node_investments -->|"consumes"| node_usehooks
node_investments -->|"derives"| node_investcalc
node_travel -->|"consumes"| node_usehooks
node_upload -->|"calls"| node_uploadapi
node_assistant -->|"calls"| node_chatapi
node_uploadapi -->|"runs in"| node_apipkg
node_chatapi -->|"runs in"| node_apipkg
node_vitecfg -->|"builds"| node_main
node_vercelcfg -->|"deploys"| node_uploadapi
node_vercelcfg -->|"deploys"| node_chatapi
node_domainfiles -->|"aligns"| node_taxonomy
node_domainfiles -->|"feeds"| node_usehooks
node_domainfiles -->|"supports"| node_review
node_domainfiles -->|"feeds"| node_budgetcalc
node_domainfiles -->|"feeds"| node_corpuscalc

click node_main "https://github.com/theboywai/blackbook/blob/main/src/main.jsx"
click node_app "https://github.com/theboywai/blackbook/blob/main/src/App.jsx"
click node_layout "https://github.com/theboywai/blackbook/blob/main/src/components/Layout.jsx"
click node_login "https://github.com/theboywai/blackbook/blob/main/src/pages/Login.jsx"
click node_setup "https://github.com/theboywai/blackbook/blob/main/src/pages/Setup.jsx"
click node_settings "https://github.com/theboywai/blackbook/blob/main/src/pages/Settings.jsx"
click node_authhook "https://github.com/theboywai/blackbook/blob/main/src/hooks/useAuth.js"
click node_supabase "https://github.com/theboywai/blackbook/blob/main/src/lib/supabase.js"
click node_dashboard "https://github.com/theboywai/blackbook/blob/main/src/pages/Dashboard.jsx"
click node_transactions "https://github.com/theboywai/blackbook/blob/main/src/pages/Transactions.jsx"
click node_review "https://github.com/theboywai/blackbook/blob/main/src/pages/Review.jsx"
click node_budget "https://github.com/theboywai/blackbook/blob/main/src/pages/Budget.jsx"
click node_investments "https://github.com/theboywai/blackbook/blob/main/src/pages/Investments.jsx"
click node_travel "https://github.com/theboywai/blackbook/blob/main/src/pages/Travel.jsx"
click node_upload "https://github.com/theboywai/blackbook/blob/main/src/pages/Upload.jsx"
click node_assistant "https://github.com/theboywai/blackbook/blob/main/src/pages/FinanceAssistant.jsx"
click node_taxonomy "https://github.com/theboywai/blackbook/blob/main/src/constants/categories.js"
click node_overviewcalc "https://github.com/theboywai/blackbook/blob/main/src/analytics/overview.js"
click node_spendcalc "https://github.com/theboywai/blackbook/blob/main/src/analytics/spend.js"
click node_budgetcalc "https://github.com/theboywai/blackbook/blob/main/src/analytics/budget.js"
click node_trendcalc "https://github.com/theboywai/blackbook/blob/main/src/analytics/trends.js"
click node_corpuscalc "https://github.com/theboywai/blackbook/blob/main/src/analytics/corpus.js"
click node_insightcalc "https://github.com/theboywai/blackbook/blob/main/src/analytics/insights.js"
click node_investcalc "https://github.com/theboywai/blackbook/blob/main/src/analytics/investments.js"
click node_uploadapi "https://github.com/theboywai/blackbook/blob/main/api/upload.js"
click node_chatapi "https://github.com/theboywai/blackbook/blob/main/api/finance-chat.js"
click node_apipkg "https://github.com/theboywai/blackbook/blob/main/api/package.json"
click node_vitecfg "https://github.com/theboywai/blackbook/blob/main/vite.config.js"
click node_vercelcfg "https://github.com/theboywai/blackbook/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_main,node_app,node_layout toneBlue
class node_login,node_setup,node_settings,node_authhook,node_supabase toneAmber
class node_dashboard,node_transactions,node_review,node_budget,node_investments,node_travel,node_upload,node_assistant,node_usehooks,node_domainfiles,node_taxonomy toneMint
class node_overviewcalc,node_spendcalc,node_budgetcalc,node_trendcalc,node_corpuscalc,node_insightcalc,node_investcalc toneRose
class node_uploadapi,node_chatapi,node_apipkg,node_vitecfg,node_vercelcfg toneIndigo
```

## Components

### App shell

Client entry, routing, and shared UI chrome.

- [Entry](https://github.com/theboywai/blackbook/blob/main/src/main.jsx): vite entry · Bootstraps the React app. · `src/main.jsx`
- [Router](https://github.com/theboywai/blackbook/blob/main/src/App.jsx): spa routes · Defines top-level navigation and page routing. · `src/App.jsx`
- [Layout](https://github.com/theboywai/blackbook/blob/main/src/components/Layout.jsx): shared shell · Persistent chrome, navigation, and status area. · `src/components/Layout.jsx`

### Auth boundary

Session handling and auth-adjacent screens.

- [Login](https://github.com/theboywai/blackbook/blob/main/src/pages/Login.jsx): auth page · Email/password sign-in surface. · `src/pages/Login.jsx`
- [Setup](https://github.com/theboywai/blackbook/blob/main/src/pages/Setup.jsx): onboarding page · Initial account and profile setup. · `src/pages/Setup.jsx`
- [Settings](https://github.com/theboywai/blackbook/blob/main/src/pages/Settings.jsx): preferences page · Budget and account configuration boundary. · `src/pages/Settings.jsx`
- [Auth hook](https://github.com/theboywai/blackbook/blob/main/src/hooks/useAuth.js): session logic · Session persistence and protected-route behavior. · `src/hooks/useAuth.js`
- [Supabase](https://github.com/theboywai/blackbook/blob/main/src/lib/supabase.js): backend client · System of record for auth and persisted finance data. · `src/lib/supabase.js`

### Domain layer

Feature hooks and canonical finance data shapes.

- [Dashboard](https://github.com/theboywai/blackbook/blob/main/src/pages/Dashboard.jsx): overview page · Main KPI and insight view. · `src/pages/Dashboard.jsx`
- [Transactions](https://github.com/theboywai/blackbook/blob/main/src/pages/Transactions.jsx): ledger page · Full transaction list with filters and running net. · `src/pages/Transactions.jsx`
- [Review](https://github.com/theboywai/blackbook/blob/main/src/pages/Review.jsx): exception queue · Categorization and merchant promotion workflow. · `src/pages/Review.jsx`
- [Budget](https://github.com/theboywai/blackbook/blob/main/src/pages/Budget.jsx): budget page · Budget control and safe-to-spend view. · `src/pages/Budget.jsx`
- [Investments](https://github.com/theboywai/blackbook/blob/main/src/pages/Investments.jsx): portfolio page · Corpus and investment view. · `src/pages/Investments.jsx`
- [Travel](https://github.com/theboywai/blackbook/blob/main/src/pages/Travel.jsx): trip page · Trip-oriented finance and tracking view. · `src/pages/Travel.jsx`
- [Upload](https://github.com/theboywai/blackbook/blob/main/src/pages/Upload.jsx): ingestion page · Document upload and sync surface. · `src/pages/Upload.jsx`
- [Assistant](https://github.com/theboywai/blackbook/blob/main/src/pages/FinanceAssistant.jsx): chat page · Finance chat interface over the app data. · `src/pages/FinanceAssistant.jsx`
- **Feature hooks**: data access · Feature-specific fetching, mutation, and derived state hooks.
- **Finance data**: domain shapes · Canonical finance records and seed-aligned data files.
- [Categories](https://github.com/theboywai/blackbook/blob/main/src/constants/categories.js): taxonomy · Central categorization rules and labels. · `src/constants/categories.js`

### Analytics engine

Derived metrics and reporting computations.

- [Overview calc](https://github.com/theboywai/blackbook/blob/main/src/analytics/overview.js): metrics engine · Dashboard KPIs and summary computations. · `src/analytics/overview.js`
- [Spend calc](https://github.com/theboywai/blackbook/blob/main/src/analytics/spend.js): metrics engine · Spending breakdown and category analysis. · `src/analytics/spend.js`
- [Budget calc](https://github.com/theboywai/blackbook/blob/main/src/analytics/budget.js): metrics engine · Budget performance and projection logic. · `src/analytics/budget.js`
- [Trend calc](https://github.com/theboywai/blackbook/blob/main/src/analytics/trends.js): metrics engine · Temporal trends and weekly history. · `src/analytics/trends.js`
- [Corpus calc](https://github.com/theboywai/blackbook/blob/main/src/analytics/corpus.js): metrics engine · Net worth and corpus views. · `src/analytics/corpus.js`
- [Insights](https://github.com/theboywai/blackbook/blob/main/src/analytics/insights.js): metrics engine · Derived recommendations and notable signals. · `src/analytics/insights.js`
- [Invest calc](https://github.com/theboywai/blackbook/blob/main/src/analytics/investments.js): metrics engine · Investment-related derived outputs. · `src/analytics/investments.js`

### API and deploy

Serverless endpoints and runtime/deployment config.

- [Upload API](https://github.com/theboywai/blackbook/blob/main/api/upload.js): serverless fn · Upload ingestion endpoint. · `api/upload.js`
- [Chat API](https://github.com/theboywai/blackbook/blob/main/api/finance-chat.js): serverless fn · Assistant/chat endpoint. · `api/finance-chat.js`
- [API runtime](https://github.com/theboywai/blackbook/blob/main/api/package.json): node boundary · Separate Node package/runtime boundary for serverless functions. · `api/package.json`
- [Vite config](https://github.com/theboywai/blackbook/blob/main/vite.config.js): build config · Client build and dev-server configuration. · `vite.config.js`
- [Vercel config](https://github.com/theboywai/blackbook/blob/main/vercel.json): deploy config · Deployment configuration for the hosted app. · `vercel.json`

## Connections

- Entry → Router: mounts · Bootstraps the routed application.
- Router → Layout: wraps · All pages render inside the shared shell.
- Router → Login: routes · Public auth entry point.
- Router → Setup: routes · Onboarding flow.
- Router → Settings: routes · Config and account settings.
- Router → Dashboard: routes · Primary app landing page.
- Router → Transactions: routes · Ledger view.
- Router → Review: routes · Exception handling queue.
- Router → Budget: routes · Budget management page.
- Router → Investments: routes · Portfolio page.
- Router → Travel: routes · Trip finance page.
- Router → Upload: routes · Ingestion surface.
- Router → Assistant: routes · Chat assistant page.
- Login → Auth hook: uses · Sign-in and session handling.
- Setup → Auth hook: uses · Requires authenticated session.
- Settings → Auth hook: uses · Protected settings flow.
- Auth hook → Supabase: authenticates · Session and credentials are managed through Supabase.
- Feature hooks → Supabase: reads/writes · Feature hooks coordinate persistence and fetches.
- Dashboard → Feature hooks: consumes · Reads dashboard state through feature hooks.
- Dashboard → Overview calc: derives · KPI and summary computations.
- Dashboard → Spend calc: derives · Spend breakdowns and charts.
- Dashboard → Trend calc: derives · Weekly and time-series views.
- Dashboard → Insights: derives · Insight cards.
- Transactions → Feature hooks: consumes · Ledger data and filters.
- Review → Feature hooks: consumes · Review queue and mutation actions.
- Review → Categories: applies · Assigns canonical categories and merchant metadata.
- Budget → Feature hooks: consumes · Budget state and inline edits.
- Budget → Budget calc: derives · Budget bars, projections, and safe-to-spend.
- Budget → Corpus calc: derives · Corpus context for budget planning.
- Investments → Feature hooks: consumes · Investment and corpus data.
- Investments → Invest calc: derives · Portfolio-specific metrics.
- Travel → Feature hooks: consumes · Trip-related data.
- Upload → Upload API: calls · Submits document ingestion requests.
- Assistant → Chat API: calls · Requests finance chat completions.
- Upload API → API runtime: runs in · Serverless Node runtime boundary.
- Chat API → API runtime: runs in · Serverless Node runtime boundary.
- Vite config → Entry: builds · Client bundling and dev server configuration.
- Vercel config → Upload API: deploys · Exposes serverless endpoints in deployment.
- Vercel config → Chat API: deploys · Exposes serverless endpoints in deployment.
- Finance data → Categories: aligns · Domain records follow the shared categorization model.
- Finance data → Feature hooks: feeds · Hooks read and shape canonical finance records.
- Finance data → Review: supports · Review workflow acts on transaction and merchant data.
- Finance data → Budget calc: feeds · Budget metrics consume canonical finance records.
- Finance data → Corpus calc: feeds · Corpus metrics consume canonical finance records.