openforce/docs/OBJECT_MANAGER_SPEC.md
Bumble d73b435ec6
Some checks failed
Build, Test, and Deploy / build-and-deploy (push) Failing after 30s
docs: add Salesforce Object Manager benchmark specification and introspection roadmap
2026-09-27 04:06:36 +00:00

16 KiB

OpenForce Object Manager Architecture & Specification

1. Executive Summary & Objective

In Salesforce, the Object Manager (Setup -> Object Manager) serves as the administrative cockpit for managing the data dictionary, data relationships, and presentation layers across the CRM. Users do not merely see custom objects; they inspect, configure, and customize both Standard Built-In Objects (Account, Contact, Lead, Opportunity, Activity, Campaign) and Dynamic Custom Objects (__c).

Within an object's detail view, the Fields & Relationships section provides a unified catalog of every attribute that can exist on a record:

  • Standard Fields (e.g., first_name, amount, close_date, expected_revenue, billing_street) created by the core system engine.
  • Custom Fields (suffixed with __c, e.g., arr__c, sla_expiration_date__c, tier__c) provisioned dynamically by CRM administrators.

This specification details the research benchmarks, backend introspection architecture, API contracts, Vue 3 Lightning UX implementation, and sprint rollout plan to achieve full Salesforce Object Manager parity in OpenForce.


2. Salesforce Object Manager Benchmark Analysis

2.1 The Two-Tier Navigation Model

In Salesforce Setup, the Object Manager implements a strict hierarchy:

  1. Object Catalog (Level 1):
    • Displays all registered objects in a searchable, filterable grid.
    • Columns: Label (e.g., "Account"), API Name (e.g., "Account" vs "Invoice__c"), Type (Standard Object vs Custom Object), Description, Last Modified.
    • Actions: Filter by Object Type (All / Standard / Custom), Global Search, and "Create Custom Object".
  2. Object Detail & Subsystem Sidebar (Level 2):
    • Left Navigation Menu:
      • Details: Label, Plural Label, API Name, Record Count, Sharing Model, Deployment Status.
      • Fields & Relationships: The central schema view showing every standard and custom field.
      • Page Layouts: Drag-and-drop assignment of fields to visual sections.
      • Validation Rules: Formula-based validations before commit.
      • Triggers / Flows: Associated automation routines.

2.2 Fields & Relationships Grid Specification

The Fields & Relationships table in Salesforce has strict visual and behavioral conventions:

Column Header Description Example Standard Field Example Custom Field
Field Label Human-readable presentation label Expected Revenue ARR Tier
Field Name (API) Exact programmatic identifier expected_revenue arr_tier__c
Data Type Specific CRM type descriptor Currency(18, 2) Picklist
Type Pill / Badge Clear visual category indicator Standard (slate badge) Custom (indigo badge)
Controlling / Lookup Referenced entity if relational - Account (Lookup)
Indexed Database query acceleration indicator Yes (Primary / Foreign key) Indexed (JSONB GIN)
Required Nullability / constraint enforcement False True
Actions Permitted mutations Read-Only (standard fields cannot be dropped or altered in core type) Edit, Delete dropdown

2.3 Field Data Type Taxonomy Mapping

To deliver authentic Salesforce parity while staying native to Django and PostgreSQL:

OpenForce / SF Type Django Internal Field Type DB Representation Validation / Semantics
Text CharField, SlugField varchar(n) / jsonb string Length limit, trimmed string
Text Area (Long) TextField text / jsonb string Multiline string
Number IntegerField, PositiveIntegerField int4, int8 Signed integer range
Currency DecimalField numeric(max_digits, decimal_places) Formatted currency with precision
Percent DecimalField, IntegerField numeric / int4 0-100 percentage display
Date DateField date (YYYY-MM-DD) Date picker parsing
Date/Time DateTimeField timestamptz ISO 8601 UTC timestamp
Checkbox BooleanField boolean True / False toggle
Picklist CharField(choices=...) varchar with choice enum Defined enumeration values
Lookup Relationship ForeignKey bigint REFERENCES or UUID Relational pointer to target object
Generic Lookup GenericForeignKey content_type_id + object_id Polymorphic relationship (e.g. Activity parent)
Autonumber / ID BigAutoField, UUIDField int8 serial / uuid System immutable identifier

3. Backend Introspection Architecture

3.1 Design Principles

  1. Zero Duplication: Never manually hand-code static field dictionaries for standard models. Standard schema must be dynamically introspected directly from Django's Model._meta.get_fields(). Any model migration or field update automatically reflects in the Object Manager.
  2. Unified Representation: Standard Django ORM fields and dynamic CustomFieldDefinition records must resolve into a single uniform DTO (Data Transfer Object) contract consumed by the frontend.
  3. Security & Information Hiding: Sensitive system attributes (password, auth tokens, session markers) must be strictly omitted. Only approved business CRM models are inspectable.
  4. Tenant Isolation: Model introspection reports canonical schema metadata, while custom field definitions (CustomFieldDefinition) respect tenant isolation scopes.

3.2 Target Models for Standard Introspection

