# rahul1015s/genexpence architecture

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

- Interactive diagram: https://gitdiagram.com/rahul1015s/genexpence
- Repository: https://github.com/rahul1015s/genexpence

## Overview

1. This is a Next.js App Router application with a strong split between presentation, API routes, and server-side domain logic. The top-level `app/` tree defines the user-facing routes, while `app/api/` contains the HTTP boundary for all business operations.

2. The repository is organized around multiple user personas and product modes rather than a single generic UI:
   - personal finance/dashboard routes
   - professional bookkeeping/invoicing routes
   - admin/owner back-office routes
   - auth/onboarding and marketing pages
   - calculators, analytics, support, pricing, and legal pages

3. The main request flow is consistent across the app: page components in `app/**/page.tsx` render feature-specific React components from `components/**`, those features call route handlers in `app/api/**/route.ts`, and the route handlers delegate into `lib/server/**` for domain rules and data access.

4. The backend logic is concentrated in `lib/server/`, which is split by domain: dashboard, personal finance, professional features, invoices, notifications, owner/admin, wealth, and app bootstrap/auth helpers. This is the main boundary where authorization, business rules, and cross-entity orchestration appear to live.

5. Data persistence is model-driven. The `models/` directory includes entities such as `User`, `Transaction`, `Invoice`, `Client`, `Investment`, `Notification`, `Announcement`, `OTP`, `SessionNotice`, `NetWorthHistory`, and audit logs. That layout strongly suggests a database-backed application with a document-model layer, with `lib/db/db.ts` providing the connection/runtime access point.

6. Authentication and account recovery are a dedicated subsystem. There are separate routes and screens for login, signup, magic-link, OTP/two-factor verification, password reset, email verification, and session notices. Supporting code in `lib/auth*`, `lib/token.ts`, `lib/crypto.ts`, and `lib/session-device.ts` indicates session management, security tokens, and device/session tracking.

7. The app has an explicit mode/context layer. `contexts/ModeContext.tsx`, `providers/AuthProvider.tsx`, and `providers/ThemeProvider.tsx` sit near the root, while routes like `app/dashboard`, `app/professional`, and `app/owner` imply the UI and APIs switch behavior based on the current user mode and subscription level. `lib/subscription.ts` and the `app/api/user/subscription/*` routes reinforce that access is feature-gated.

8. The personal finance dashboard is a large subsystem. It covers transactions, accounts, budgets, goals, recurring items, categories, charts, investments, lent/borrowed tracking, net worth, and dashboard summaries. Its UI lives mostly under `components/Dashboard`, and its server endpoints are grouped under `app/api/dashboard/*`, `app/api/transactions/*`, `app/api/investments/*`, `app/api/lent-borrowed/*`, and `app/api/wealth/*`.

9. The professional/business subsystem is similarly self-contained. It includes clients, invoices, payments, PDF generation, GST summaries, reports, team settings, notifications, and transaction enhancements. The main UI lives under `components/Professional`, with matching API groups under `app/api/professional/*`, and invoice-specific helpers in `lib/invoice-pdf.ts`, `lib/invoice-utils.ts`, and `lib/invoiceNumber.ts`.

10. Administrative and owner workflows are separated from end-user functionality. `app/admin/*` and `app/owner/*` expose user management, announcements, audit logs, billing, analytics, and spend controls, while API routes under `app/api/admin/*` provide privileged operations like user deletion, password resets, verification changes, announcements, and overview data. This is a distinct back-office boundary with elevated permissions.

11. Notifications, announcements, and operational messaging are first-class cross-cutting concerns. There are API routes for active announcements, admin notification processing, session notices, and general notifications, plus client-side banner components and email template code in `components/email-templates*` and `lib/email.ts`. This suggests both in-app and email delivery paths.

12. Offline and PWA support are part of the architecture, not an afterthought. `public/sw.js`, `components/PwaRegister.tsx`, `components/App/OfflineSyncManager.tsx`, `components/App/OfflineStatusIndicator.tsx`, and `lib/offline/*` show a client-side caching/sync layer, likely centered on transaction data and resilient usage when disconnected.

13. Calculators and wealth tools are a separate product surface. `app/(dashboard)/calculators`, `components/calculators/*`, and `lib/calculators/*` contain reusable financial calculation engines and UI shells for loan EMI, SIP, tax, XIRR, and goal planning. The presence of `lib/wealth-engine.ts` and dedicated wealth routes indicates a computation-heavy subsystem with shared formatting and insight generation.

