Pipelines & Deals
Relevant source files
The following files were used as context for generating this wiki page:
The Pipelines & Deals system is a core component of the CRM module, designed to manage sales cycles and track revenue opportunities. It provides a structured framework for defining sales stages, managing deal flow via visual Kanban boards, and forecasting financial outcomes. This module enables businesses to visualize their sales funnel, prioritize high-value opportunities, and ensure account-scoped data isolation for multi-tenant environments.
The system is built using Domain-Driven Design (DDD) principles, separating domain logic (entities like Pipelines, Stages, and Deals) from infrastructure concerns. It integrates closely with Contacts Management to associate opportunities with individual or company records.
Sources: README.md:27-28, CRM_IMPLEMENTATION_REPORT.md:32-41, backend/src/crm/README.md:14-22
System Architecture
The Pipelines & Deals module follows a clean 4-layer architecture. The domain layer defines the business rules for sales processes, while the application layer orchestrates use cases such as deal forecasting and stage transitions.
Domain Entities & Data Model
The system is modeled around three primary aggregate roots: Pipelines, PipelineStages, and Deals. Deals represent the financial opportunities, which move through sequential Stages defined within a specific Pipeline.
Sources: backend/src/crm/README.md:58-62, CRM_IMPLEMENTATION_REPORT.md:91-105
| Entity | Description | Key Attributes |
|---|---|---|
| Pipeline | Defines a specific sales process. | id, account_id, name |
| PipelineStage | A step within a pipeline with specific probability. | id, pipeline_id, name, probability, order |
| Deal | A specific sales opportunity. | id, name, value_amount (cents), status, stage_id |
Database Relationships
The following Entity-Relationship Diagram illustrates how deals are linked to pipelines and stages while maintaining multi-tenant isolation through account_id.
The data model stores value_amount as integer cents to ensure precision during financial calculations and forecasting.
Sources: backend/src/crm/README.md:118-132, CRM_IMPLEMENTATION_REPORT.md:36-39
Application Logic & Use Cases
The backend provides 14 specific API endpoints for managing the pipeline lifecycle. Key logic includes automated probability overrides during stage movements and financial forecasting.
Sources: CRM_IMPLEMENTATION_REPORT.md:129-145
Forecasting Logic
The forecasting engine calculates revenue based on deal status and stage probability.
- Total Value: Sum of all open deals.
- Weighted Value: Sum of (Deal Value * Stage Probability).
- Won/Lost Values: Aggregates based on the
statusenum (open, won, lost, abandoned).
Sources: CRM_IMPLEMENTATION_REPORT.md:39-41, backend/src/crm/README.md:129-132
API Endpoints
| Method | Endpoint | Description |
|---|---|---|
POST | /api/v1/crm/deals | Creates a new sales opportunity. |
PATCH | /api/v1/crm/deals/{id}/move | Moves a deal to a different stage. |
POST | /api/v1/crm/deals/{id}/win | Marks a deal as won. |
GET | /api/v1/crm/deals/forecast | Returns weighted and total revenue projections. |
Frontend Implementation
The frontend utilizes a visual Kanban board for interactive deal management, allowing users to drag and drop deals between stages.
Kanban Component Architecture
The PipelineKanbanBoard is the primary interface, supported by state management via a specialized useDealStore (Zustand).
The frontend implementation features real-time updates through TanStack Query, which handles the fetching of deals grouped by stage_id.
Sources: frontend/src/app/crm/pipelines/page.tsx:18-36, CRM_FRONTEND_SUMMARY.md:37-41
User Interface Features
- Pipeline Selector: A dropdown to switch between different sales processes (e.g., "Sales Pipeline" vs "Onboarding").
- Deal Cards: Display key metadata including value, priority, and associated contact.
- Drag & Drop: Powered by
dnd-kit, allowing users to update a deal's stage ID by moving cards between columns. - Status Management: Visual badges indicate if a deal is "Open", "Won", or "Lost".
Sources: frontend/src/app/crm/pipelines/page.tsx:84-118, CRM_FRONTEND_SUMMARY.md:10-15
Conclusion
The Pipelines & Deals system provides a robust framework for revenue tracking within the GoHighLevel Clone. By combining a precise backend data model (integer cents and weighted forecasting) with a highly interactive frontend (Kanban board with drag-and-drop), the system ensures that sales teams can effectively manage their pipeline while maintaining the strict multi-tenant security required for enterprise applications.
Sources: CRM_IMPLEMENTATION_REPORT.md:213-225, backend/src/crm/README.md:231-236