The following standard models in crm_core and outreach are exposed to the Object Manager:

  • Account (crm_core.models.Account)
  • Contact (crm_core.models.Contact)
  • Lead (crm_core.models.Lead)
  • Opportunity (crm_core.models.Opportunity)
  • Activity (crm_core.models.Activity)
  • Campaign (outreach.models.Campaign)

3.3 Dynamic Model Introspection Service

A dedicated service crm_core/introspection.py handles parsing model metadata:

# crm_core/introspection.py
from django.apps import apps
from django.db import models
from custom_objects.models import CustomFieldDefinition

STANDARD_OBJECT_REGISTRY = {
    "Account": ("crm_core", "Account"),
    "Contact": ("crm_core", "Contact"),
    "Lead": ("crm_core", "Lead"),
    "Opportunity": ("crm_core", "Opportunity"),
    "Activity": ("crm_core", "Activity"),
    "Campaign": ("outreach", "Campaign"),
}

EXCLUDED_FIELDS = {
    "custom_fields",  # JSONB container itself is not displayed as a business field
    "password",
    "is_superuser",
    "is_staff",
}

DJANGO_TYPE_MAP = {
    "CharField": "Text",
    "TextField": "Text Area (Long)",
    "IntegerField": "Number",
    "PositiveIntegerField": "Number",
    "BigAutoField": "AutoNumber",
    "DecimalField": "Currency",
    "BooleanField": "Checkbox",
    "DateField": "Date",
    "DateTimeField": "Date/Time",
    "ForeignKey": "Lookup",
    "GenericForeignKey": "Generic Lookup",
    "EmailField": "Email",
    "URLField": "URL",
}

def map_field_type(field):
    if getattr(field, "choices", None):
        return "Picklist"
    internal_type = field.get_internal_type() if hasattr(field, "get_internal_type") else type(field).__name__
    return DJANGO_TYPE_MAP.get(internal_type, internal_type)

def introspect_standard_fields(model_name: str):
    if model_name not in STANDARD_OBJECT_REGISTRY:
        raise ValueError(f"Unknown standard object: {model_name}")
    
    app_label, cls_name = STANDARD_OBJECT_REGISTRY[model_name]
    model = apps.get_model(app_label, cls_name)
    
    fields = []
    for field in model._meta.get_fields():
        # Exclude reverse relations and internal containers
        if field.auto_created and not field.concrete:
            continue
        if field.name in EXCLUDED_FIELDS:
            continue
            
        data_type = map_field_type(field)
        choices = [c[0] for c in field.choices] if getattr(field, "choices", None) else []
        related_to = None
        if field.is_relation and getattr(field, "related_model", None):
            related_to = field.related_model.__name__
            
        fields.append({
            "name": field.name,
            "label": str(getattr(field, "verbose_name", field.name)).title(),
            "data_type": data_type,
            "is_custom": False,
            "is_required": not getattr(field, "blank", True) and not getattr(field, "null", True),
            "is_unique": getattr(field, "unique", False),
            "is_indexed": getattr(field, "db_index", False) or getattr(field, "primary_key", False) or field.is_relation,
            "help_text": str(getattr(field, "help_text", "")),
            "choices": choices,
            "related_to": related_to,
            "max_length": getattr(field, "max_length", None),
            "editable": field.name not in ["id", "created_at", "updated_at"],
        })
    return fields

3.4 REST API Endpoint Specification

We expose standard introspection alongside custom fields through clean RESTful endpoints:

Endpoint 1: Standard Object Schema Introspection

GET /api/schema/objects/{entity_name}/fields/

  • Authentication: Session / Token (Requires authenticated user)
  • Parameters: entity_name (e.g. Account, Contact, Lead, Opportunity, Activity)
  • Response:
{
  "entity_name": "Opportunity",
  "label": "Opportunity",
  "is_custom": false,
  "standard_fields": [
    {
      "name": "id",
      "label": "ID",
      "data_type": "AutoNumber",
      "is_custom": false,
      "is_required": false,
      "is_unique": true,
      "is_indexed": true,
      "choices": [],
      "related_to": null,
      "editable": false
    },
    {
      "name": "name",
      "label": "Name",
      "data_type": "Text",
      "is_custom": false,
      "is_required": true,
      "is_unique": false,
      "is_indexed": false,
      "choices": [],
      "related_to": null,
      "editable": true
    },
    {
      "name": "amount",
      "label": "Amount",
      "data_type": "Currency",
      "is_custom": false,
      "is_required": false,
      "is_unique": false,
      "is_indexed": false,
      "choices": [],
      "related_to": null,
      "editable": true
    },
    {
      "name": "expected_revenue",
      "label": "Expected Revenue",
      "data_type": "Currency",
      "is_custom": false,
      "is_required": false,
      "is_unique": false,
      "is_indexed": false,
      "choices": [],
      "related_to": null,
      "editable": true
    },
    {
      "name": "stage",
      "label": "Stage",
      "data_type": "Picklist",
      "is_custom": false,
      "is_required": true,
      "is_unique": false,
      "is_indexed": false,
      "choices": [
        "Prospecting",
        "Qualification",
        "Needs Analysis",
        "Value Proposition",
        "Id. Decision Makers",
        "Decision Makers",
        "Perception Analysis",
        "Proposal/Price Quote",
        "Negotiation/Review",
        "Closed Won",
        "Closed Lost"
      ],
      "related_to": null,
      "editable": true
    },
    {
      "name": "account",
      "label": "Account",
      "data_type": "Lookup",
      "is_custom": false,
      "is_required": true,
      "is_unique": false,
      "is_indexed": true,
      "choices": [],
      "related_to": "Account",
      "editable": true
    }
  ]
}

