theboywai/blackbook

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.