# premwizard/crm architecture

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

- Interactive diagram: https://gitdiagram.com/premwizard/crm
- Repository: https://github.com/premwizard/crm

## Overview

#### Purpose and deployment shape
IC CRM is a multi-tenant sales CRM for companies, contacts, leads, deals, tasks, activities, notes, tags, segments, and reporting. It has two independently runnable TypeScript services: a Next.js 15 App Router application and API surface, plus a standalone Express API server. Both target PostgreSQL through Prisma. Core entry points are `frontend/src/app/page.tsx`, `frontend/src/app/layout.tsx`, and `backend/src/app.ts`.

#### Web workspace and navigation
The Next.js application provides authentication pages and an authenticated dashboard workspace. Dashboard layout, header/sidebar navigation, and client-side providers form the UI boundary around CRM pages. Key paths: `frontend/src/app/(dashboard)/layout.tsx`, `frontend/src/components/layout/header.tsx`, `frontend/src/components/providers/auth-provider.tsx`.

#### API boundary: parallel implementations
The repository exposes REST resources under `/api/v1` through Next.js route handlers, while Express implements a corresponding route-oriented API. Consumers should select/configure one API host deliberately; these are parallel server surfaces rather than a single layered request path. Representative paths: `frontend/src/app/api/v1/companies/route.ts`, `frontend/src/app/api/v1/leads/[id]/convert/route.ts`, `backend/src/routes/companies.ts`.

#### Identity, tenancy, and authorization
JWT authentication and bcrypt password handling protect application/API access. The frontend uses route middleware and auth utilities; Express enforces auth through middleware before protected routes. The schema defines users, organizations, and memberships, establishing the tenant boundary that business queries must preserve. Paths: `frontend/src/middleware.ts`, `frontend/src/lib/auth.ts`, `backend/src/middleware/auth.ts`.

#### CRM entity lifecycle
Companies, contacts, leads, and deals are the principal sales records. Lead conversion is a critical transactional workflow: eligible leads create or associate Company and Contact records, create a Deal, record conversion relations, and prevent invalid reconversion. Deal updates support pipeline stages, weighted forecasting, stage history, and activity logging. Paths: `frontend/src/app/api/v1/leads/[id]/convert/route.ts`, `frontend/src/components/leads/lead-convert-modal.tsx`, `frontend/src/components/deals/deal-kanban-board.tsx`.

#### Cross-cutting engagement records
Tasks, activities, notes, and tags attach to primary CRM entities, making detail views aggregation points rather than isolated resource screens. Timeline, task, note, and tag components call entity-filtered APIs and present shared operational context. Paths: `frontend/src/components/timeline/activity-timeline.tsx`, `frontend/src/components/tasks/entity-tasks.tsx`, `frontend/src/components/notes/entity-notes.tsx`.

#### Data operations and analytics
List endpoints support server-side pagination, sorting, filters, bulk actions, CSV import/export, global search, saved segments, dashboards, forecasts, and report generation. These operations should remain server-side against Prisma/PostgreSQL rather than loading full datasets into the browser. Paths: `frontend/src/app/api/v1/search/route.ts`, `frontend/src/app/api/v1/import/execute/route.ts`, `frontend/src/app/api/v1/reports/generate/route.ts`.

#### Persistence and runtime infrastructure
PostgreSQL 16 is the only stated external datastore; Prisma is the persistence boundary and schema authority, with separate schema copies per service. Next.js runs the React UI and serverless-style route handlers; Node.js/Express runs separately, with CORS configured. Paths: `frontend/prisma/schema.prisma`, `frontend/src/lib/db.ts`, `backend/prisma/schema.prisma`.

