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:
- 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 ObjectvsCustom Object),Description,Last Modified. - Actions: Filter by Object Type (All / Standard / Custom), Global Search, and "Create Custom Object".
- 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.
- Left Navigation Menu:
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
- 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. - Unified Representation: Standard Django ORM fields and dynamic
CustomFieldDefinitionrecords must resolve into a single uniform DTO (Data Transfer Object) contract consumed by the frontend. - Security & Information Hiding: Sensitive system attributes (
password, auth tokens, session markers) must be strictly omitted. Only approved business CRM models are inspectable. - 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
CustomFieldDefinitionrecords. - 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:
- 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".
- Main Detail Pane:
- Header Card:
- Object Icon (standard entity icons: Accounts 🏢, Contacts 👤, Leads 🎯, Opportunities 💼, Activities 📅, Custom 📦).
- Object Label & API Name badge (
AccountvsInvoice__c). - Metadata summary: Type badge (
Standard ObjectvsCustom Object), Description, Total Fields Count.
- Tabs:
- Fields & Relationships (Default active tab).
- Object Details (Record counts, storage, settings).
- Flows & Triggers (Automations associated with this object).
- Header Card:
4.2 Unified Fields Table Features
- Table Columns:
Field Label: Bold title (e.g. Expected Revenue).API Name: Monospace font tag (expected_revenueordeal_score__c).Data Type: Formatted type badge (Text(255),Currency,Picklist,Lookup(Account)).Origin / Badge:- Standard: Slate/gray badge
Standard. - Custom: Blue/indigo badge
Custom.
- Standard: Slate/gray badge
Required: Checkmark✓or dash-.Indexed: Indicator if field is a PK, FK, or JSONB GIN indexed.Actions:- Standard Fields: Lock icon or "Standard Field (System Managed)".
- Custom Fields: Action buttons for
EditandDeletewith 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
__cAPI 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
- 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. - GenericForeignKeys: The
parentfield inActivityusescontent_typeandobject_id. The introspection engine gracefully maps this asGeneric Lookuppointing to multiple target entities. - 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
__ccustom field convention. - 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__con Account if it violates ambiguity rules).