# rahul1015s/crm architecture

> Architecture diagram of the GitHub repository rahul1015s/crm, 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/crm
- Repository: https://github.com/rahul1015s/crm

## Overview

1. This repository is a Next.js App Router CRM built around server-rendered pages plus a large REST-like API surface under `app/api`. The UI is organized by business domain rather than by technical layer, which makes it a classic “page routes + shared components + server endpoints” architecture.

2. The top-level user experience is split into two major areas: authenticated CRM/product workflows and public/auth flows. Public auth lives under `app/(auth)` with dedicated pages for login, signup, magic link, forgot/reset password, and two-factor. The authenticated app exposes dashboard, leads, deals, clients/customers, companies, proposals, reminders, reports, users, settings, and a CRM-specific shell under `app/crm`.

3. The CRM area is the main domain boundary. `components/crm/*` contains specialized submodules for activities, leads, marketing, and pipeline, and `app/crm/*` provides route-level shells with loading/error states. This suggests the CRM experience is a composed workspace that groups multiple operational tools under one navigation context.

4. Core business objects are modeled as separate resource domains with CRUD-style routes and pages: leads, deals, customers/clients, companies, proposals, tasks, reminders, activities, campaigns, pipelines, and users. Most entities have list/detail/edit/new routes in `app/`, while API handlers in `app/api/<domain>` expose create/read/update/delete and workflow-specific actions such as stage changes, receipt generation, PDF generation, completion, scoring, and launches.

5. The server boundary is explicit. `app/api/.../route.ts` files implement the backend entry points, and `app/actions/crm.ts` indicates some mutations are also invoked through server actions. Client code appears to use `lib/api-client.ts`, `lib/api.ts`, and `lib/server-api.ts` as the abstraction layer for talking to those endpoints.

6. Persistence is MongoDB-centric, with both `models/` and `lib/db/` present. `models/*` holds Mongoose models, while `lib/db/schemas/*` and `lib/db/queries/*` suggest a newer or parallel typed data-access layer for querying and shaping records. `lib/mongodb.ts` and `lib/db.ts` are the connection/bootstrap points, and `lib/db/filters.ts` indicates tenant-aware or scoped querying.

7. Auth is not just login/logout; it includes session handling, OTP verification, magic links, password reset, and email-based workflows. The supporting code lives in `lib/auth/*` for session cookies, session state, password helpers, tenant context, API protection, and demo-user support. `proxy.ts` likely enforces route-level access control before requests reach the app.

8. Several cross-cutting business services sit in `lib/`: lead scoring, lead routing, forecasting, proposals, permissions, plan limits, pagination, rate limiting, and CRM utilities. These are the domain rules that the UI and API layers share, and they are what make the app more than a thin CRUD shell.

9. Marketing and analytics are first-class modules rather than reports-only features. There are endpoints and components for campaign analytics, A/B testing, email sequences, conversion tracking, pipeline forecasting, pattern insights, attention counts, and global analytics views. `components/crm/marketing/*`, `components/pattern-insights/*`, and `app/pattern-insights` show that dashboards are built from domain data, not from a separate BI system.

10. Activity management is another major workflow with its own sub-ecosystem: calendar, feed, call logging, meeting scheduling, task boards, and upcoming tasks. The corresponding API routes under `app/api/activities/*` indicate that activities are normalized records that feed multiple surfaces, not a single page.

11. Email and notifications are integrated into the business flows. `lib/email/mailer.ts` handles outbound mail, while auth and campaign features depend on it for password resets, magic links, and marketing delivery. `app/api/notifications` and `components/notifications-bell.tsx` suggest in-app notifications are part of the interaction loop as well.

12. The UI layer is built from reusable domain components plus a shared design system. `components/ui/*` provides Radix/Tailwind-based primitives, while domain components like tables, forms, modals, kanban boards, calendars, and dashboards compose those primitives into feature screens. Theme support is centralized through `components/theme-provider.tsx` and `components/theme-toggle.tsx`.