Main entry points: [`frontend/src/app/api/v1/companies/route.ts`](https://github.com/premwizard/crm/blob/main/frontend/src/app/api/v1/companies/route.ts) (Next REST API), [`frontend/src/app/(dashboard)/layout.tsx`](https://github.com/premwizard/crm/blob/main/frontend/src/app/(dashboard)/layout.tsx) (Dashboard Workspace), [`backend/src/routes/companies.ts`](https://github.com/premwizard/crm/blob/main/backend/src/routes/companies.ts) (Express CRM Routes), [`frontend/src/lib/db.ts`](https://github.com/premwizard/crm/blob/main/frontend/src/lib/db.ts) (Frontend Prisma)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Next.js Web App"]
  node_next_entry["Next.js App Router<br/>web runtime<br/>[page.tsx]"]
  node_dashboard_shell["Dashboard Workspace<br/>authenticated UI<br/>[layout.tsx]"]
  node_next_auth["Web Auth Guard<br/>JWT middleware<br/>[middleware.ts]"]
  node_next_api{{"Next REST API<br/>route handlers<br/>[route.ts]"}}
  node_lead_conversion_ui["Lead Conversion UI<br/>CRM workflow UI"]
  node_deal_pipeline_ui["Deal Pipeline UI<br/>Kanban UI"]
  node_engagement_ui["Engagement Detail UI<br/>shared entity views"]
  node_data_operations["Data Operations &amp; Analytics<br/>server-side operations<br/>[route.ts]"]
end

subgraph group_express["Express API"]
  node_express_app["Express Server<br/>Node.js runtime<br/>[app.ts]"]
  node_express_auth["Express Auth Middleware<br/>JWT middleware<br/>[auth.ts]"]
  node_express_routes{{"Express CRM Routes<br/>REST routes<br/>[companies.ts]"}}
end

subgraph group_data["Persistence"]
  node_frontend_prisma["Frontend Prisma<br/>persistence boundary<br/>[db.ts]"]
  node_frontend_schema["Frontend Schema<br/>Prisma schema<br/>[schema.prisma]"]
  node_backend_schema["Backend Schema<br/>Prisma schema<br/>[schema.prisma]"]
  node_postgres[("PostgreSQL 16<br/>database")]
end

node_identity_tenancy["Identity &amp; Tenancy<br/>domain boundary"]
node_sales_lifecycle["Sales Lifecycle<br/>CRM domain workflow<br/>[route.ts]"]
node_engagement_records["Engagement Records<br/>CRM domain records<br/>[entity-tasks.tsx]"]

node_next_entry -->|"renders authenticated workspace"| node_dashboard_shell
node_next_auth -->|"protects"| node_dashboard_shell
node_dashboard_shell -->|"hosts"| node_lead_conversion_ui
node_dashboard_shell -->|"hosts"| node_deal_pipeline_ui
node_dashboard_shell -->|"hosts"| node_engagement_ui
node_lead_conversion_ui -->|"calls"| node_next_api
node_deal_pipeline_ui -->|"calls"| node_next_api
node_engagement_ui -->|"queries filtered records"| node_next_api
node_next_auth -->|"guards"| node_next_api
node_next_api -->|"enforces tenant scope"| node_identity_tenancy
node_next_api -->|"serves"| node_sales_lifecycle
node_next_api -->|"serves"| node_engagement_records
node_next_api -->|"runs"| node_data_operations
node_sales_lifecycle -->|"logs deal activity"| node_engagement_records
node_next_api -->|"persists through"| node_frontend_prisma
node_frontend_prisma -.->|"uses"| node_frontend_schema
node_frontend_prisma -->|"queries"| node_postgres
node_express_app -->|"applies"| node_express_auth
node_express_auth -->|"authorizes"| node_express_routes
node_express_routes -->|"enforces tenant scope"| node_identity_tenancy
node_express_routes -->|"persists via Prisma"| node_postgres
node_backend_schema -.->|"models"| node_postgres
node_next_api -.->|"parallel API surface; choose one host"| node_express_routes

click node_next_entry "https://github.com/premwizard/crm/blob/main/frontend/src/app/page.tsx"
click node_dashboard_shell "https://github.com/premwizard/crm/blob/main/frontend/src/app/(dashboard)/layout.tsx"
click node_next_auth "https://github.com/premwizard/crm/blob/main/frontend/src/middleware.ts"
click node_next_api "https://github.com/premwizard/crm/blob/main/frontend/src/app/api/v1/companies/route.ts"
click node_lead_conversion_ui "https://github.com/premwizard/crm/blob/main/frontend/src/components/leads/lead-convert-modal.tsx"
click node_deal_pipeline_ui "https://github.com/premwizard/crm/blob/main/frontend/src/components/deals/deal-kanban-board.tsx"
click node_engagement_ui "https://github.com/premwizard/crm/blob/main/frontend/src/components/timeline/activity-timeline.tsx"
click node_express_app "https://github.com/premwizard/crm/blob/main/backend/src/app.ts"
click node_express_auth "https://github.com/premwizard/crm/blob/main/backend/src/middleware/auth.ts"
click node_express_routes "https://github.com/premwizard/crm/blob/main/backend/src/routes/companies.ts"
click node_sales_lifecycle "https://github.com/premwizard/crm/blob/main/frontend/src/app/api/v1/leads/%5Bid%5D/convert/route.ts"
click node_engagement_records "https://github.com/premwizard/crm/blob/main/frontend/src/components/tasks/entity-tasks.tsx"
click node_data_operations "https://github.com/premwizard/crm/blob/main/frontend/src/app/api/v1/reports/generate/route.ts"
click node_frontend_prisma "https://github.com/premwizard/crm/blob/main/frontend/src/lib/db.ts"
click node_frontend_schema "https://github.com/premwizard/crm/blob/main/frontend/prisma/schema.prisma"
click node_backend_schema "https://github.com/premwizard/crm/blob/main/backend/prisma/schema.prisma"

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_next_entry,node_dashboard_shell,node_next_auth,node_next_api,node_lead_conversion_ui,node_deal_pipeline_ui,node_engagement_ui,node_data_operations toneBlue
class node_express_app,node_express_auth,node_express_routes toneAmber
class node_frontend_prisma,node_frontend_schema,node_backend_schema,node_postgres toneMint
class node_identity_tenancy,node_sales_lifecycle,node_engagement_records toneNeutral
```

## Components

### Next.js Web App

React workspace and parallel API handlers.

- [Next.js App Router](https://github.com/premwizard/crm/blob/main/frontend/src/app/page.tsx): web runtime · Renders public and authenticated CRM application pages. · `frontend/src/app/page.tsx`
- [Dashboard Workspace](https://github.com/premwizard/crm/blob/main/frontend/src/app/(dashboard)/layout.tsx): authenticated UI · Layout, navigation, and auth provider surround CRM pages. · `frontend/src/app/(dashboard)/layout.tsx`
- [Web Auth Guard](https://github.com/premwizard/crm/blob/main/frontend/src/middleware.ts): JWT middleware · Protects routes using frontend authentication utilities. · `frontend/src/middleware.ts`
- [Next REST API](https://github.com/premwizard/crm/blob/main/frontend/src/app/api/v1/companies/route.ts): route handlers · Parallel /api/v1 server surface. · `frontend/src/app/api/v1/companies/route.ts`
- [Lead Conversion UI](https://github.com/premwizard/crm/blob/main/frontend/src/components/leads/lead-convert-modal.tsx): CRM workflow UI · Initiates transactional lead conversion. · `frontend/src/components/leads/lead-convert-modal.tsx`
- [Deal Pipeline UI](https://github.com/premwizard/crm/blob/main/frontend/src/components/deals/deal-kanban-board.tsx): Kanban UI · Presents deal stages and forecasting workflow. · `frontend/src/components/deals/deal-kanban-board.tsx`
- [Engagement Detail UI](https://github.com/premwizard/crm/blob/main/frontend/src/components/timeline/activity-timeline.tsx): shared entity views · Shows activities, tasks, notes, and tags for CRM records. · `frontend/src/components/timeline/activity-timeline.tsx`
- [Data Operations & Analytics](https://github.com/premwizard/crm/blob/main/frontend/src/app/api/v1/reports/generate/route.ts): server-side operations · Search, bulk work, CSV, segments, dashboards, forecasts, and reports. · `frontend/src/app/api/v1/reports/generate/route.ts`

### Express API

Independently runnable Node.js API.

- [Express Server](https://github.com/premwizard/crm/blob/main/backend/src/app.ts): Node.js runtime · Separate CORS-enabled REST API host. · `backend/src/app.ts`
- [Express Auth Middleware](https://github.com/premwizard/crm/blob/main/backend/src/middleware/auth.ts): JWT middleware · Authenticates protected Express routes. · `backend/src/middleware/auth.ts`
- [Express CRM Routes](https://github.com/premwizard/crm/blob/main/backend/src/routes/companies.ts): REST routes · Corresponding route-oriented API resources. · `backend/src/routes/companies.ts`

### Persistence

Separate Prisma schema authority for each runtime.

- [Frontend Prisma](https://github.com/premwizard/crm/blob/main/frontend/src/lib/db.ts): persistence boundary · Prisma client and schema for Next.js handlers. · `frontend/src/lib/db.ts`
- [Frontend Schema](https://github.com/premwizard/crm/blob/main/frontend/prisma/schema.prisma): Prisma schema · Frontend runtime schema authority. · `frontend/prisma/schema.prisma`
- [Backend Schema](https://github.com/premwizard/crm/blob/main/backend/prisma/schema.prisma): Prisma schema · Express runtime schema authority. · `backend/prisma/schema.prisma`
- **PostgreSQL 16**: database · Only stated external datastore.

### Other components

- **Identity & Tenancy**: domain boundary · Users, organizations, and memberships scope tenant access.
- [Sales Lifecycle](https://github.com/premwizard/crm/blob/main/frontend/src/app/api/v1/leads/%5Bid%5D/convert/route.ts): CRM domain workflow · Companies, contacts, leads, deals, conversion, stages, and forecasts. · `frontend/src/app/api/v1/leads/[id]/convert/route.ts`
- [Engagement Records](https://github.com/premwizard/crm/blob/main/frontend/src/components/tasks/entity-tasks.tsx): CRM domain records · Tasks, activities, notes, and tags attach to primary entities. · `frontend/src/components/tasks/entity-tasks.tsx`

## Connections

- Next.js App Router → Dashboard Workspace: renders authenticated workspace
- Web Auth Guard → Dashboard Workspace: protects
- Dashboard Workspace → Lead Conversion UI: hosts
- Dashboard Workspace → Deal Pipeline UI: hosts
- Dashboard Workspace → Engagement Detail UI: hosts
- Lead Conversion UI → Next REST API: calls
- Deal Pipeline UI → Next REST API: calls
- Engagement Detail UI → Next REST API: queries filtered records
- Web Auth Guard → Next REST API: guards
- Next REST API → Identity & Tenancy: enforces tenant scope
- Next REST API → Sales Lifecycle: serves
- Next REST API → Engagement Records: serves
- Next REST API → Data Operations & Analytics: runs
- Sales Lifecycle → Engagement Records: logs deal activity
- Next REST API → Frontend Prisma: persists through
- Frontend Prisma → Frontend Schema: uses
- Frontend Prisma → PostgreSQL 16: queries
- Express Server → Express Auth Middleware: applies
- Express Auth Middleware → Express CRM Routes: authorizes
- Express CRM Routes → Identity & Tenancy: enforces tenant scope
- Express CRM Routes → PostgreSQL 16: persists via Prisma
- Backend Schema → PostgreSQL 16: models
- Next REST API → Express CRM Routes: parallel API surface; choose one host