# 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: ```python # 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**: ```json { "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).