AMSDAL CRM¶

amsdal_crm is an MVP CRM plugin for the AMSDAL Framework. It provides a full-featured CRM system with entities, deals and pipeline management, activity tracking, custom fields, workflow automation, and file attachments.

Installation¶

pip install amsdal_crm

Plugin Registration¶

Register the plugin in your AMSDAL configuration:

AMSDAL_CONTRIBS = [
    # ... other plugins
    'amsdal_crm.app.CRMAppConfig',
]

Features¶

Entities — contacts, organizations, and accounts with relationships, identifiers, contact points, and addresses
Deals & Pipelines — sales opportunities progressing through configurable pipeline stages with automatic status tracking
Activities — tasks, events, emails, notes, and calls linked to entities or deals
Custom Fields — user-defined fields with type validation on any CRM model
Workflow Rules — automated actions triggered by entity create/update/delete events
Attachments — file attachments linked to entities, deals, or activities

Architecture¶

Entity ──── EntityRelationship ──── Entity
  │
  ├── EntityIdentifier
  ├── EntityContactPoint
  ├── EntityAddress
  │
  └── Deal ──── Stage ──── Pipeline
        │
        └── Activity (Task, Event, Email, Note, Call)
              │
              └── Attachment

Activities and Attachments use a polymorphic relationship pattern (related_to_type + related_to_id) to link to different record types.

Configuration¶

CRM settings are configured via environment variables with the AMSDAL_CRM_ prefix:

Environment Variable	Type	Default	Description
`AMSDAL_CRM_DEFAULT_ACTIVITY_TIMELINE_LIMIT`	`int`	`100`	Max activities returned by timeline queries
`AMSDAL_CRM_MAX_CUSTOM_FIELDS_PER_ENTITY`	`int`	`50`	Max custom field definitions per entity type
`AMSDAL_CRM_MAX_WORKFLOW_RULES_PER_ENTITY`	`int`	`100`	Max workflow rules per entity type
`AMSDAL_CRM_DEFAULT_CURRENCY`	`str`	`USD`	Default currency for deals

These settings are defined in CRMSettings (a Pydantic BaseSettings subclass) and are available as a singleton via crm_settings:

from amsdal_crm.settings import crm_settings

print(crm_settings.DEFAULT_CURRENCY)  # 'USD'

Permissions¶

CRM uses an owner-based permission model:

Owner access — users who are assigned_to an entity, deal, or activity have full access to that record
Super admin access — users with the super_admin scope have access to all records
Unauthenticated users have no access

Each of Entity, Deal, and Activity implements has_object_permission() with this logic.

Error Handling¶

All CRM exceptions inherit from CRMError:

Exception	Description
`CRMError`	Base exception for all CRM errors
`CustomFieldValidationError`	Custom field validation failure
`WorkflowExecutionError`	Workflow rule execution failure
`InvalidStageTransitionError`	Invalid deal stage transition
`PermissionDeniedError`	Permission check failure

from amsdal_crm.errors import CRMError, CustomFieldValidationError