# zubayer-hossain/household-finance architecture

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

- Interactive diagram: https://gitdiagram.com/zubayer-hossain/household-finance
- Repository: https://github.com/zubayer-hossain/household-finance

## Overview

1. This is a Next.js 15 App Router application backed by Supabase. The repo is a household-first budgeting MVP, with a clear split between public auth flows, an onboarding path, and the authenticated app area.

2. The route structure is intentionally segmented:
   - `src/app/(public)`-style pages for login, signup, password reset, invite acceptance, and callback handling
   - `src/app/onboarding` for first-time household setup
   - `src/app/app` for the authenticated workspace, including dashboard, household, members, transactions, categories, and budgets
   - `src/app/api/household/*` for server-only household invite utilities

3. Authentication and session handling are isolated in `src/features/auth`. That feature owns forms, session listeners, profile fetching, password setup for invite flows, and auth guards/redirect components. It uses the Supabase client split in `src/services/supabase-browser.ts`, `supabase-server.ts`, and `supabase-middleware.ts` depending on whether code runs in the browser, server, or middleware.

4. The household subsystem is the core domain boundary. It covers household creation, membership management, member rosters, invite workflows, permission gates, onboarding/bootstrap UI, and deletion/rename flows. The invite lifecycle has a server-side helper for sending mail and an API layer for invite, resend, and invited-name updates. There is also a shared library for finalizing pending household invites.

5. Feature modules follow a consistent layered shape:
   - `components` for UI composition
   - `hooks` for query/mutation orchestration
   - `services` for Supabase/RPC access
   - `schemas` for validation
   - `lib` for domain calculations and selectors
   - `tests` for logic and policy coverage
   This makes the architecture easy to diagram as UI → hooks → services → Supabase/database.

6. Budgets is the largest product module. It includes index/detail routes, budget summary and category cards, health/status indicators, permission gates, monthly close, approval, reallocation, and adjustment flows. The `lib` layer holds budget aggregates, selectors, and health calculations, while the tests focus on permissions, reallocation, adjustment, and derived-state correctness.

7. Categories is a separate household-level domain. It handles category CRUD, archive/unarchive, reorder, draft-budget cleanup, and templates/prefill behavior. The feature includes its own permission gates, lifecycle dialogs, and a dedicated service layer, which suggests categories are a foundational model shared by later budgeting flows.

8. Transactions is another major subsystem and is more interaction-heavy than the others. It supports transaction lists, filtering, create/edit/delete, detail sheets, quick-add expense UI, category assignment, and attachment upload/delete. The attachment flow is likely backed by Supabase Storage, while transaction permissions and list statistics live in the feature’s `lib` and `tests`.

9. Dashboard and shell are cross-cutting presentation layers. `src/components/shell` provides the authenticated app chrome: desktop nav, mobile bottom nav, header, logo link, profile menu, and shell content layout. The dashboard feature is mostly derived stats and route composition, feeding a simple landing view inside the authenticated area.

10. Shared infrastructure and utilities live outside the product features:
   - `src/lib` for formatting, query keys, timeout helpers, and invite finalization
   - `src/components/ui` for reusable primitives and dialogs
   - `src/stores` for small app-level UI state
   - `src/app/providers.tsx` for top-level client providers
   These are the main shared boundaries allowed to cross feature lines.

11. The database layer is designed around Supabase migrations and server-enforced rules. The `supabase/migrations/` folder contains schema creation, RLS policies, security-definer helpers, and RPCs for household creation/listing/deletion, membership roster access, invite finalization, and private enforcement. Several migrations also show domain logic pushed into the database rather than the client.

12. A key architectural constraint is enforced by linting and folder boundaries: auth and household are not supposed to import each other directly. Cross-feature coupling is meant to go through shared libs/components or route/API layers. That is important for drawing the diagram: each feature is a bounded context, with Supabase and app routes acting as the integration points.

13. Tests are colocated with feature logic and mostly validate domain rules, permissions, selectors, and derived calculations rather than full end-to-end flows. That suggests the architecture relies on modular business logic in services/lib files, with UI as a relatively thin layer over the domain.

