# nishal77/udhaarclear architecture

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

- Interactive diagram: https://gitdiagram.com/nishal77/udhaarclear
- Repository: https://github.com/nishal77/udhaarclear

## Overview

1. **Overall shape**
   - This is a multi-surface Next.js App Router application: a public marketing site, an authenticated SaaS dashboard, a payment portal, and a server-side API layer.
   - The main architectural split is between `app/` route groups, reusable feature components in `components/`, and server/domain code in `lib/`.

2. **Route boundaries**
   - `app/(auth)` contains login/signup screens.
   - `app/(dashboard)` contains the main product: customers, invoices, analytics, payments, reports, reminders, team, settings, WhatsApp/email logs, and MSME/legal features.
   - `app/onboarding` and `app/pay/[id]` are separate flows that sit outside the normal dashboard experience.
   - `app/api/*` is the backend surface for all business operations.

3. **Authentication and onboarding flow**
   - Auth is OTP-based, with routes for login, signup, OTP verification, and callback handling.
   - `lib/auth/otp-cookie.ts` and `proxy.ts` indicate session/state enforcement at the edge/middleware boundary.
   - `app/onboarding` handles post-auth setup before a user fully enters the dashboard.

4. **Core business domain**
   - The product centers on receivables management: customers, invoices, reminders, payments, and collections.
   - Customer and invoice CRUD exist in both pages and API routes, with matching create/edit/detail screens.
   - Legal notice and MSME-related pages suggest debt-recovery workflows beyond simple invoicing.

5. **Analytics subsystem**
   - Analytics is a first-class area with dedicated dashboard pages for heatmap, predictive insights, recovery analytics, and digest views.
   - These screens are backed by API routes under `app/api/analytics/*`.
   - UI components in `components/analytics` appear to be reusable visualizations driven by backend-derived collection data.

6. **Reminder and notification engine**
   - Reminders are orchestrated by a server-side service layer in `lib/services/reminder-service.ts` and `lib/cron/reminder-engine.ts`.
   - `app/api/cron/send-reminders` suggests scheduled execution, likely via a hosted cron trigger.
   - Delivery channels include email and WhatsApp, with tracking endpoints for email open events and log dashboards for message history.

7. **Payments and collection confirmation**
   - Razorpay is the external payment rail, with dedicated client, payment-link, and webhook helpers in `lib/razorpay`.
   - The payment experience has its own public flow under `app/pay/[id]`, plus confirm/verify endpoints for completing and validating payment events.
   - Payment status updates likely feed back into invoices, reminders, and analytics.

8. **Settings and tenant administration**
   - The settings area is modular: profile, billing, team, integrations, webhooks, WhatsApp, and payments.
   - `components/settings/*` and `app/(dashboard)/settings/*` indicate separate server and client responsibilities.
   - Team/business pages suggest multi-business or multi-user workspace management rather than a single-user app.

9. **Shared dashboard shell**
   - The authenticated UI is wrapped by shared layout components: sidebar, top bar, page header, mobile nav, notification dropdown, and dashboard shell.
   - Most feature pages are thin route wrappers around feature-specific components, keeping page files light and presentation logic centralized.
   - Shared primitives in `components/ui` and `components/shared` standardize charts, cards, loading states, and empty states.

10. **Domain libraries and integrations**
   - `lib/validations` defines schema-level input validation for customers, invoices, and shared structures.
   - `lib/utils` contains common formatting and domain helpers such as currency, date, phone, GST, and API error handling.
   - Email, WhatsApp, PDF generation, and Razorpay clients are isolated in `lib/email`, `lib/whatsapp`, `lib/pdf`, and `lib/razorpay`, keeping external integrations out of page code.

11. **Persistence and data contracts**
   - Prisma is the primary database layer, with schema and migrations under `prisma/`.
   - `lib/prisma/client.ts` is the main database access point, while `types/database.ts` and other type files provide typed contracts for external payloads.
   - The architecture suggests server routes and services read/write the database, then drive UI state through pages and dashboards.

