Frappe CRM: Technical Documentation

Overview

Frappe CRM is an open-source Customer Relationship Management application built on the Frappe Framework. It provides a modern, feature-rich solution for managing customer relationships, deals, leads, communications, and more.

Architecture

Tech Stack

• Backend: Python with Frappe Framework
• Frontend: Vue.js with Tailwind CSS
• Database: MariaDB (via Frappe)
• Authentication: Frappe's authentication system

Directory Structure

crm/
├── crm/                      # Python backend code
│   ├── api/                  # API endpoints
│   ├── fcrm/                 # DocType definitions
│   │   └── doctype/          # Document types
│   ├── hooks.py              # Frappe hooks configuration
│   ├── install.py            # Installation utilities
│   ├── templates/            # Templates
│   ├── public/               # Public assets
│   └── www/                  # Web pages
│
├── frontend/                 # Vue.js frontend code
│   ├── src/                  # Source code
│   │   ├── components/       # Vue components
│   │   │   ├── Common/       # Common components
│   │   │   ├── Dashboard/    # Dashboard components
│   │   │   ├── Deal/         # Deal-related components
│   │   │   ├── Lead/         # Lead-related components
│   │   │   └── ...           # Other component groups
│   │   │
│   │   └── pages/            # Vue pages
│   │       ├── Dashboard.vue # Dashboard page
│   │       ├── Lead.vue      # Lead page
│   │       ├── Deal.vue      # Deal page
│   │       └── ...           # Other pages
│   │
│   └── docs/                 # Frontend documentation
│
└── ...                       # Other files and directories

Core Modules

1. Lead Management

The Lead Management module allows tracking potential customers before they convert to deals or customers. Key features include:

• Lead capturing and tracking
• Lead status workflow management
• Lead qualification and conversion
• Custom lead fields and layouts

Key DocTypes: - CRM Lead - CRM Lead Status - CRM Lead Source

2. Deal Management

The Deal Management module helps track sales opportunities. Key features include:

• Deal pipeline visualization
• Deal status workflow management
• Deal tracking with probability, value, and expected closing date
• Deal conversion tracking

Key DocTypes: - CRM Deal - CRM Deal Status - CRM Deal Type

3. Contact and Organization Management

Manages contacts and their associated organizations. Features include:

• Contact information management
• Organization details tracking
• Relationship mapping between contacts and organizations
• Communication history

Key DocTypes: - Contact (Overridden from Frappe core) - CRM Organization - CRM Contacts

4. Communication

Handles all forms of communication with contacts. Features include:

• Email tracking
• Call logging
• WhatsApp integration (via Twilio)
• Communication status tracking

Key DocTypes: - CRM Communication Status - CRM Call Log - WhatsApp Message (Integration)

5. Quotation Management

Handles the creation and management of quotations. Features include:

• Quotation creation and tracking
• Quotation conversion to deals
• Quotation templates

Key DocTypes: - CRM Quotation

6. Contract Management

Manages contracts with customers. Features include:

• Contract creation and tracking
• Contract renewal management
• Contract terms and items

Key DocTypes: - CRM Contract - CRM Contract Item

7. Task Management

Tracks tasks related to leads, deals, contacts, etc. Features include:

• Task assignment
• Task status tracking
• Due date management
• Task categorization

Key DocTypes: - CRM Task

Frontend Architecture

The frontend is built using Vue.js with a component-based architecture. Key features include:

Components

1. Layout Components

   • Navbar, sidebar, and main content layout
   • Responsive design for mobile and desktop

2. Common Components

   • Reusable UI elements like buttons, inputs, cards
   • Specialized CRM components like KPI metrics, activity timelines

3. Page Components

   • Dashboard
   • Lead/Deal/Contact/Organization views
   • Settings pages

UI/UX Features

• Responsive design with Tailwind CSS
• Interactive charts and visualizations
• Kanban board views for deals
• List views with customizable columns

API Integration

Key API Endpoints

1. Document Management

   • /api/resource/<doctype>: CRUD operations for documents
   • /api/method/crm.api.doc.*: Custom document operations

2. Authentication

   • /api/method/crm.api.auth.*: Authentication endpoints

3. Communication

   • /api/method/crm.api.activities.*: Activity logging
   • /api/method/crm.api.whatsapp.*: WhatsApp integration

4. Other APIs

   • Notification APIs
   • Reporting APIs
   • Integration APIs

Integration Points

1. ERPNext Integration

The CRM can be integrated with ERPNext for seamless customer data flow:

• Leads can be converted to ERPNext Customers
• Quotations can be linked to ERPNext Quotations
• Organizations can be linked to ERPNext Companies or Customers

Configuration is managed via the ERPNext CRM Settings DocType.

2. WhatsApp Integration

Provides WhatsApp messaging capabilities through Twilio:

• Send and receive WhatsApp messages
• Track message status
• Attach WhatsApp messages to leads/deals

Configuration is managed via the Twilio Settings DocType.

Customization

1. Fields Layout

The CRM provides flexible layout customization through the CRM Fields Layout DocType:

• Quick Entry forms can be customized
• Side panel layouts can be customized
• Field visibility and arrangement can be controlled

2. View Settings

List views, Kanban views, and other views can be customized via the CRM View Settings DocType:

• Column configuration
• Filtering options
• Sorting options
• Grouping options

3. Custom Scripts

Custom client-side scripts can be added via the CRM Form Script DocType.

Installation and Setup

Prerequisites

• Frappe Framework
• Node.js and Yarn
• Python 3.6+

Installation Steps

1. Install Frappe Bench
2. Create a new site
3. Install the CRM app:

   bench get-app crm https://github.com/frappe/crm
   bench --site [site-name] install-app crm
   

4. Run migrations:

   bench --site [site-name] migrate
   

Development Guide

Backend Development

1. Creating new DocTypes

   • Use the Frappe DocType builder
   • Add controller methods in Python

2. API Development

   • Add new methods to existing API modules or create new ones
   • Use @frappe.whitelist() decorator for exposed methods

3. Hooks

   • Use Frappe hooks in hooks.py to integrate with the framework
   • Common hooks: doc_events, scheduler_events, override_doctype_class

Frontend Development

1. Creating new pages

   • Add a new .vue file in the frontend/src/pages directory
   • Register the route in the router

2. Creating components

   • Add a new .vue file in the appropriate subdirectory of frontend/src/components
   • Follow the component organization pattern

3. Building and running

   cd frontend
   yarn install
   yarn dev
   

Performance Considerations

1. Backend Optimization

   • Use appropriate indexes for frequently queried fields
   • Cache frequently accessed data
   • Use batch processing for bulk operations

2. Frontend Optimization

   • Lazy loading of components
   • Pagination of large datasets
   • Optimized API calls

Security Considerations

1. Authentication

   • All API endpoints require authentication
   • Role-based access control

2. Data Protection

   • Sensitive data encrypted in the database
   • Audit logs for critical actions

3. API Security

   • CSRF protection
   • Rate limiting

Troubleshooting

Common Issues

1. Installation Issues

   • Check Frappe bench logs
   • Verify dependencies

2. Frontend Issues

   • Check browser console errors
   • Verify API responses

3. Integration Issues

   • Verify credentials for third-party services
   • Check connection settings

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

License

The Frappe CRM is licensed under the GNU Affero General Public License v3.0.