Frappe Enterprise Patterns

Architectural patterns for building production-grade enterprise applications.

When to use

• Building CRM, Helpdesk, HRMS, or similar multi-entity systems

• Designing SLA-driven workflows

• Implementing assignment and queue management

• Building audit trails and activity logs

• Integrating with external systems (email, telephony, CRM)

Inputs required

• System type (CRM/Helpdesk/custom)

• Core entities and relationships

• SLA requirements

• Workflow states and transitions

• Integration points

Procedure

0. Design data model

Start with clear, normalized DocTypes:

Ticket (parent) ├── customer (Link: Customer) ├── assigned_to (Link: User) ├── status (Select: Open, In Progress, Resolved, Closed) ├── priority (Link: Priority) ├── sla (Link: SLA) ├── activities (Table: Ticket Activity) └── response_by, resolution_by (Datetime)

Key patterns:

• Use Link fields for relationships

• Use child tables for activities, timelines, line items

• Use Dynamic Link when target DocType varies

1. Implement state machine

Option A: Workflow DocType

• Create Workflow with states and role-based transitions

• Link to your DocType

Option B: docstatus for submission flow

docstatus Meaning

0 Draft

1 Submitted

2 Cancelled

Option C: Custom status field with validation

def validate(self): allowed = self.get_allowed_transitions() if self.status not in allowed: frappe.throw(f"Cannot transition to {self.status}")

2. Set up permissions

Row-level filtering:

• Use User Permissions to restrict by entity

• Combine with Role Permissions

Always re-check in RPC methods:

@frappe.whitelist() def update_ticket(name, status): doc = frappe.get_doc("Ticket", name) if not frappe.has_permission("Ticket", "write", doc): frappe.throw("Not permitted", frappe.PermissionError) doc.status = status doc.save()

3. Build activity trail

Track changes using Activity Log or custom child table:

def on_update(self): if self.has_value_changed("status"): self.append("activities", { "action": "Status Change", "old_value": self._doc_before_save.status, "new_value": self.status, "timestamp": frappe.utils.now() })

4. Implement SLA

SLA DocType:

SLA ├── entity_type (Link: DocType) ├── response_time (Duration) ├── resolution_time (Duration) └── escalation_rules (Table: Escalation Rule)

Apply SLA on creation:

def after_insert(self): sla = get_applicable_sla(self) if sla: self.response_by = add_to_date(self.creation, hours=sla.response_time) self.resolution_by = add_to_date(self.creation, hours=sla.resolution_time) self.db_update()

Monitor breaches (scheduled job):

def check_sla_breaches(): tickets = frappe.get_all("Ticket", filters={"status": ["not in", ["Resolved", "Closed"]]}, fields=["name", "resolution_by"] ) for t in tickets: if frappe.utils.now_datetime() > t.resolution_by: mark_sla_breached(t.name)

5. Assignment and queues

Round-robin assignment:

def assign_next_agent(queue): agents = frappe.get_all("Queue Member", filters={"queue": queue, "available": 1}, fields=["user", "current_load"], order_by="current_load asc" ) if agents: return agents[0].user return None

Assignment Rules DocType for automatic assignment.

6. Notifications and escalations

Configure Notification DocType for:

• SLA approaching breach

• Assignment changes

• Status transitions

• Customer replies

Escalation chain:

Level 1 (0h): Notify assigned agent Level 2 (4h): Notify team lead Level 3 (8h): Notify manager Level 4 (24h): Notify department head

7. External integrations

Centralize in integrations/ module:

my_app/integrations/email_connector.py

def sync_emails(): # Fetch from Email Account # Create Communications # Link to Tickets

Use background jobs for sync:

frappe.enqueue( "my_app.integrations.email_connector.sync_emails", queue="long", timeout=600 )

Verification

• Workflow transitions work for all roles

• Permissions enforced at API level

• Activity log captures all changes

• SLA calculation correct

• Notifications fire appropriately

• Integration sync runs without errors

Failure modes / debugging

• Permission bypass: Check RPC methods have explicit permission checks

• SLA not applying: Verify scheduled job is running

• Activities not logging: Check has_value_changed usage

• Notifications not sending: Check Notification rules and email queue

Escalation

• For complex permission patterns, see references/advanced-permissions.md

• For queue optimization, see references/queue-patterns.md

• For UI/UX patterns → frappe-ui-patterns

References

• references/workflow-patterns.md - State machine design

• references/sla-implementation.md - SLA details

• references/integration-patterns.md - External systems

Guardrails

• Follow CRM/Helpdesk UI patterns: For CRUD apps, follow frappe-ui-patterns skill which documents app shell, navigation, list views, and form patterns from official Frappe apps. This includes sidebar layouts, quick filters, Kanban views, and detail panels.

• Use Frappe UI for frontends: All custom enterprise frontends must use Frappe UI (Vue 3 + TailwindCSS) — never vanilla JS or jQuery

• Design workflows carefully: Map all states and transitions before implementation; consider rollback paths

• Handle edge cases: Plan for cancelled, on-hold, and exception states in workflows

• Test performance early: Run load tests for high-volume DocTypes and complex queries

• Use background jobs for heavy operations: Never block web requests with long-running tasks

• Log critical operations: Use frappe.log_error() and activity logs for auditability

Common Mistakes

Mistake Why It Fails Fix

Over-complex workflows Hard to maintain, user confusion Keep workflows linear when possible; split complex flows

Missing error handling in integrations Silent failures, data inconsistency Wrap external calls in try/except; log errors; retry logic

Race conditions in document updates Data corruption Use frappe.db.get_value(..., for_update=True) for locks

SLA without timezone handling Wrong calculations for global users Store and compare in UTC; use frappe.utils.convert_utc_to_timezone

Not using queues for bulk operations Timeouts, memory issues Use frappe.enqueue() for operations on many records

Hardcoded role names Breaks on role changes Use constants or settings for role names

Custom UI patterns Inconsistent UX, user confusion Study and follow CRM/Helpdesk app shells

Using vanilla JS/jQuery for frontend Maintenance burden, ecosystem mismatch Always use Frappe UI with Vue 3