12. **Testing and verification**
   - Vitest-based tests cover utility and domain logic such as currency formatting, validations, and tone engine behavior.
   - This indicates the repo is not only UI-heavy; it also has testable backend/domain rules around reminders, messaging tone, and validation.

Overall, the diagram should show a Next.js front end composed of several route groups, a server API layer for CRUD/integrations/analytics, a shared domain/service layer in `lib/`, and external dependencies for auth/session, database, payments, email, WhatsApp, and scheduled reminder delivery.

Main entry points: [`components/layout`](https://github.com/nishal77/udhaarclear/tree/main/components/layout) (Dashboard shell), [`app/(dashboard)`](https://github.com/nishal77/udhaarclear/tree/main/app/(dashboard)) (Receivables), [`lib`](https://github.com/nishal77/udhaarclear/tree/main/lib) (Integrations), [`app/api`](https://github.com/nishal77/udhaarclear/tree/main/app/api) (Business API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_public["Public site"]
  node_node_marketing["Landing site<br/>Next.js public pages<br/>[page.tsx]"]
end

subgraph group_group_auth["Auth flow"]
  node_node_auth_routes["Auth pages<br/>OTP entry flow"]
  node_node_onboarding["Onboarding<br/>Post-auth setup"]
end

subgraph group_group_dashboard["Dashboard app"]
  node_node_dashboard_shell["Dashboard shell<br/>Shared layout"]
  node_node_receivables["Receivables<br/>Core CRUD"]
  node_node_analytics_ui["Analytics UI<br/>Insights views"]
  node_node_settings["Settings<br/>Tenant config"]
  node_node_team["Team admin<br/>Workspace mgmt"]
  node_node_tone_engine["Tone engine<br/>Messaging logic<br/>[page.tsx]"]
end

subgraph group_group_api["API layer"]
  node_node_api_auth["Auth API<br/>OTP backend"]
  node_node_api_business["Business API<br/>CRUD backend"]
  node_node_api_analytics["Analytics API<br/>Insight backend"]
  node_node_api_payments["Payments API<br/>Payment backend"]
  node_node_api_reminders["Reminder API<br/>Scheduler API"]
  node_node_api_webhooks["Webhooks<br/>Ingress handlers"]
end

subgraph group_group_lib["Server domain"]
  node_node_lib_auth["Auth state<br/>Session/middleware<br/>[otp-cookie.ts]"]
  node_node_lib_services["Reminder service<br/>Domain services"]
  node_node_lib_integrations["Integrations<br/>Adapters"]
  node_node_lib_data[("Data layer<br/>Prisma/Supabase<br/>[client.ts]")]
end

subgraph group_group_integrations["External systems"]
  node_node_external_db[("Database<br/>Prisma/Postgres<br/>[schema.prisma]")]
  node_node_external_comm["Email/WhatsApp<br/>Messaging providers<br/>[client.ts]"]
  node_node_external_pay["Razorpay<br/>Payment rail<br/>[client.ts]"]
  node_node_external_cron["Hosted cron<br/>Scheduled trigger<br/>[route.ts]"]
end

node_node_marketing -->|"start signup"| node_node_auth_routes
node_node_auth_routes -->|"verify OTP"| node_node_api_auth
node_node_api_auth -->|"set session"| node_node_lib_auth
node_node_lib_auth -->|"send OTP"| node_node_external_comm
node_node_api_auth -->|"post-auth"| node_node_onboarding
node_node_onboarding -->|"save setup"| node_node_api_business
node_node_dashboard_shell -->|"wraps"| node_node_receivables
node_node_dashboard_shell -->|"wraps"| node_node_analytics_ui
node_node_dashboard_shell -->|"wraps"| node_node_settings
node_node_dashboard_shell -->|"wraps"| node_node_team
node_node_dashboard_shell -->|"wraps"| node_node_tone_engine
node_node_receivables -->|"CRUD"| node_node_api_business
node_node_receivables -->|"collect"| node_node_api_payments
node_node_receivables -->|"remind"| node_node_api_reminders
node_node_receivables -->|"receive events"| node_node_api_webhooks
node_node_analytics_ui -->|"load insights"| node_node_api_analytics
node_node_settings -->|"update config"| node_node_api_business
node_node_settings -->|"configure"| node_node_api_webhooks
node_node_team -->|"manage workspace"| node_node_api_business
node_node_tone_engine -->|"shape messaging"| node_node_lib_services
node_node_api_business -->|"read/write"| node_node_lib_data
node_node_api_analytics -->|"aggregate"| node_node_lib_data
node_node_api_payments -->|"process payments"| node_node_lib_integrations
node_node_api_reminders -->|"orchestrate"| node_node_lib_services
node_node_api_reminders -->|"deliver"| node_node_lib_integrations
node_node_api_webhooks -->|"ingest events"| node_node_lib_integrations
node_node_lib_services -->|"scheduled by"| node_node_external_cron
node_node_lib_services -->|"send notifications"| node_node_external_comm
node_node_lib_integrations -->|"use"| node_node_external_pay
node_node_lib_integrations -->|"use"| node_node_external_comm
node_node_lib_data -->|"persist"| node_node_external_db

click node_node_marketing "https://github.com/nishal77/udhaarclear/blob/main/app/page.tsx"
click node_node_auth_routes "https://github.com/nishal77/udhaarclear/tree/main/app/(auth)"
click node_node_onboarding "https://github.com/nishal77/udhaarclear/tree/main/app/onboarding"
click node_node_dashboard_shell "https://github.com/nishal77/udhaarclear/tree/main/components/layout"
click node_node_receivables "https://github.com/nishal77/udhaarclear/tree/main/app/(dashboard)"
click node_node_analytics_ui "https://github.com/nishal77/udhaarclear/tree/main/components/analytics"
click node_node_settings "https://github.com/nishal77/udhaarclear/tree/main/app/(dashboard)/settings"
click node_node_team "https://github.com/nishal77/udhaarclear/tree/main/app/(dashboard)/team"
click node_node_tone_engine "https://github.com/nishal77/udhaarclear/blob/main/app/(dashboard)/tone-engine/page.tsx"
click node_node_api_auth "https://github.com/nishal77/udhaarclear/tree/main/app/api/auth"
click node_node_api_business "https://github.com/nishal77/udhaarclear/tree/main/app/api"
click node_node_api_analytics "https://github.com/nishal77/udhaarclear/tree/main/app/api/analytics"
click node_node_api_payments "https://github.com/nishal77/udhaarclear/tree/main/app/api/pay"
click node_node_api_reminders "https://github.com/nishal77/udhaarclear/tree/main/app/api/reminders"
click node_node_api_webhooks "https://github.com/nishal77/udhaarclear/tree/main/app/api/webhooks"
click node_node_lib_auth "https://github.com/nishal77/udhaarclear/blob/main/lib/auth/otp-cookie.ts"
click node_node_lib_services "https://github.com/nishal77/udhaarclear/blob/main/lib/services/reminder-service.ts"
click node_node_lib_integrations "https://github.com/nishal77/udhaarclear/tree/main/lib"
click node_node_lib_data "https://github.com/nishal77/udhaarclear/blob/main/lib/prisma/client.ts"
click node_node_external_db "https://github.com/nishal77/udhaarclear/blob/main/prisma/schema.prisma"
click node_node_external_comm "https://github.com/nishal77/udhaarclear/blob/main/lib/email/client.ts"
click node_node_external_pay "https://github.com/nishal77/udhaarclear/blob/main/lib/razorpay/client.ts"
click node_node_external_cron "https://github.com/nishal77/udhaarclear/blob/main/app/api/cron/send-reminders/route.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_marketing toneBlue
class node_node_auth_routes,node_node_onboarding toneAmber
class node_node_dashboard_shell,node_node_receivables,node_node_analytics_ui,node_node_settings,node_node_team,node_node_tone_engine toneMint
class node_node_api_auth,node_node_api_business,node_node_api_analytics,node_node_api_payments,node_node_api_reminders,node_node_api_webhooks toneRose
class node_node_lib_auth,node_node_lib_services,node_node_lib_integrations,node_node_lib_data toneIndigo
class node_node_external_db,node_node_external_comm,node_node_external_pay,node_node_external_cron toneTeal
```

## Components

### Public site

Marketing and pricing surfaces for anonymous visitors.

- [Landing site](https://github.com/nishal77/udhaarclear/blob/main/app/page.tsx): Next.js public pages · Homepage, pricing, and marketing content for acquisition. · `app/page.tsx`

### Auth flow

OTP-based sign-in and account creation.

- [Auth pages](https://github.com/nishal77/udhaarclear/tree/main/app/(auth)): OTP entry flow · Login and signup screens for the OTP-based authentication experience. · `app/(auth)`
- [Onboarding](https://github.com/nishal77/udhaarclear/tree/main/app/onboarding): Post-auth setup · Setup flow that runs before full dashboard access. · `app/onboarding`

### Dashboard app

Authenticated product surfaces and shared shell.

- [Dashboard shell](https://github.com/nishal77/udhaarclear/tree/main/components/layout): Shared layout · Sidebar, top bar, headers, mobile nav, and notification chrome for authenticated views. · `components/layout`
- [Receivables](https://github.com/nishal77/udhaarclear/tree/main/app/(dashboard)): Core CRUD · Customers, invoices, payments, reminders, legal notices, and reports. · `app/(dashboard)`
- [Analytics UI](https://github.com/nishal77/udhaarclear/tree/main/components/analytics): Insights views · Heatmap, predictive, recovery, and digest dashboards backed by API data. · `components/analytics`
- [Settings](https://github.com/nishal77/udhaarclear/tree/main/app/(dashboard)/settings): Tenant config · Profile, billing, team, integrations, webhooks, WhatsApp, and payment settings. · `app/(dashboard)/settings`
- [Team admin](https://github.com/nishal77/udhaarclear/tree/main/app/(dashboard)/team): Workspace mgmt · Business and member administration for multi-user or multi-business usage. · `app/(dashboard)/team`
- [Tone engine](https://github.com/nishal77/udhaarclear/blob/main/app/(dashboard)/tone-engine/page.tsx): Messaging logic · Controls reminder and message tone for recovery communications. · `app/(dashboard)/tone-engine/page.tsx`

### API layer

Route handlers for business operations, analytics, payments, and webhooks.

- [Auth API](https://github.com/nishal77/udhaarclear/tree/main/app/api/auth): OTP backend · Login, signup, verification, and callback endpoints. · `app/api/auth`
- [Business API](https://github.com/nishal77/udhaarclear/tree/main/app/api): CRUD backend · Customers, invoices, dashboard stats, onboarding, and business payment details. · `app/api`
- [Analytics API](https://github.com/nishal77/udhaarclear/tree/main/app/api/analytics): Insight backend · Heatmap, predictive, and recovery data endpoints for dashboard analytics. · `app/api/analytics`
- [Payments API](https://github.com/nishal77/udhaarclear/tree/main/app/api/pay): Payment backend · Payment links, confirm/verify endpoints, and payment-status workflows. · `app/api/pay`
- [Reminder API](https://github.com/nishal77/udhaarclear/tree/main/app/api/reminders): Scheduler API · Reminder creation, reminder sending, and email-open tracking endpoints. · `app/api/reminders`
- [Webhooks](https://github.com/nishal77/udhaarclear/tree/main/app/api/webhooks): Ingress handlers · Razorpay and WhatsApp webhook entrypoints. · `app/api/webhooks`

### Server domain

Reusable auth, services, integrations, validation, and data access code.

- [Auth state](https://github.com/nishal77/udhaarclear/blob/main/lib/auth/otp-cookie.ts): Session/middleware · OTP cookie and auth utilities enforced at the edge boundary. · `lib/auth/otp-cookie.ts`
- [Reminder service](https://github.com/nishal77/udhaarclear/blob/main/lib/services/reminder-service.ts): Domain services · Reminder orchestration and scheduled delivery logic. · `lib/services/reminder-service.ts`
- [Integrations](https://github.com/nishal77/udhaarclear/tree/main/lib): Adapters · Email, WhatsApp, Razorpay, PDF, and payment-routing helpers. · `lib`
- [Data layer](https://github.com/nishal77/udhaarclear/blob/main/lib/prisma/client.ts): Prisma/Supabase · Database client, schema, migrations, and typed contracts. · `lib/prisma/client.ts`

### External systems

Database, payment, email, WhatsApp, and hosting-triggered jobs.

- [Database](https://github.com/nishal77/udhaarclear/blob/main/prisma/schema.prisma): Prisma/Postgres · Persistent store accessed through Prisma and migrations. · `prisma/schema.prisma`
- [Email/WhatsApp](https://github.com/nishal77/udhaarclear/blob/main/lib/email/client.ts): Messaging providers · Outbound OTP, reminder, and notification delivery channels. · `lib/email/client.ts`
- [Razorpay](https://github.com/nishal77/udhaarclear/blob/main/lib/razorpay/client.ts): Payment rail · External payment processor used for links, confirmations, and webhooks. · `lib/razorpay/client.ts`
- [Hosted cron](https://github.com/nishal77/udhaarclear/blob/main/app/api/cron/send-reminders/route.ts): Scheduled trigger · External scheduler that invokes reminder sending. · `app/api/cron/send-reminders/route.ts`

## Connections

- Landing site → Auth pages: start signup · Public visitors move into login or signup flows.
- Auth pages → Auth API: verify OTP · Login and signup screens submit OTP actions to the auth API.
- Auth API → Auth state: set session · Auth handlers read and write OTP/session state.
- Auth state → Email/WhatsApp: send OTP · OTP delivery uses email or other messaging channels.
- Auth API → Onboarding: post-auth · Authenticated users are directed into onboarding before the dashboard.
- Onboarding → Business API: save setup · Onboarding persists business and account setup data.
- Dashboard shell → Receivables: wraps · Shared chrome hosts the primary product areas.
- Dashboard shell → Analytics UI: wraps · Analytics screens use the same authenticated shell.
- Dashboard shell → Settings: wraps · Settings pages live inside the shared dashboard frame.
- Dashboard shell → Team admin: wraps · Team management pages are part of the same workspace shell.
- Dashboard shell → Tone engine: wraps · Tone configuration is exposed as a dashboard area.
- Receivables → Business API: CRUD · Customer, invoice, report, and dashboard pages depend on business APIs.
- Receivables → Payments API: collect · Payment and invoice flows rely on payment endpoints.
- Receivables → Reminder API: remind · Reminder actions and history are driven by reminder APIs.
- Receivables → Webhooks: receive events · Payment and message events feed back through webhook handlers.
- Analytics UI → Analytics API: load insights · Dashboard analytics components consume analytics APIs.
- Settings → Business API: update config · Profile, billing, integrations, and webhook settings persist through APIs.
- Settings → Webhooks: configure · Webhook and provider settings affect incoming event handlers.
- Team admin → Business API: manage workspace · Business and member changes are stored through business APIs.
- Tone engine → Reminder service: shape messaging · Tone controls influence reminder generation and delivery behavior.
- Business API → Data layer: read/write · Business routes persist domain records through the data layer.
- Analytics API → Data layer: aggregate · Analytics handlers derive insights from persisted records.
- Payments API → Integrations: process payments · Payment routes use Razorpay helpers and payment-link utilities.
- Reminder API → Reminder service: orchestrate · Reminder endpoints call the reminder service layer.
- Reminder API → Integrations: deliver · Reminder delivery uses email and WhatsApp adapters.
- Webhooks → Integrations: ingest events · Webhook handlers validate provider payloads and update state.
- Reminder service → Hosted cron: scheduled by · Reminder sending is triggered by an external cron job.
- Reminder service → Email/WhatsApp: send notifications · Service layer dispatches reminder messages through communication providers.
- Integrations → Razorpay: use · Payment helpers connect to Razorpay.
- Integrations → Email/WhatsApp: use · Email and WhatsApp clients connect to delivery providers.
- Data layer → Database: persist · Prisma-backed code stores and reads application data from the database.