premwizard/crm

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.