# OpenForce Standard CRM Schema Specification & Field Dictionary **Target Entities**: `Account`, `Contact`, `Lead`, `Opportunity`, and `Activity` This document defines the production field dictionary, constraint rules, indexing strategies, and lifecycle conversion dynamics for OpenForce's Phase 1 standard objects, benchmarking Salesforce standard fields, Twenty CRM, and SuiteCRM. --- ## 1. Account (Standard Object) Represents a business organization, partner, or enterprise client. ### Fields & Constraints | Field Name | Type | Constraints | Description | | :--- | :--- | :--- | :--- | | `id` | UUID | Primary Key, default `uuid.uuid4` | Global unique identifier | | `name` | String(255) | Required, indexed | Company or organization legal/trading name | | `account_type` | Enum / String(50) | Choices: `Customer`, `Prospect`, `Partner`, `Competitor`, `Vendor`, `Other` | Relationship type | | `industry` | Enum / String(100) | Choices: `Technology`, `Finance`, `Healthcare`, `Manufacturing`, `Retail`, `Services`, `Other` | Sector categorization | | `annual_revenue` | Decimal(18, 2) | Nullable, default `None` | Annual estimated or reported turnover | | `employees_count`| Integer | Nullable, min 0 | Total workforce count | | `website` | URLField | Nullable, max_length 255 | Corporate website URL | | `phone` | String(40) | Nullable | Primary corporate telephone number | | `billing_address`| JSONB | Schema: `{street, city, state, postal_code, country}` | Structured billing address | | `shipping_address`| JSONB | Schema: `{street, city, state, postal_code, country}` | Structured shipping/logistics address | | `parent_account` | ForeignKey(Account) | Nullable, `on_delete=SET_NULL`, related_name=`child_accounts` | Corporate hierarchy/subsidiary tree | | `owner` | ForeignKey(User) | Nullable, `on_delete=SET_NULL`, related_name=`accounts` | Account executive / sales rep owner | | `created_at` | DateTime | Auto now add, indexed | Creation timestamp | | `updated_at` | DateTime | Auto now, indexed | Last updated timestamp | --- ## 2. Contact (Standard Object) Represents an individual person associated with an Account. ### Fields & Constraints | Field Name | Type | Constraints | Description | | :--- | :--- | :--- | :--- | | `id` | UUID | Primary Key | Global unique identifier | | `account` | ForeignKey(Account) | Nullable, `on_delete=CASCADE`, related_name=`contacts`, indexed | Linked company/account | | `first_name` | String(100) | Required | Individual's given name | | `last_name` | String(100) | Required, indexed | Individual's family / surname | | `email` | EmailField | Indexed, nullable | Primary email address | | `phone` | String(40) | Nullable | Direct business telephone | | `mobile_phone` | String(40) | Nullable | Mobile/cellular telephone | | `title` | String(128) | Nullable | Job title / professional role (e.g. VP Engineering) | | `department` | String(128) | Nullable | Department within organization | | `is_primary` | Boolean | Default `False` | Primary contact flag for the parent Account | | `do_not_call` | Boolean | Default `False` | Compliance flag for outbound calling | | `email_opt_out` | Boolean | Default `False`, indexed | Unsubscribe flag for automated outreach campaigns | | `owner` | ForeignKey(User) | Nullable, `on_delete=SET_NULL`, related_name=`contacts` | Relationship manager | | `created_at` | DateTime | Auto now add | Creation timestamp | | `updated_at` | DateTime | Auto now | Last updated timestamp | --- ## 3. Lead (Standard Object) Represents an unqualified prospect or inbound marketing inquiry. ### Fields & Constraints | Field Name | Type | Constraints | Description | | :--- | :--- | :--- | :--- | | `id` | UUID | Primary Key | Global unique identifier | | `first_name` | String(100) | Required | Prospect given name | | `last_name` | String(100) | Required, indexed | Prospect family name | | `company` | String(255) | Required, indexed | Organization name provided by prospect | | `email` | EmailField | Indexed, nullable | Prospect email address | | `phone` | String(40) | Nullable | Phone number | | `lead_source` | Enum / String(64) | Choices: `Inbound Web`, `Referral`, `Conference`, `Cold Outreach`, `Partner`, `Other` | Acquisition origin | | `status` | Enum / String(50) | Choices: `New`, `Contacted`, `Working`, `Qualified`, `Unqualified` | Lead lifecycle status | | `lead_score` | Integer | Default 0, indexed | Heuristic engagement score (0-100) | | `is_converted` | Boolean | Default `False`, indexed | True if converted to Account/Contact/Opp | | `converted_at` | DateTime | Nullable | Conversion timestamp | | `converted_account` | ForeignKey(Account) | Nullable, `on_delete=SET_NULL` | Account generated during conversion | | `converted_contact` | ForeignKey(Contact) | Nullable, `on_delete=SET_NULL` | Contact generated during conversion | | `converted_opportunity` | ForeignKey(Opportunity) | Nullable, `on_delete=SET_NULL` | Deal created during conversion | | `owner` | ForeignKey(User) | Nullable, `on_delete=SET_NULL`, related_name=`leads` | Sales development representative | | `created_at` | DateTime | Auto now add | Creation timestamp | | `updated_at` | DateTime | Auto now | Last updated timestamp | --- ## 4. Opportunity (Standard Object) Represents a prospective deal or revenue-generating engagement in the sales pipeline. ### Fields & Constraints | Field Name | Type | Constraints | Description | | :--- | :--- | :--- | :--- | | `id` | UUID | Primary Key | Global unique identifier | | `name` | String(255) | Required, indexed | Deal name (e.g. "Acme Corp - 50 Seat License") | | `account` | ForeignKey(Account) | Required, `on_delete=CASCADE`, related_name=`opportunities` | Associated client account | | `primary_contact`| ForeignKey(Contact) | Nullable, `on_delete=SET_NULL` | Lead champion / signatory contact | | `amount` | Decimal(18, 2) | Default `0.00`, indexed | Total deal value in base currency | | `stage` | Enum / String(50) | Indexed | Pipeline stage (see Stage Dictionary below) | | `probability` | Integer | Min 0, Max 100 | Percentage probability of winning (stage-derived default) | | `expected_revenue`| Decimal(18, 2) | Computed (`amount * probability / 100`) | Weighted pipeline revenue | | `close_date` | Date | Required, indexed | Anticipated or actual transaction close date | | `lead_source` | Enum / String(64) | Nullable | Origination channel | | `deal_type` | Enum / String(50) | Choices: `New Business`, `Existing Business - Expansion`, `Renewal` | Commercial categorization | | `next_step` | String(255) | Nullable | Immediate operational action step | | `owner` | ForeignKey(User) | Nullable, `on_delete=SET_NULL`, related_name=`opportunities` | Deal lead | | `created_at` | DateTime | Auto now add | Creation timestamp | | `updated_at` | DateTime | Auto now | Last updated timestamp | ### Opportunity Stage & Probability Matrix | Stage Name | Default Probability | Forecast Category | Description | | :--- | :--- | :--- | :--- | | `Prospecting` | 10% | Pipeline | Initial contact made, interest identified | | `Qualification`| 20% | Pipeline | BANT (Budget, Authority, Need, Timeline) assessed | | `Needs Analysis`| 40% | Pipeline | Deep technical & requirements discovery | | `Proposal / Quote`| 60% | Best Case | Formal quote or proposal delivered | | `Negotiation / Review`| 80% | Commit | Legal, procurement, and terms discussion | | `Closed Won` | 100% | Closed | Executed agreement, deal won | | `Closed Lost` | 0% | Omitted | Deal abandoned or lost to competitor | --- ## 5. Unified Activity & Task Model Tracks all activities, calls, emails, and to-dos against standard and custom entities. ### Activity / Task Schema | Field Name | Type | Constraints | Description | | :--- | :--- | :--- | :--- | | `id` | UUID | Primary Key | Global unique identifier | | `subject` | String(255) | Required | Activity headline / task title | | `activity_type` | Enum / String(32) | Choices: `Task`, `Call`, `Meeting`, `Email`, `Note` | Classification of interaction | | `status` | Enum / String(32) | Choices: `Not Started`, `In Progress`, `Completed`, `Deferred` | Execution status | | `priority` | Enum / String(20) | Choices: `High`, `Normal`, `Low` | Urgency tier | | `due_date` | DateTime | Nullable, indexed | Target completion or occurrence time | | `description` | TextField | Nullable | Body notes or meeting transcript | | `content_type` | ForeignKey(ContentType) | Indexed | Generic relation to any Django model | | `object_id` | String(64) | Indexed | ID of target entity (Account, Contact, Lead, etc.) | | `content_object`| GenericForeignKey | Resolves `(content_type, object_id)` | Polymorphic target link | | `assigned_to` | ForeignKey(User) | Nullable, `on_delete=SET_NULL` | Action assignee | | `completed_at` | DateTime | Nullable | Actual completion timestamp | --- ## 6. Lead Conversion Pipeline Mechanics When a user or automated flow invokes `POST /api/leads/{id}/convert/`: 1. **Validation**: Verify `lead.is_converted == False`. 2. **Atomic Transaction (`transaction.atomic`)**: - Locate or create `Account` matching `lead.company`. - Create `Contact` with `first_name`, `last_name`, `email`, `phone`, linked to `Account`. - If requested, create `Opportunity` with `name=f"{lead.company} - New Deal"`, `stage="Prospecting"`, linked to `Account` and `Contact`. - Update `Lead`: - `is_converted = True` - `converted_at = timezone.now()` - `converted_account = account` - `converted_contact = contact` - `converted_opportunity = opportunity` - Re-link all related polymorphic `Tasks` and `Activities` from `(Lead, lead.id)` to `(Contact, contact.id)` or `(Account, account.id)`.