Endpoint 2: Unified Fields Retrieval for Object Manager

GET /api/custom-fields/?entity_name={entity_name} or unified /api/schema/objects/{entity_name}/all-fields/

  • Merges introspected standard fields with stored CustomFieldDefinition records.
  • Custom field attributes include: id, name (e.g. arr__c), label, field_type, is_custom: true, required, choices, related_to.
  • Resulting unified list is sorted deterministically: Standard fields first, then Custom fields alphabetically, or sortable by any column in the UI.

4. Frontend UI/UX Specification (CustomObjectsView.vue)

4.1 Master-Detail Layout Structure

The Object Manager in frontend/src/views/CustomObjectsView.vue features a dual-pane Lightning interface:

  1. Left Sidebar (Object Selector):
    • Search input filter for quickly locating objects.
    • Segmented section for Standard Objects (Account, Contact, Lead, Opportunity, Activity, Campaign).
    • Segmented section for Custom Objects (*__c).
    • Pill counters showing count of custom fields attached to each object.
    • Button to "Create Custom Object".
  2. Main Detail Pane:
    • Header Card:
      • Object Icon (standard entity icons: Accounts 🏢, Contacts 👤, Leads 🎯, Opportunities 💼, Activities 📅, Custom 📦).
      • Object Label & API Name badge (Account vs Invoice__c).
      • Metadata summary: Type badge (Standard Object vs Custom Object), Description, Total Fields Count.
    • Tabs:
      • Fields & Relationships (Default active tab).
      • Object Details (Record counts, storage, settings).
      • Flows & Triggers (Automations associated with this object).

4.2 Unified Fields Table Features

  • Table Columns:
    1. Field Label: Bold title (e.g. Expected Revenue).
    2. API Name: Monospace font tag (expected_revenue or deal_score__c).
    3. Data Type: Formatted type badge (Text(255), Currency, Picklist, Lookup(Account)).
    4. Origin / Badge:
      • Standard: Slate/gray badge Standard.
      • Custom: Blue/indigo badge Custom.
    5. Required: Checkmark ✓ or dash -.
    6. Indexed: Indicator if field is a PK, FK, or JSONB GIN indexed.
    7. Actions:
      • Standard Fields: Lock icon or "Standard Field (System Managed)".
      • Custom Fields: Action buttons for Edit and Delete with confirmation modal.
  • Search & Filter Controls:
    • Quick search bar: instantly filters fields across label, API name, or data type.
    • Filter pills: All Fields, Standard Only, Custom Only.
  • "New Custom Field" Modal:
    • Accessible on both standard objects and custom objects.
    • Generates valid __c API names with preview.
    • Field type selector: Text, Number, Currency, Date, DateTime, Boolean, Picklist.

5. Sprint Implementation Plan

Phase Milestone Owner Deliverables Status
Sprint 4.4A Schema Introspection Engine Bumble & Comb • Create crm_core/introspection.py
• Map all 6 core models to Salesforce types
• Expose GET /api/schema/objects/{entity}/fields/
• Backend unit tests in tests/test_introspection.py
Ready for Dev
Sprint 4.4B Store & State Integration Goose • Update frontend/src/stores/crm.js
• Add fetchObjectSchema(entityName)
• Merge standard & custom fields in pinia state
Pending 4.4A
Sprint 4.4C Unified Fields UI in Object Manager Goose • Refactor CustomObjectsView.vue
• Implement Salesforce-style fields table
• Add Type Pills, Search & Filters, and Read-Only locks
Pending 4.4B
Sprint 4.4D Regression Testing & Deployment Goose & Comb • Frontend Vitest / Cypress tests
• Validate crm.ch4t.buzz live deployment
• CI/CD pipeline verification
Final Signoff

6. Technical Safeguards & Edge Cases

  1. Foreign Key Reverse Lookups: Reverse relations (e.g. contact_set, activity_set) must be excluded from the basic fields list to avoid cluttering the attribute editor; they belong in a dedicated "Related Lists" tab.
  2. GenericForeignKeys: The parent field in Activity uses content_type and object_id. The introspection engine gracefully maps this as Generic Lookup pointing to multiple target entities.
  3. Immutability of Standard Fields: Standard fields must be strictly protected from deletion or arbitrary rename requests. The UI will disable edit/delete actions, and backend mutation APIs will reject any field payload lacking the __c custom field convention.
  4. Field Name Collisions: Ensure the custom field creation validator rejects custom field names that collide with existing standard fields (e.g. preventing a custom field named name__c on Account if it violates ambiguity rules).