14. Reusable UI and shell composition are centralized in `components/ui/*` and layout components such as `components/Dashboard/DashboardLayout.tsx`, `components/Dashboard/DashboardSidebar.tsx`, and `components/AppRootClient.tsx`. The visual layer is built from shared primitives, then specialized per persona and feature.

15. Overall, the architecture is a multi-tenant, role- and mode-aware finance platform: Next.js pages provide the UX, API route handlers expose domain operations, `lib/server` enforces business logic and authorization, and `models`/`lib/db` persist domain state. The main diagram should emphasize the separation between persona-specific feature areas and the shared cross-cutting systems for auth, subscription, notifications, offline sync, and data models.

Main entry points: [`app`](https://github.com/rahul1015s/genexpence/tree/feat/dashboard-api/app) (App routes), [`components/Dashboard`](https://github.com/rahul1015s/genexpence/tree/feat/dashboard-api/components/Dashboard) (Dashboard comps), [`lib/db/db.ts`](https://github.com/rahul1015s/genexpence/blob/feat/dashboard-api/lib/db/db.ts) (DB runtime), [`models`](https://github.com/rahul1015s/genexpence/tree/feat/dashboard-api/models) (Domain models)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_presentation["Presentation"]
  node_app_root["App routes<br/>nextjs routes"]
  node_auth_pages["Auth pages<br/>auth ux"]
  node_dashboard_pages["Dashboard UI<br/>personal finance ui"]
  node_pro_pages["Professional UI<br/>business ui"]
  node_admin_pages["Admin UI<br/>back-office ui"]
  node_public_pages["Public pages<br/>marketing/docs<br/>[page.tsx]"]
  node_dashboard_comp["Dashboard comps<br/>feature components"]
  node_pro_comp["Professional comps<br/>feature components"]
  node_admin_comp["Admin comps<br/>admin components"]
  node_auth_comp["Auth comps<br/>auth components"]
end

subgraph group_api["API Layer"]
  node_api_auth["Auth API<br/>auth/http"]
  node_api_dashboard["Dashboard API<br/>personal finance api"]
  node_api_professional["Professional API<br/>business api"]
  node_api_admin["Admin API<br/>privileged api"]
  node_api_crosscutting["Shared API<br/>platform api"]
end

subgraph group_server["Server Logic"]
  node_server_auth["Auth guard<br/>security layer<br/>[route-auth.ts]"]
  node_server_dashboard["Dashboard logic<br/>domain service"]
  node_server_professional["Professional logic<br/>domain service<br/>[professional.ts]"]
  node_server_owner["Owner logic<br/>admin service<br/>[owner-admin.ts]"]
  node_server_wealth["Wealth logic<br/>calculation service<br/>[wealth.ts]"]
end

subgraph group_shared["Shared Systems"]
  node_shared_auth["Auth stack<br/>identity<br/>[auth.ts]"]
  node_shared_offline["Offline stack<br/>pwa/offline"]
  node_shared_calc["Calculators<br/>finance engine"]
  node_shared_mail["Messaging<br/>notifications/email<br/>[email.ts]"]
end

subgraph group_data["Data Model"]
  node_shared_db[("DB runtime<br/>database runtime<br/>[db.ts]")]
  node_models_domain[("Domain models<br/>schema models")]
end

node_app_root -->|"renders"| node_auth_pages
node_app_root -->|"renders"| node_dashboard_pages
node_app_root -->|"renders"| node_pro_pages
node_app_root -->|"renders"| node_admin_pages
node_app_root -->|"renders"| node_public_pages
node_auth_pages -->|"uses"| node_auth_comp
node_dashboard_pages -->|"uses"| node_dashboard_comp
node_pro_pages -->|"uses"| node_pro_comp
node_admin_pages -->|"uses"| node_admin_comp
node_auth_comp -->|"calls"| node_api_auth
node_dashboard_comp -->|"calls"| node_api_dashboard
node_pro_comp -->|"calls"| node_api_professional
node_admin_comp -->|"calls"| node_api_admin
node_api_auth -->|"delegates"| node_server_auth
node_api_dashboard -->|"delegates"| node_server_dashboard
node_api_professional -->|"delegates"| node_server_professional
node_api_admin -->|"delegates"| node_server_owner
node_api_crosscutting -->|"guards"| node_server_auth
node_server_dashboard -->|"reads/writes"| node_shared_db
node_server_professional -->|"reads/writes"| node_shared_db
node_server_owner -->|"reads/writes"| node_shared_db
node_server_wealth -->|"reads/writes"| node_shared_db
node_server_dashboard -->|"uses"| node_models_domain
node_server_professional -->|"uses"| node_models_domain
node_server_owner -->|"uses"| node_models_domain
node_server_wealth -->|"uses"| node_models_domain
node_shared_auth -->|"supports"| node_api_auth
node_shared_auth -->|"supports"| node_api_crosscutting
node_shared_offline -->|"supports"| node_dashboard_comp
node_shared_calc -->|"supports"| node_dashboard_comp
node_shared_mail -->|"supports"| node_api_crosscutting
node_shared_mail -->|"supports"| node_api_admin

click node_app_root "https://github.com/rahul1015s/genexpence/tree/feat/dashboard-api/app"
click node_auth_pages "https://github.com/rahul1015s/genexpence/tree/feat/dashboard-api/app/(auth)"
click node_dashboard_pages "https://github.com/rahul1015s/genexpence/tree/feat/dashboard-api/app/dashboard"
click node_pro_pages "https://github.com/rahul1015s/genexpence/tree/feat/dashboard-api/app/professional"
click node_admin_pages "https://github.com/rahul1015s/genexpence/tree/feat/dashboard-api/app/admin"
click node_public_pages "https://github.com/rahul1015s/genexpence/blob/feat/dashboard-api/app/page.tsx"
click node_dashboard_comp "https://github.com/rahul1015s/genexpence/tree/feat/dashboard-api/components/Dashboard"
click node_pro_comp "https://github.com/rahul1015s/genexpence/tree/feat/dashboard-api/components/Professional"
click node_admin_comp "https://github.com/rahul1015s/genexpence/tree/feat/dashboard-api/components/Admin"
click node_auth_comp "https://github.com/rahul1015s/genexpence/tree/feat/dashboard-api/components/auth"
click node_api_auth "https://github.com/rahul1015s/genexpence/tree/feat/dashboard-api/app/api/auth"
click node_api_dashboard "https://github.com/rahul1015s/genexpence/tree/feat/dashboard-api/app/api/dashboard"
click node_api_professional "https://github.com/rahul1015s/genexpence/tree/feat/dashboard-api/app/api/professional"
click node_api_admin "https://github.com/rahul1015s/genexpence/tree/feat/dashboard-api/app/api/admin"
click node_api_crosscutting "https://github.com/rahul1015s/genexpence/tree/feat/dashboard-api/app/api"
click node_server_auth "https://github.com/rahul1015s/genexpence/blob/feat/dashboard-api/lib/server/route-auth.ts"
click node_server_dashboard "https://github.com/rahul1015s/genexpence/blob/feat/dashboard-api/lib/server/personal-dashboard.ts"
click node_server_professional "https://github.com/rahul1015s/genexpence/blob/feat/dashboard-api/lib/server/professional.ts"
click node_server_owner "https://github.com/rahul1015s/genexpence/blob/feat/dashboard-api/lib/server/owner-admin.ts"
click node_server_wealth "https://github.com/rahul1015s/genexpence/blob/feat/dashboard-api/lib/server/wealth.ts"
click node_shared_auth "https://github.com/rahul1015s/genexpence/blob/feat/dashboard-api/lib/auth.ts"
click node_shared_offline "https://github.com/rahul1015s/genexpence/tree/feat/dashboard-api/lib/offline"
click node_shared_calc "https://github.com/rahul1015s/genexpence/tree/feat/dashboard-api/lib/calculators"
click node_shared_mail "https://github.com/rahul1015s/genexpence/blob/feat/dashboard-api/lib/email.ts"
click node_shared_db "https://github.com/rahul1015s/genexpence/blob/feat/dashboard-api/lib/db/db.ts"
click node_models_domain "https://github.com/rahul1015s/genexpence/tree/feat/dashboard-api/models"

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_auth_pages,node_dashboard_pages,node_pro_pages,node_admin_pages,node_public_pages,node_dashboard_comp,node_pro_comp,node_admin_comp,node_auth_comp toneBlue
class node_api_auth,node_api_dashboard,node_api_professional,node_api_admin,node_api_crosscutting toneAmber
class node_server_auth,node_server_dashboard,node_server_professional,node_server_owner,node_server_wealth toneMint
class node_shared_auth,node_shared_offline,node_shared_calc,node_shared_mail toneRose
class node_shared_db,node_models_domain toneIndigo
```

## Components

### Presentation

App Router routes and feature UIs

- [App routes](https://github.com/rahul1015s/genexpence/tree/feat/dashboard-api/app): nextjs routes · Top-level App Router surfaces for persona-specific and public pages · `app`
- [Auth pages](https://github.com/rahul1015s/genexpence/tree/feat/dashboard-api/app/(auth)): auth ux · Login, signup, OTP, reset, and email verification screens · `app/(auth)`
- [Dashboard UI](https://github.com/rahul1015s/genexpence/tree/feat/dashboard-api/app/dashboard): personal finance ui · Personal finance dashboard, wealth, accounts, goals, investments, and transactions · `app/dashboard`
- [Professional UI](https://github.com/rahul1015s/genexpence/tree/feat/dashboard-api/app/professional): business ui · Professional invoicing, clients, GST, reports, and notifications pages · `app/professional`
- [Admin UI](https://github.com/rahul1015s/genexpence/tree/feat/dashboard-api/app/admin): back-office ui · Owner and admin console for users, announcements, audit, billing, and spend · `app/admin`
- [Public pages](https://github.com/rahul1015s/genexpence/blob/feat/dashboard-api/app/page.tsx): marketing/docs · Home, pricing, support, legal, analytics, and search surfaces · `app/page.tsx`
- [Dashboard comps](https://github.com/rahul1015s/genexpence/tree/feat/dashboard-api/components/Dashboard): feature components · Personal finance dashboard composition and widgets · `components/Dashboard`
- [Professional comps](https://github.com/rahul1015s/genexpence/tree/feat/dashboard-api/components/Professional): feature components · Client, invoice, GST, report, and settings UI pieces · `components/Professional`
- [Admin comps](https://github.com/rahul1015s/genexpence/tree/feat/dashboard-api/components/Admin): admin components · Owner/admin tables, detail views, and announcement tools · `components/Admin`
- [Auth comps](https://github.com/rahul1015s/genexpence/tree/feat/dashboard-api/components/auth): auth components · Reusable login, signup, reset, OTP, and magic-link forms · `components/auth`

### API Layer

HTTP route handlers grouped by domain

- [Auth API](https://github.com/rahul1015s/genexpence/tree/feat/dashboard-api/app/api/auth): auth/http · Authentication, password reset, OTP, session, and signup endpoints · `app/api/auth`
- [Dashboard API](https://github.com/rahul1015s/genexpence/tree/feat/dashboard-api/app/api/dashboard): personal finance api · Accounts, budgets, goals, recurring items, charting, and transactions · `app/api/dashboard`
- [Professional API](https://github.com/rahul1015s/genexpence/tree/feat/dashboard-api/app/api/professional): business api · Clients, invoices, GST, reports, team, settings, and collaboration endpoints · `app/api/professional`
- [Admin API](https://github.com/rahul1015s/genexpence/tree/feat/dashboard-api/app/api/admin): privileged api · User administration, announcements, audit, overview, and enforcement actions · `app/api/admin`
- [Shared API](https://github.com/rahul1015s/genexpence/tree/feat/dashboard-api/app/api): platform api · User profile, mode, subscription, notifications, search, health, wealth, and personal helpers · `app/api`

### Server Logic

Domain rules, orchestration, and auth guards

- [Auth guard](https://github.com/rahul1015s/genexpence/blob/feat/dashboard-api/lib/server/route-auth.ts): security layer · Route authorization, app bootstrap, session policy, and user context · `lib/server/route-auth.ts`
- [Dashboard logic](https://github.com/rahul1015s/genexpence/blob/feat/dashboard-api/lib/server/personal-dashboard.ts): domain service · Personal finance orchestration for transactions, summaries, and dashboard views · `lib/server/personal-dashboard.ts`
- [Professional logic](https://github.com/rahul1015s/genexpence/blob/feat/dashboard-api/lib/server/professional.ts): domain service · Business workflows for clients, invoices, reports, notifications, and collaboration · `lib/server/professional.ts`
- [Owner logic](https://github.com/rahul1015s/genexpence/blob/feat/dashboard-api/lib/server/owner-admin.ts): admin service · Owner/admin controls, billing, analytics, and elevated operations · `lib/server/owner-admin.ts`
- [Wealth logic](https://github.com/rahul1015s/genexpence/blob/feat/dashboard-api/lib/server/wealth.ts): calculation service · Net worth and wealth profile orchestration · `lib/server/wealth.ts`

### Shared Systems

Cross-cutting client and utility subsystems

- [Auth stack](https://github.com/rahul1015s/genexpence/blob/feat/dashboard-api/lib/auth.ts): identity · Client auth, tokens, crypto, sessions, devices, and subscription gating · `lib/auth.ts`
- [Offline stack](https://github.com/rahul1015s/genexpence/tree/feat/dashboard-api/lib/offline): pwa/offline · Service worker, IndexedDB cache, and transaction sync · `lib/offline`
- [Calculators](https://github.com/rahul1015s/genexpence/tree/feat/dashboard-api/lib/calculators): finance engine · Reusable loan, SIP, tax, XIRR, formatting, and insight helpers · `lib/calculators`
- [Messaging](https://github.com/rahul1015s/genexpence/blob/feat/dashboard-api/lib/email.ts): notifications/email · In-app notices, announcements, and email template delivery · `lib/email.ts`

### Data Model

Persistence models and database access

- [DB runtime](https://github.com/rahul1015s/genexpence/blob/feat/dashboard-api/lib/db/db.ts): database runtime · Database connection and persistence runtime access · `lib/db/db.ts`
- [Domain models](https://github.com/rahul1015s/genexpence/tree/feat/dashboard-api/models): schema models · User, transaction, invoice, client, investment, notification, and audit entities · `models`

## Connections

- App routes → Auth pages: renders · App Router exposes auth screens
- App routes → Dashboard UI: renders · App Router exposes personal finance surfaces
- App routes → Professional UI: renders · App Router exposes professional surfaces
- App routes → Admin UI: renders · App Router exposes admin surfaces
- App routes → Public pages: renders · App Router exposes public marketing and utility pages
- Auth pages → Auth comps: uses · Auth screens are built from shared forms
- Dashboard UI → Dashboard comps: uses · Dashboard pages compose feature widgets
- Professional UI → Professional comps: uses · Professional pages compose business UI
- Admin UI → Admin comps: uses · Admin pages compose privileged UI
- Auth comps → Auth API: calls · Auth forms submit to auth endpoints
- Dashboard comps → Dashboard API: calls · Dashboard UI fetches and mutates finance data
- Professional comps → Professional API: calls · Professional UI drives business APIs
- Admin comps → Admin API: calls · Admin UI invokes privileged endpoints
- Auth API → Auth guard: delegates · Auth handlers rely on authorization and session helpers
- Dashboard API → Dashboard logic: delegates · Dashboard routes hand off to domain logic
- Professional API → Professional logic: delegates · Professional routes hand off to business logic
- Admin API → Owner logic: delegates · Admin routes hand off to owner/admin logic
- Shared API → Auth guard: guards · Shared platform endpoints still enforce user context and access rules
- Dashboard logic → DB runtime: reads/writes · Dashboard logic persists to the database runtime
- Professional logic → DB runtime: reads/writes · Professional logic persists business data
- Owner logic → DB runtime: reads/writes · Admin workflows operate on persisted records
- Wealth logic → DB runtime: reads/writes · Wealth features persist profile and history state
- Dashboard logic → Domain models: uses · Dashboard logic works over transaction and finance entities
- Professional logic → Domain models: uses · Professional logic works over invoice and client entities
- Owner logic → Domain models: uses · Admin logic works over user, audit, and announcement entities
- Wealth logic → Domain models: uses · Wealth logic works over net worth and profile entities
- Auth stack → Auth API: supports · Identity stack backs authentication endpoints
- Auth stack → Shared API: supports · Mode, subscription, and profile endpoints use shared auth state
- Offline stack → Dashboard comps: supports · Offline sync and status are part of dashboard UX
- Calculators → Dashboard comps: supports · Dashboard wealth and calculators reuse finance engines
- Messaging → Shared API: supports · Announcements, notifications, and emails are delivered through shared messaging
- Messaging → Admin API: supports · Admin operations trigger operational messaging
