zubayer-hossain/household-finance

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.