# colinbertin/my-spending architecture

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

- Interactive diagram: https://gitdiagram.com/colinbertin/my-spending
- Repository: https://github.com/colinbertin/my-spending

## Overview

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: [`utils/supabase/client.ts`](https://github.com/colinbertin/my-spending/blob/main/utils/supabase/client.ts) (Supabase clients), [`app/api/transactions/route.ts`](https://github.com/colinbertin/my-spending/blob/main/app/api/transactions/route.ts) (Transactions API), [`app/(routes)/accounts/[id]/details/page.tsx`](https://github.com/colinbertin/my-spending/blob/main/app/(routes)/accounts/[id]/details/page.tsx) (Accounts), [`app/(routes)/ledger-generator/page.tsx`](https://github.com/colinbertin/my-spending/blob/main/app/(routes)/ledger-generator/page.tsx) (Ledger generator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_app_auth["Auth routes"]
  node_node_auth_login["Login<br/>auth page<br/>[page.tsx]"]
  node_node_auth_signup["Signup<br/>auth page<br/>[page.tsx]"]
end

subgraph group_group_app_routes["App routes"]
  node_node_app_layout["App shell<br/>route shell<br/>[layout.tsx]"]
  node_node_dashboard["Dashboard<br/>overview page<br/>[dashboard.tsx]"]
  node_node_accounts["Accounts<br/>account routes<br/>[page.tsx]"]
  node_node_categories["Categories<br/>category routes<br/>[page.tsx]"]
  node_node_ledger_route["Ledger generator<br/>report route<br/>[page.tsx]"]
end

subgraph group_group_api["API routes"]
  node_node_api_accounts[("Accounts API<br/>REST endpoint<br/>[route.ts]")]
  node_node_api_categories[("Categories API<br/>REST endpoint<br/>[route.ts]")]
  node_node_api_transactions[("Transactions API<br/>REST endpoint<br/>[route.ts]")]
end

subgraph group_group_components["UI components"]
  node_node_layout["Navbar<br/>layout component<br/>[Navbar.tsx]"]
  node_node_forms["Forms<br/>form/modals<br/>[ModalInputForm.tsx]"]
  node_node_visuals["Analytics UI<br/>charts/listings<br/>[Chart.tsx]"]
  node_node_ledger_ui["Ledger UI<br/>export ui"]
end

subgraph group_group_data["Data and auth"]
  node_node_auth_utils["Auth helpers<br/>supabase auth<br/>[authClient.ts]"]
  node_node_supabase_clients["Supabase clients<br/>server/client helpers<br/>[client.ts]"]
  node_node_middleware["Middleware<br/>route guard<br/>[middleware.ts]"]
end

subgraph group_group_ledger["Ledger pipeline"]
  node_node_ledger_lib["Ledger logic<br/>report transforms"]
end

subgraph group_group_backend["Backend schema"]
  node_node_db_schema[("Supabase schema<br/>postgres migrations")]
end

node_node_auth_login -->|"auth flow"| node_node_auth_utils
node_node_auth_signup -->|"signup flow"| node_node_auth_utils
node_node_app_layout -->|"shell"| node_node_layout
node_node_dashboard -->|"summaries"| node_node_visuals
node_node_accounts -->|"edit/create"| node_node_forms
node_node_categories -->|"edit/create"| node_node_forms
node_node_accounts -->|"CRUD"| node_node_api_accounts
node_node_categories -->|"CRUD"| node_node_api_categories
node_node_accounts -->|"transactions"| node_node_api_transactions
node_node_dashboard -->|"activity"| node_node_api_transactions
node_node_visuals -->|"data"| node_node_api_transactions
node_node_ledger_route -->|"preview"| node_node_ledger_ui
node_node_ledger_route -->|"transform"| node_node_ledger_lib
node_node_ledger_ui -->|"export"| node_node_ledger_lib
node_node_api_accounts -->|"storage"| node_node_supabase_clients
node_node_api_categories -->|"storage"| node_node_supabase_clients
node_node_api_transactions -->|"storage"| node_node_supabase_clients
node_node_supabase_clients -->|"schema"| node_node_db_schema
node_node_auth_utils -->|"sessions"| node_node_supabase_clients
node_node_middleware -->|"guards"| node_node_supabase_clients
node_node_app_layout -->|"protected"| node_node_middleware
node_node_ledger_route -->|"source data"| node_node_api_transactions

click node_node_auth_login "https://github.com/colinbertin/my-spending/blob/main/app/(auth)/login/page.tsx"
click node_node_auth_signup "https://github.com/colinbertin/my-spending/blob/main/app/(auth)/signup/page.tsx"
click node_node_app_layout "https://github.com/colinbertin/my-spending/blob/main/app/(routes)/layout.tsx"
click node_node_dashboard "https://github.com/colinbertin/my-spending/blob/main/app/(routes)/dashboard.tsx"
click node_node_accounts "https://github.com/colinbertin/my-spending/blob/main/app/(routes)/accounts/[id]/details/page.tsx"
click node_node_categories "https://github.com/colinbertin/my-spending/blob/main/app/(routes)/categories/create/page.tsx"
click node_node_ledger_route "https://github.com/colinbertin/my-spending/blob/main/app/(routes)/ledger-generator/page.tsx"
click node_node_api_accounts "https://github.com/colinbertin/my-spending/blob/main/app/api/accounts/route.ts"
click node_node_api_categories "https://github.com/colinbertin/my-spending/blob/main/app/api/categories/route.ts"
click node_node_api_transactions "https://github.com/colinbertin/my-spending/blob/main/app/api/transactions/route.ts"
click node_node_layout "https://github.com/colinbertin/my-spending/blob/main/components/layout/Navbar.tsx"
click node_node_forms "https://github.com/colinbertin/my-spending/blob/main/components/ModalInputForm.tsx"
click node_node_visuals "https://github.com/colinbertin/my-spending/blob/main/components/Chart.tsx"
click node_node_ledger_ui "https://github.com/colinbertin/my-spending/blob/main/components/LedgerPreviewTable.tsx"
click node_node_auth_utils "https://github.com/colinbertin/my-spending/blob/main/utils/authClient.ts"
click node_node_supabase_clients "https://github.com/colinbertin/my-spending/blob/main/utils/supabase/client.ts"
click node_node_ledger_lib "https://github.com/colinbertin/my-spending/blob/main/lib/ledgerPreviewRows.ts"
click node_node_db_schema "https://github.com/colinbertin/my-spending/blob/main/supabase/migrations/20260205095113_init_schema.sql"
click node_node_middleware "https://github.com/colinbertin/my-spending/blob/main/middleware.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_node_auth_login,node_node_auth_signup,node_node_db_schema toneBlue
class node_node_app_layout,node_node_dashboard,node_node_accounts,node_node_categories,node_node_ledger_route toneAmber
class node_node_api_accounts,node_node_api_categories,node_node_api_transactions toneMint
class node_node_layout,node_node_forms,node_node_visuals,node_node_ledger_ui toneRose
class node_node_auth_utils,node_node_supabase_clients,node_node_middleware toneIndigo
class node_node_ledger_lib toneTeal
```

## Components

### Auth routes

Public sign-in and sign-up pages.

- [Login](https://github.com/colinbertin/my-spending/blob/main/app/(auth)/login/page.tsx): auth page · Login route and form composition. · `app/(auth)/login/page.tsx`
- [Signup](https://github.com/colinbertin/my-spending/blob/main/app/(auth)/signup/page.tsx): auth page · Signup route and form composition. · `app/(auth)/signup/page.tsx`

### App routes

Protected finance application routes and shells.

- [App shell](https://github.com/colinbertin/my-spending/blob/main/app/(routes)/layout.tsx): route shell · Authenticated layout and shared route scaffolding. · `app/(routes)/layout.tsx`
- [Dashboard](https://github.com/colinbertin/my-spending/blob/main/app/(routes)/dashboard.tsx): overview page · Main read-heavy finance dashboard. · `app/(routes)/dashboard.tsx`
- [Accounts](https://github.com/colinbertin/my-spending/blob/main/app/(routes)/accounts/[id]/details/page.tsx): account routes · Account creation and account detail routes. · `app/(routes)/accounts/[id]/details/page.tsx`
- [Categories](https://github.com/colinbertin/my-spending/blob/main/app/(routes)/categories/create/page.tsx): category routes · Category creation flow and category screens. · `app/(routes)/categories/create/page.tsx`
- [Ledger generator](https://github.com/colinbertin/my-spending/blob/main/app/(routes)/ledger-generator/page.tsx): report route · Dedicated ledger reporting and generation routes. · `app/(routes)/ledger-generator/page.tsx`

### API routes

CRUD endpoints for finance entities.

- [Accounts API](https://github.com/colinbertin/my-spending/blob/main/app/api/accounts/route.ts): REST endpoint · Accounts CRUD endpoints. · `app/api/accounts/route.ts`
- [Categories API](https://github.com/colinbertin/my-spending/blob/main/app/api/categories/route.ts): REST endpoint · Categories CRUD endpoint. · `app/api/categories/route.ts`
- [Transactions API](https://github.com/colinbertin/my-spending/blob/main/app/api/transactions/route.ts): REST endpoint · Transactions CRUD endpoints, including per-record operations. · `app/api/transactions/route.ts`

### UI components

Shared screens, forms, charts, and layout pieces.

- [Navbar](https://github.com/colinbertin/my-spending/blob/main/components/layout/Navbar.tsx): layout component · Primary navigation shell for the app. · `components/layout/Navbar.tsx`
- [Forms](https://github.com/colinbertin/my-spending/blob/main/components/ModalInputForm.tsx): form/modals · Reusable modal and form components for create/update flows. · `components/ModalInputForm.tsx`
- [Analytics UI](https://github.com/colinbertin/my-spending/blob/main/components/Chart.tsx): charts/listings · Charts, summaries, and transaction presentation components. · `components/Chart.tsx`
- [Ledger UI](https://github.com/colinbertin/my-spending/blob/main/components/LedgerPreviewTable.tsx): export ui · Ledger preview table and export buttons. · `components/LedgerPreviewTable.tsx`

### Data and auth

Auth helpers, Supabase access, and domain utilities.

- [Auth helpers](https://github.com/colinbertin/my-spending/blob/main/utils/authClient.ts): supabase auth · Client auth, user hook, signup service, and auth types. · `utils/authClient.ts`
- [Supabase clients](https://github.com/colinbertin/my-spending/blob/main/utils/supabase/client.ts): server/client helpers · Browser, server, middleware, and admin Supabase helpers. · `utils/supabase/client.ts`
- [Middleware](https://github.com/colinbertin/my-spending/blob/main/middleware.ts): route guard · Session-aware routing and protection for private pages. · `middleware.ts`

### Ledger pipeline

Preview and export flow for accounting output.

- [Ledger logic](https://github.com/colinbertin/my-spending/blob/main/lib/ledgerPreviewRows.ts): report transforms · Ledger preview row shaping and XLSX generation utilities. · `lib/ledgerPreviewRows.ts`

### Backend schema

Database migrations and Supabase persistence layer.

- [Supabase schema](https://github.com/colinbertin/my-spending/blob/main/supabase/migrations/20260205095113_init_schema.sql): postgres migrations · Database migrations defining finance tables and auth-linked user references. · `supabase/migrations/20260205095113_init_schema.sql`

## Connections

- 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.