Main entry points: [`src/app/app/page.tsx`](https://github.com/zubayer-hossain/household-finance/blob/main/src/app/app/page.tsx) (Workspace), [`src/services/supabase-client.ts`](https://github.com/zubayer-hossain/household-finance/blob/main/src/services/supabase-client.ts) (Supabase clients), [`src/app/layout.tsx`](https://github.com/zubayer-hossain/household-finance/blob/main/src/app/layout.tsx) (Root app), [`src/features/household/components/HouseholdBootstrap.tsx`](https://github.com/zubayer-hossain/household-finance/blob/main/src/features/household/components/HouseholdBootstrap.tsx) (Household)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App Router"]
  node_app_root["Root app<br/>Next app<br/>[layout.tsx]"]
  node_public_auth_routes["Public auth<br/>Routes<br/>[page.tsx]"]
  node_onboarding_route["Onboarding<br/>Route<br/>[page.tsx]"]
  node_workspace_routes["Workspace<br/>Routes<br/>[page.tsx]"]
  node_household_api["Household API<br/>Route handlers<br/>[route.ts]"]
end

subgraph group_features["Feature Modules"]
  node_auth_feature["Auth<br/>Feature<br/>[AuthGuard.tsx]"]
  node_household_feature["Household<br/>Feature"]
  node_budget_feature["Budgets<br/>Feature"]
  node_category_feature["Categories<br/>Feature"]
  node_transaction_feature["Transactions<br/>Feature"]
  node_dashboard_feature["Dashboard<br/>Feature<br/>[DashboardRoute.tsx]"]
end

subgraph group_shared["Shared Infra"]
  node_app_shell["App shell<br/>Chrome<br/>[AppShell.tsx]"]
  node_ui_primitives["UI kit<br/>Primitives<br/>[button.tsx]"]
  node_supabase_clients["Supabase clients<br/>Client adapters<br/>[supabase-client.ts]"]
  node_shared_lib["Shared lib<br/>Utilities"]
end

subgraph group_db["Supabase"]
  node_db_migrations[("Migrations<br/>SQL schema")]
  node_auth_rpc_rls[("Auth & RLS<br/>Postgres rules")]
  node_household_rpc[("Household RPCs<br/>Postgres RPCs")]
  node_invite_rpc[("Invite finalize<br/>Postgres RPCs")]
  node_category_budget_sql[("Category budget SQL<br/>Postgres rules")]
end

node_app_root -->|"routes"| node_public_auth_routes
node_app_root -->|"routes"| node_onboarding_route
node_app_root -->|"routes"| node_workspace_routes
node_app_root -->|"api"| node_household_api
node_workspace_routes -->|"uses"| node_app_shell
node_public_auth_routes -->|"uses"| node_auth_feature
node_onboarding_route -->|"uses"| node_household_feature
node_workspace_routes -->|"uses"| node_dashboard_feature
node_workspace_routes -->|"uses"| node_household_feature
node_workspace_routes -->|"uses"| node_budget_feature
node_workspace_routes -->|"uses"| node_category_feature
node_workspace_routes -->|"uses"| node_transaction_feature
node_auth_feature -->|"data"| node_supabase_clients
node_household_feature -->|"data"| node_supabase_clients
node_budget_feature -->|"data"| node_supabase_clients
node_category_feature -->|"data"| node_supabase_clients
node_transaction_feature -->|"data"| node_supabase_clients
node_dashboard_feature -->|"calc"| node_shared_lib
node_household_api -->|"invites"| node_shared_lib
node_shared_lib -->|"supports"| node_invite_rpc
node_supabase_clients -->|"connects"| node_db_migrations
node_auth_feature -->|"governed by"| node_auth_rpc_rls
node_household_feature -->|"governed by"| node_household_rpc
node_household_api -->|"server flow"| node_invite_rpc
node_transaction_feature -->|"governed by"| node_category_budget_sql
node_budget_feature -->|"governed by"| node_category_budget_sql

click node_app_root "https://github.com/zubayer-hossain/household-finance/blob/main/src/app/layout.tsx"
click node_public_auth_routes "https://github.com/zubayer-hossain/household-finance/blob/main/src/app/login/page.tsx"
click node_onboarding_route "https://github.com/zubayer-hossain/household-finance/blob/main/src/app/onboarding/page.tsx"
click node_workspace_routes "https://github.com/zubayer-hossain/household-finance/blob/main/src/app/app/page.tsx"
click node_household_api "https://github.com/zubayer-hossain/household-finance/blob/main/src/app/api/household/invite/route.ts"
click node_auth_feature "https://github.com/zubayer-hossain/household-finance/blob/main/src/features/auth/components/AuthGuard.tsx"
click node_household_feature "https://github.com/zubayer-hossain/household-finance/blob/main/src/features/household/components/HouseholdBootstrap.tsx"
click node_budget_feature "https://github.com/zubayer-hossain/household-finance/blob/main/src/features/budgets/components/BudgetsRouteIndex.tsx"
click node_category_feature "https://github.com/zubayer-hossain/household-finance/blob/main/src/features/categories/components/CategoriesRoute.tsx"
click node_transaction_feature "https://github.com/zubayer-hossain/household-finance/blob/main/src/features/transactions/components/TransactionsRoute.tsx"
click node_dashboard_feature "https://github.com/zubayer-hossain/household-finance/blob/main/src/features/dashboard/components/DashboardRoute.tsx"
click node_app_shell "https://github.com/zubayer-hossain/household-finance/blob/main/src/components/shell/AppShell.tsx"
click node_ui_primitives "https://github.com/zubayer-hossain/household-finance/blob/main/src/components/ui/button.tsx"
click node_supabase_clients "https://github.com/zubayer-hossain/household-finance/blob/main/src/services/supabase-client.ts"
click node_shared_lib "https://github.com/zubayer-hossain/household-finance/blob/main/src/lib/finalize-pending-household-invites.ts"
click node_db_migrations "https://github.com/zubayer-hossain/household-finance/blob/main/supabase/migrations/20260202120000_household_finance_foundation.sql"
click node_auth_rpc_rls "https://github.com/zubayer-hossain/household-finance/blob/main/supabase/migrations/20260502153000_onboarding_profile_and_membership_rls.sql"
click node_household_rpc "https://github.com/zubayer-hossain/household-finance/blob/main/supabase/migrations/20260506194500_delete_my_household_rpc.sql"
click node_invite_rpc "https://github.com/zubayer-hossain/household-finance/blob/main/supabase/migrations/20260511120000_finalize_pending_household_invites_rpc.sql"
click node_category_budget_sql "https://github.com/zubayer-hossain/household-finance/blob/main/supabase/migrations/20260520120000_household_categories_draft_budget_delete.sql"

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_root,node_public_auth_routes,node_onboarding_route,node_workspace_routes,node_household_api toneBlue
class node_auth_feature,node_household_feature,node_budget_feature,node_category_feature,node_transaction_feature,node_dashboard_feature toneAmber
class node_app_shell,node_ui_primitives,node_supabase_clients,node_shared_lib toneMint
class node_db_migrations,node_auth_rpc_rls,node_household_rpc,node_invite_rpc,node_category_budget_sql toneRose
```

## Components

### App Router

Next.js route boundaries for public auth, onboarding, workspace, and API flows.

- [Root app](https://github.com/zubayer-hossain/household-finance/blob/main/src/app/layout.tsx): Next app · Top-level layout, providers, and global routing entrypoints. · `src/app/layout.tsx`
- [Public auth](https://github.com/zubayer-hossain/household-finance/blob/main/src/app/login/page.tsx): Routes · Login, signup, password reset, callback, and invite password setup. · `src/app/login/page.tsx`
- [Onboarding](https://github.com/zubayer-hossain/household-finance/blob/main/src/app/onboarding/page.tsx): Route · First-time household setup flow. · `src/app/onboarding/page.tsx`
- [Workspace](https://github.com/zubayer-hossain/household-finance/blob/main/src/app/app/page.tsx): Routes · Authenticated app area for dashboard, household, members, budgets, categories, and transactions. · `src/app/app/page.tsx`
- [Household API](https://github.com/zubayer-hossain/household-finance/blob/main/src/app/api/household/invite/route.ts): Route handlers · Server-only invite, resend, and invited-name update endpoints. · `src/app/api/household/invite/route.ts`

### Feature Modules

Bounded contexts for auth, household, budgets, categories, dashboard, and transactions.

- [Auth](https://github.com/zubayer-hossain/household-finance/blob/main/src/features/auth/components/AuthGuard.tsx): Feature · Session handling, auth forms, guards, and profile loading. · `src/features/auth/components/AuthGuard.tsx`
- [Household](https://github.com/zubayer-hossain/household-finance/blob/main/src/features/household/components/HouseholdBootstrap.tsx): Feature · Household creation, membership, onboarding bootstrap, invites, and permission gates. · `src/features/household/components/HouseholdBootstrap.tsx`
- [Budgets](https://github.com/zubayer-hossain/household-finance/blob/main/src/features/budgets/components/BudgetsRouteIndex.tsx): Feature · Budget views, health, approvals, reallocation, and monthly close. · `src/features/budgets/components/BudgetsRouteIndex.tsx`
- [Categories](https://github.com/zubayer-hossain/household-finance/blob/main/src/features/categories/components/CategoriesRoute.tsx): Feature · Category CRUD, lifecycle controls, reorder, and draft-budget cleanup. · `src/features/categories/components/CategoriesRoute.tsx`
- [Transactions](https://github.com/zubayer-hossain/household-finance/blob/main/src/features/transactions/components/TransactionsRoute.tsx): Feature · Transaction lists, filtering, editing, category assignment, and attachments. · `src/features/transactions/components/TransactionsRoute.tsx`
- [Dashboard](https://github.com/zubayer-hossain/household-finance/blob/main/src/features/dashboard/components/DashboardRoute.tsx): Feature · Derived summary stats and the authenticated landing view. · `src/features/dashboard/components/DashboardRoute.tsx`

### Shared Infra

Reusable shell, UI primitives, app state, and Supabase client wrappers.

- [App shell](https://github.com/zubayer-hossain/household-finance/blob/main/src/components/shell/AppShell.tsx): Chrome · Authenticated navigation, header, profile menu, and shell layout. · `src/components/shell/AppShell.tsx`
- [UI kit](https://github.com/zubayer-hossain/household-finance/blob/main/src/components/ui/button.tsx): Primitives · Reusable buttons, dialogs, forms, and other shared UI building blocks. · `src/components/ui/button.tsx`
- [Supabase clients](https://github.com/zubayer-hossain/household-finance/blob/main/src/services/supabase-client.ts): Client adapters · Browser, server, middleware, and shared Supabase access wrappers. · `src/services/supabase-client.ts`
- [Shared lib](https://github.com/zubayer-hossain/household-finance/blob/main/src/lib/finalize-pending-household-invites.ts): Utilities · Formatting, query keys, timeout helpers, and pending invite finalization. · `src/lib/finalize-pending-household-invites.ts`

### Supabase

Database migrations, RLS, RPCs, and server-enforced domain rules.

- [Migrations](https://github.com/zubayer-hossain/household-finance/blob/main/supabase/migrations/20260202120000_household_finance_foundation.sql): SQL schema · Schema, RLS, security-definer helpers, and RPC/domain logic in Postgres. · `supabase/migrations/20260202120000_household_finance_foundation.sql`
- [Auth & RLS](https://github.com/zubayer-hossain/household-finance/blob/main/supabase/migrations/20260502153000_onboarding_profile_and_membership_rls.sql): Postgres rules · Profile, membership, household, and private-enforcement policies and RPCs. · `supabase/migrations/20260502153000_onboarding_profile_and_membership_rls.sql`
- [Household RPCs](https://github.com/zubayer-hossain/household-finance/blob/main/supabase/migrations/20260506194500_delete_my_household_rpc.sql): Postgres RPCs · Create/list/delete household and membership roster helpers. · `supabase/migrations/20260506194500_delete_my_household_rpc.sql`
- [Invite finalize](https://github.com/zubayer-hossain/household-finance/blob/main/supabase/migrations/20260511120000_finalize_pending_household_invites_rpc.sql): Postgres RPCs · Invite finalization and roster-access helpers for pending household invites. · `supabase/migrations/20260511120000_finalize_pending_household_invites_rpc.sql`
- [Category budget SQL](https://github.com/zubayer-hossain/household-finance/blob/main/supabase/migrations/20260520120000_household_categories_draft_budget_delete.sql): Postgres rules · Draft-budget cleanup and transaction-category related domain rules. · `supabase/migrations/20260520120000_household_categories_draft_budget_delete.sql`

## Connections

- Root app → Public auth: routes · Public pages mount through the root Next app.
- Root app → Onboarding: routes · Onboarding is a dedicated route segment.
- Root app → Workspace: routes · Authenticated workspace routes live under the app area.
- Root app → Household API: api · Route handlers are exposed from the same app tree.
- Workspace → App shell: uses · Workspace pages render inside the authenticated shell.
- Public auth → Auth: uses · Login, signup, reset, callback, and invite flows are handled by auth feature components.
- Onboarding → Household: uses · Household bootstrap and onboarding guard drive first-run setup.
- Workspace → Dashboard: uses · Workspace landing composes dashboard stats.
- Workspace → Household: uses · Household settings and members screens are built from the household feature.
- Workspace → Budgets: uses · Budgets route composes the budgeting feature.
- Workspace → Categories: uses · Categories route composes the categories feature.
- Workspace → Transactions: uses · Transactions route composes the transaction feature.
- Auth → Supabase clients: data · Auth state, profile queries, and session listeners use Supabase adapters.
- Household → Supabase clients: data · Household membership and invite flows query Supabase through service wrappers.
- Budgets → Supabase clients: data · Budget hooks and services read/write through Supabase.
- Categories → Supabase clients: data · Category CRUD and draft-budget operations use Supabase services.
- Transactions → Supabase clients: data · Transactions and attachment flows use Supabase and storage-backed services.
- Dashboard → Shared lib: calc · Dashboard stats rely on shared utilities and selectors.
- Household API → Shared lib: invites · Invite endpoints use shared pending-invite finalization and mail helpers.
- Shared lib → Invite finalize: supports · Shared invite finalization mirrors database-level invite RPC behavior.
- Supabase clients → Migrations: connects · Client adapters are constrained by the migrated schema and RLS rules.
- Auth → Auth & RLS: governed by · Session/profile behavior depends on auth and membership policies.
- Household → Household RPCs: governed by · Creation, listing, deletion, and roster access are backed by household RPCs.
- Household API → Invite finalize: server flow · Invite routes coordinate with invite finalization and membership helpers.
- Transactions → Category budget SQL: governed by · Transaction/category behavior depends on SQL rules for category cleanup and posting.
- Budgets → Category budget SQL: governed by · Budget lifecycle and category interactions depend on database-enforced rules.