# 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).