How colinbertin/my-spending works
1. Overall shape
- This is a Next.js App Router finance application built with React + TypeScript.
- The repo is organized around three main layers: route/page composition in app/, shared UI and feature components in components/, and data/auth/ledger utilities in utils/, lib/, and helpers/.
2. Primary business domains
- The app centers on three finance entities: accounts, categories, and transactions.
- These entities support the core user workflow: create accounts and categories, record transactions, then inspect monthly activity and generate ledger outputs.
3. Routing and page boundaries
- app/(auth) contains the authentication-facing routes: login and signup.
- app/(routes) contains the authenticated application shell and all finance features: dashboard, accounts, categories, and ledger-generator.
- This route-group split is the main architectural boundary between public/auth and protected app sections.
4. Authentication and access control
- Authentication is handled through Supabase Auth, with supporting utilities in utils/authClient.ts, utils/authTypes.ts, utils/useAuthUser.ts, and utils/signupService.ts.
- middleware.ts plus utils/supabase/middleware.ts likely enforce session-aware routing and protect private pages.
- Supabase client/server/admin helpers in utils/supabase/ indicate a clear separation between browser access, server-side session handling, and privileged admin operations.
5. Data access layer
- CRUD operations for the finance entities are exposed through Next.js API routes under app/api/.
- There are dedicated endpoints for:
- accounts
- categories
- transactions
- Dynamic routes like app/api/accounts/[id]/route.ts and app/api/transactions/[id]/route.ts support per-record update/delete flows.
6. Database and backend platform
- The persistent backend is Supabase Postgres, with schema changes tracked in supabase/migrations/.
- The migration history shows schema evolution around:
- initial domain tables,
- linking users to auth identities,
- switching user references to auth-backed IDs,
- adding updated_at fields.
- This makes the backend architecture database-centric, with Supabase providing both auth and data storage.
7. UI composition and feature components
- Most interactive screens are assembled from reusable components in components/.
- There are feature-specific components for accounts, transactions, ledger preview, dialogs/forms, and visualizations.
- components/layout/ holds shared shell elements like the Navbar and Footer.
- components/ui/ contains lower-level primitives such as buttons, selects, popovers, and notifications.
8. Ledger generation subsystem
- app/(routes)/ledger-generator/ is a dedicated subsystem for accounting-style output.
- Supporting logic lives in lib/ledgerPreviewRows.ts and lib/ledgerXlsx.ts, suggesting two output modes:
- on-screen ledger preview
- exportable spreadsheet/XLSX generation
- The README also mentions PDF/print-ready output, so the ledger flow is not just data entry; it is a separate reporting/export pipeline.
9. Analytics and presentation flow
- The dashboard and account detail areas combine transaction data with visual summaries.
- Components like Chart, Doughnut, MonthlyTransactions, and TransactionList indicate the app transforms raw transaction records into:
- monthly summaries,
- category breakdowns,
- account activity views,
- detailed transaction listings.
- This is a read-heavy presentation layer sitting on top of the CRUD data model.
10. Form and modal interaction model
- Create/update flows are heavily modal and form driven, with components like Modal, ModalInputForm, ModalDetailsContent, and field primitives.
- This suggests user actions such as creating accounts, categories, and transactions are handled through reusable dialog/form patterns rather than separate full-page wizards.
11. Infrastructure and runtime concerns
- The app depends on environment variables for Supabase connection details, split between public browser access and a service-role key for privileged server operations.
- next.config.ts, middleware.ts, and the App Router loading/error/not-found files show the app uses standard Next.js runtime conventions for route-level loading, error handling, and fallback states.
12. Testing and quality gates
- Tests are colocated with implementation in many areas, especially pages/components and utility libraries.
- The repo uses Vitest and Testing Library, with CI support in .github/workflows/test.yml.
- This indicates the architecture is designed with unit/component testing around the most important user flows and utility transformations.
13. How data likely moves through the system
- A user interacts with a route page in app/(routes).
- That page composes feature components from components/.
- User actions trigger API routes in app/api/.
- API routes talk to Supabase through the helper layer in utils/supabase/.
- Retrieved records feed back into dashboards, account detail views, and ledger preview/export utilities in lib/.
14. Key architectural boundary to capture in a diagram
- The most important boundary is between presentation/interaction and persistent finance data:
- presentation: Next.js pages, shared components, charts, forms, modals
- persistence/auth: API routes, Supabase client/server/admin helpers, Postgres schema, Supabase Auth
- A second important boundary is the ledger generation path, which consumes finance data and emits accounting/reporting artifacts rather than ordinary CRUD screens.
Main entry points: client.ts Supabase clients · route.ts Transactions API · details/page.tsx Accounts · ledger-generator/page.tsx Ledger generator
Components 19
Auth routes
Public sign-in and sign-up pages.
App routes
Protected finance application routes and shells.
- App shell · Authenticated layout and shared route scaffolding.
app/(routes)/layout.tsx - Dashboard · Main read-heavy finance dashboard.
app/(routes)/dashboard.tsx - Accounts · Account creation and account detail routes.
app/(routes)/accounts/[id]/details/page.tsx - Categories · Category creation flow and category screens.
app/(routes)/categories/create/page.tsx - Ledger generator · Dedicated ledger reporting and generation routes.
app/(routes)/ledger-generator/page.tsx
API routes
CRUD endpoints for finance entities.
- Accounts API · Accounts CRUD endpoints.
app/api/accounts/route.ts - Categories API · Categories CRUD endpoint.
app/api/categories/route.ts - Transactions API · Transactions CRUD endpoints, including per-record operations.
app/api/transactions/route.ts
UI components
Shared screens, forms, charts, and layout pieces.
- Navbar · Primary navigation shell for the app.
components/layout/Navbar.tsx - Forms · Reusable modal and form components for create/update flows.
components/ModalInputForm.tsx - Analytics UI · Charts, summaries, and transaction presentation components.
components/Chart.tsx - Ledger UI · Ledger preview table and export buttons.
components/LedgerPreviewTable.tsx
Data and auth
Auth helpers, Supabase access, and domain utilities.
- Auth helpers · Client auth, user hook, signup service, and auth types.
utils/authClient.ts - Supabase clients · Browser, server, middleware, and admin Supabase helpers.
utils/supabase/client.ts - Middleware · Session-aware routing and protection for private pages.
middleware.ts
Ledger pipeline
Preview and export flow for accounting output.
- Ledger logic · Ledger preview row shaping and XLSX generation utilities.
lib/ledgerPreviewRows.ts
Backend schema
Database migrations and Supabase persistence layer.
- Supabase schema · Database migrations defining finance tables and auth-linked user references.
supabase/migrations/20260205095113_init_schema.sql
Connections 22
- Login → Auth helpers: auth flow · Login UI uses shared auth utilities.
- Signup → Auth helpers: signup flow · Signup UI delegates to auth helpers and signup service.
- App shell → Navbar: shell · Authenticated routes compose the shared navigation shell.
- Dashboard → Analytics UI: summaries · Dashboard renders charts and activity summaries.
- Accounts → Forms: edit/create · Account routes use shared modal form patterns.
- Categories → Forms: edit/create · Category screens use reusable form components.
- Accounts → Accounts API: CRUD · Account screens talk to the accounts API.
- Categories → Categories API: CRUD · Category screens talk to the categories API.
- Accounts → Transactions API: transactions · Account detail routes depend on transaction endpoints.
- Dashboard → Transactions API: activity · Dashboard reads transaction data for monthly views.
- Analytics UI → Transactions API: data · Charts and lists consume transaction records.
- Ledger generator → Ledger UI: preview · Ledger routes render preview and export controls.
- Ledger generator → Ledger logic: transform · Ledger routes use row shaping and spreadsheet generation logic.
- Ledger UI → Ledger logic: export · UI actions trigger XLSX and print-oriented generation.
- Accounts API → Supabase clients: storage · Accounts API uses Supabase helpers for persistence.
- Categories API → Supabase clients: storage · Categories API uses Supabase helpers for persistence.
- Transactions API → Supabase clients: storage · Transactions API uses Supabase helpers for persistence.
- Supabase clients → Supabase schema: schema · Supabase access targets the migrated Postgres schema.
- Auth helpers → Supabase clients: sessions · Auth helpers rely on Supabase client/server wrappers.
- Middleware → Supabase clients: guards · Middleware uses Supabase session middleware helpers.
- App shell → Middleware: protected · Protected app routes are gated by middleware.
- Ledger generator → Transactions API: source data · Ledger generation consumes finance transaction data.