13. Operationally, the repo includes seeding and migration scripts under `scripts/`, which implies the data model evolves outside the request path. Combined with `.env.example`, the app is designed to be deployed with MongoDB, optional Redis for rate limiting/session-related features, and email infrastructure.

14. In architecture-diagram terms, the clearest boundaries are: browser/UI routes in `app/`, shared feature components in `components/`, business logic in `lib/`, persistence in `models/` and `lib/db/`, and external services such as MongoDB, Redis, and email. The main data flow is user interaction → page/component → API/server action → domain logic → database/service → response back into domain UI.

Main entry points: [`app/api`](https://github.com/rahul1015s/crm/tree/main/app/api) (CRM API), [`app/api/auth`](https://github.com/rahul1015s/crm/tree/main/app/api/auth) (Auth API), [`lib/auth`](https://github.com/rahul1015s/crm/tree/main/lib/auth) (Auth core), [`components/crm`](https://github.com/rahul1015s/crm/tree/main/components/crm) (CRM UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App routes"]
  node_app_public_auth["Auth flows<br/>route group"]
  node_app_dashboard["Dashboard<br/>page<br/>[page.tsx]"]
  node_app_crm_shell["CRM shell<br/>route shell"]
  node_app_crm_routes["CRM routes<br/>route group"]
  node_app_business_pages["Business pages<br/>page group"]
  node_app_api_auth["Auth API<br/>endpoint group"]
  node_app_api_crm["CRM API<br/>endpoint group"]
  node_app_actions_crm["CRM actions<br/>server actions<br/>[crm.ts]"]
end

subgraph group_components["Components"]
  node_ui_kit["UI kit<br/>design system"]
  node_crm_ui["CRM UI<br/>domain UI"]
  node_domain_forms["Domain forms<br/>feature components"]
  node_auth_support["Auth UI<br/>feature components"]
end

subgraph group_lib["Core logic"]
  node_lib_api_client["API clients<br/>client/server adapters<br/>[api-client.ts]"]
  node_lib_auth["Auth core<br/>security/session"]
  node_lib_domain["Domain logic<br/>business services"]
  node_lib_email["Email service<br/>mailer<br/>[mailer.ts]"]
end

subgraph group_data["Data layer"]
  node_lib_data["DB access<br/>data access"]
  node_models["Models"]
end

node_external_db[("MongoDB<br/>database")]
node_external_redis[("Redis<br/>cache")]
node_external_mail["Mail provider<br/>external service"]

node_app_public_auth -->|"renders"| node_auth_support
node_app_public_auth -->|"submits"| node_app_api_auth
node_app_dashboard -->|"composes"| node_crm_ui
node_app_crm_shell -->|"wraps"| node_crm_ui
node_app_crm_routes -->|"renders"| node_crm_ui
node_app_business_pages -->|"renders"| node_domain_forms
node_app_business_pages -->|"fetches"| node_lib_api_client
node_app_api_auth -->|"uses"| node_lib_auth
node_app_api_auth -->|"sends"| node_lib_email
node_app_api_crm -->|"applies"| node_lib_domain
node_app_api_crm -->|"queries"| node_lib_data
node_app_actions_crm -->|"delegates"| node_lib_domain
node_crm_ui -->|"uses"| node_lib_domain
node_domain_forms -->|"uses"| node_lib_domain
node_auth_support -->|"uses"| node_lib_auth
node_lib_api_client -->|"calls"| node_app_api_crm
node_lib_api_client -->|"calls"| node_app_api_auth
node_lib_auth -->|"stores"| node_external_db
node_lib_auth -->|"limits"| node_external_redis
node_lib_email -->|"delivers"| node_external_mail
node_lib_data -->|"maps"| node_models
node_models -->|"persists"| node_external_db
node_lib_data -->|"connects"| node_external_db
node_app_api_crm -->|"reads/writes"| node_external_db

click node_app_public_auth "https://github.com/rahul1015s/crm/tree/main/app/(auth)"
click node_app_dashboard "https://github.com/rahul1015s/crm/blob/main/app/dashboard/page.tsx"
click node_app_crm_shell "https://github.com/rahul1015s/crm/tree/main/app/crm"
click node_app_crm_routes "https://github.com/rahul1015s/crm/tree/main/app/crm"
click node_app_business_pages "https://github.com/rahul1015s/crm/tree/main/app"
click node_app_api_auth "https://github.com/rahul1015s/crm/tree/main/app/api/auth"
click node_app_api_crm "https://github.com/rahul1015s/crm/tree/main/app/api"
click node_app_actions_crm "https://github.com/rahul1015s/crm/blob/main/app/actions/crm.ts"
click node_ui_kit "https://github.com/rahul1015s/crm/tree/main/components/ui"
click node_crm_ui "https://github.com/rahul1015s/crm/tree/main/components/crm"
click node_domain_forms "https://github.com/rahul1015s/crm/tree/main/components"
click node_auth_support "https://github.com/rahul1015s/crm/tree/main/components/auth"
click node_lib_api_client "https://github.com/rahul1015s/crm/blob/main/lib/api-client.ts"
click node_lib_auth "https://github.com/rahul1015s/crm/tree/main/lib/auth"
click node_lib_domain "https://github.com/rahul1015s/crm/tree/main/lib"
click node_lib_email "https://github.com/rahul1015s/crm/blob/main/lib/email/mailer.ts"
click node_lib_data "https://github.com/rahul1015s/crm/tree/main/lib/db"
click node_models "https://github.com/rahul1015s/crm/tree/main/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_public_auth,node_app_dashboard,node_app_crm_shell,node_app_crm_routes,node_app_business_pages,node_app_api_auth,node_app_api_crm,node_app_actions_crm toneBlue
class node_ui_kit,node_crm_ui,node_domain_forms,node_auth_support toneAmber
class node_lib_api_client,node_lib_auth,node_lib_domain,node_lib_email toneMint
class node_lib_data,node_models toneRose
class node_external_db,node_external_redis,node_external_mail toneNeutral
```

## Components

### App routes

Next.js App Router pages, shells, and API endpoints

- [Auth flows](https://github.com/rahul1015s/crm/tree/main/app/(auth)): route group · Public login, signup, password reset, magic link, and two-factor pages · `app/(auth)`
- [Dashboard](https://github.com/rahul1015s/crm/blob/main/app/dashboard/page.tsx): page · Authenticated landing dashboard · `app/dashboard/page.tsx`
- [CRM shell](https://github.com/rahul1015s/crm/tree/main/app/crm): route shell · CRM workspace layout with loading and error states · `app/crm`
- [CRM routes](https://github.com/rahul1015s/crm/tree/main/app/crm): route group · CRM subroutes for leads, activities, marketing, and pipeline · `app/crm`
- [Business pages](https://github.com/rahul1015s/crm/tree/main/app): page group · Resource pages for leads, deals, clients, companies, proposals, reminders, reports, users, settings, and pattern insights · `app`
- [Auth API](https://github.com/rahul1015s/crm/tree/main/app/api/auth): endpoint group · Authentication, session, OTP, and email verification endpoints · `app/api/auth`
- [CRM API](https://github.com/rahul1015s/crm/tree/main/app/api): endpoint group · Core CRUD and workflow endpoints for CRM resources · `app/api`
- [CRM actions](https://github.com/rahul1015s/crm/blob/main/app/actions/crm.ts): server actions · Server actions for CRM mutations · `app/actions/crm.ts`

### Components

Reusable domain UI and shared design system

- [UI kit](https://github.com/rahul1015s/crm/tree/main/components/ui): design system · Shared Radix/Tailwind primitives · `components/ui`
- [CRM UI](https://github.com/rahul1015s/crm/tree/main/components/crm): domain UI · Specialized CRM modules for activities, leads, marketing, and pipeline · `components/crm`
- [Domain forms](https://github.com/rahul1015s/crm/tree/main/components): feature components · Forms, tables, and detail shells for leads, deals, clients, companies, proposals, and activities · `components`
- [Auth UI](https://github.com/rahul1015s/crm/tree/main/components/auth): feature components · Login, signup, reset, OTP, and auth card components · `components/auth`

### Core logic

Authentication, domain services, API clients, and helpers

- [API clients](https://github.com/rahul1015s/crm/blob/main/lib/api-client.ts): client/server adapters · Browser and server abstractions for calling app APIs · `lib/api-client.ts`
- [Auth core](https://github.com/rahul1015s/crm/tree/main/lib/auth): security/session · Session cookies, auth protection, tenant context, password helpers, and demo-user support · `lib/auth`
- [Domain logic](https://github.com/rahul1015s/crm/tree/main/lib): business services · Lead scoring, routing, forecasting, proposals, permissions, plan limits, pagination, rate limiting, and CRM utilities · `lib`
- [Email service](https://github.com/rahul1015s/crm/blob/main/lib/email/mailer.ts): mailer · Outbound email delivery used by auth and marketing flows · `lib/email/mailer.ts`

### Data layer

Mongoose models, typed schemas, and query layer

- [DB access](https://github.com/rahul1015s/crm/tree/main/lib/db): data access · Mongo bootstrap, typed queries, filters, and schema definitions · `lib/db`
- [Models](https://github.com/rahul1015s/crm/tree/main/models): mongoose models · Mongoose models for activities, campaigns, customers, deals, leads, pipelines, proposals, routing rules, tasks, and users · `models`

### Other components

- **MongoDB**: database · Primary persistence store
- **Redis**: cache · Optional rate limiting and session-related infrastructure
- **Mail provider**: external service · Email transport for login, reset, and marketing workflows

## Connections

- Auth flows → Auth UI: renders · Auth pages are composed from dedicated auth components
- Auth flows → Auth API: submits · Forms and flows call authentication endpoints
- Dashboard → CRM UI: composes · Dashboard pulls in shared CRM-facing UI patterns
- CRM shell → CRM UI: wraps · CRM shell provides the workspace around CRM feature modules
- CRM routes → CRM UI: renders · CRM subroutes use specialized CRM components
- Business pages → Domain forms: renders · Business pages are built from resource-specific tables, forms, and shells
- Business pages → API clients: fetches · Pages and client components use API helpers for data access
- Auth API → Auth core: uses · Auth endpoints rely on session and protection logic
- Auth API → Email service: sends · Magic links and password flows send email
- CRM API → Domain logic: applies · Resource endpoints execute shared business rules
- CRM API → DB access: queries · API routes read and shape data through the DB layer
- CRM actions → Domain logic: delegates · Server actions reuse domain services for mutations
- CRM UI → Domain logic: uses · CRM widgets depend on shared CRM logic
- Domain forms → Domain logic: uses · Feature UI uses domain helpers for workflows and validation
- Auth UI → Auth core: uses · Auth components depend on session and OTP helpers
- API clients → CRM API: calls · Client and server adapters talk to CRM endpoints
- API clients → Auth API: calls · Client and server adapters talk to auth endpoints
- Auth core → MongoDB: stores · Sessions and user state persist in MongoDB-backed storage
- Auth core → Redis: limits · Rate limiting and protection can use Redis
- Email service → Mail provider: delivers · Outbound messages go through an email provider
- DB access → Models: maps · Typed queries and schemas are backed by Mongoose models
- Models → MongoDB: persists · Models persist application records in MongoDB
- DB access → MongoDB: connects · DB bootstrap and query layer connect to MongoDB
- CRM API → MongoDB: reads/writes · CRM endpoints persist resource changes through the database layer
