Contact Management
Relevant source files
The following files were used as context for generating this wiki page:
Contact Management is a core module within the CRM system designed to handle the lifecycle and data of individual leads and customers. It provides comprehensive tools for creating, updating, searching, and organizing contacts through tags and custom fields, ensuring account-level data isolation in a multi-tenant environment.
This module acts as the foundation for other CRM features, such as Pipelines & Deals and Activities/Tasks, by providing the primary entity (the Contact) to which these records are associated.
Sources: backend/src/crm/README.md, CRM_IMPLEMENTATION_REPORT.md:20-30
Domain Architecture
The contact system is built on Domain-Driven Design (DDD) principles, utilizing the Contact entity as an aggregate root. The domain layer enforces business rules such as email and phone number validation and ensures that every contact is linked to a specific account for multi-tenancy.
Core Entities and Value Objects
The system defines several key components in the domain layer to maintain data integrity:
- Contact Entity: The central record containing personal info, contact details, and metadata.
- Email/PhoneNumber Value Objects: Enforce RFC 5322 and E.164 compliance respectively.
- Tag Entity: Used for categorization and filtering.
Application Logic and Use Cases
The application layer orchestrates 8 primary use cases to handle contact operations. These use cases ensure that business logic is applied before infrastructure (database) persistence occurs.
| Use Case | Description |
|---|---|
| CreateContact | Validates input (email/phone) and persists a new contact record. |
| UpdateContact | Modifies existing fields while maintaining audit timestamps. |
| BulkImport | Handles up to 1000 contacts per request with duplicate detection. |
| Add/RemoveTag | Manages the association between contacts and labels. |
| SearchContacts | Performs full-text search across names and emails using GIN indexes. |
Sources: backend/src/crm/application/use_cases/contacts.py, CRM_IMPLEMENTATION_REPORT.md:140-150, specs/crm/contacts.yaml:15-30
Data Flow: Contact Creation
The creation of a contact involves a flow from the presentation layer through the application use cases to the infrastructure persistence.
Frontend Implementation
The frontend is implemented using Next.js 14 and React 19, providing a highly interactive interface for managing contacts. The primary page utilizes Zustand for state management and TanStack Query for server-side state synchronization.
Key Components
- ContactListTable: A table with search, advanced filters, and pagination.
- BulkActionsBar: Enables operations like mass deletion, tagging, or exporting to CSV.
- ContactImportModal: Interface for CSV column mapping.
- ContactStatusBadge: Displays lifecycle stages (Lead, Prospect, Customer, etc.).
Database Schema
The infrastructure layer uses a relational schema with a strong focus on performance through composite and GIN indexing.
Conclusion
The Contact Management module provides a robust, DDD-compliant foundation for the CRM. By leveraging strict domain validation, multi-tenant isolation, and a modern frontend stack, it allows users to efficiently manage thousands of records with high search performance and rich categorization capabilities.
Sources: CRM_IMPLEMENTATION_REPORT.md:280-300, FINAL_REPORT.md