Architecture

[pgajek2]

Assumptions

No Custom Metadata by default

Developers shouldn’t be forced to create custom metadata records to make the framework work.
All handlers should be executed based on one of the following approaches:

A) Interface-based execution

The framework queries Apex classes that implement a handler interface and executes them automatically.

Pros

• Simplest solution
• No additional setup required - just implement the interface

Cons

• If developers work in a shared developer sandbox and someone deploys a handler that is not ready, it will be executed and may cause errors

Mitigation

• Introduce a marker interface, e.g. Trigger.Bypass
• If a handler implements this interface, it will not be executed
  (Open for discussion)

B) Orchestrator-based execution

Introduce an orchestrator that maintains a list of handlers to be executed.

Characteristics

• Requires two steps:
  1. Create the handler
  2. Register it in the orchestrator
• The orchestrator may cause merge conflicts, but this should be manageable

Role of Custom Metadata

Custom metadata should be used only to override default handler behavior, not to define it.

Examples:

• Bypassing a handler
  A metadata record can be created with a bypass flag enabled.
• Conditional execution
  Handlers run for all users by default, but metadata can override this and restrict execution to specific profiles or permission sets.

Additional override options can be introduced as needed.

Populators

Over 90% of actions performed in before insert or before update contexts are related to field population. We should introduce a sub-framework as part of the library called Populators. Populators should simplify development and reduce the need for complex if-else logic.

A populator should define two methods: isQualified and populate.

• isQualified determines whether the population logic should be executed.
• populate performs the actual field population.

This approach keeps the code minimal, readable, and easy to reason about.

public with sharing class MyFieldPopulator implements Trigger.Populator.BeforeInsert {
    public Boolean isQualified(Record record) {
        return record.isNotNull(MyObject__c.MyField__c);
    }

    public void populate(SObject record) { // or (MyObject__c record) when using a typed interface
        record.Field__c = 'Something';
    }
}

The populator framework should be executed in a single-record context, without any explicit loops.
All DML and SOQL operations should be blocked when executed from the isQualified or populate methods.

If additional data is required—such as related or global data—it should be provided through a context object, which will be described in a separate section.

Handlers

Similarly to Populators, handlers should be executed in a single-record context to avoid repeating for loops across multiple handlers.

An interface should be introduced that enforces the implementation of two methods: isQualified and execute.

• isQualified determines whether the execution logic should be applied to a given record.
• execute performs the actual action — DML operations are allowed here.

The execute method should be invoked only if at least one record qualifies.

public with sharing class MyHandler implements Trigger.AfterInsert {
    public Boolean isQualified(Record record) {
        return record.isNotNull(MyObject__c.MyField__c);
    }

    public void execute(List<SObject> records) { 
        // or (List<MyObject__c> records) when using a typed interface
        // action here
    }
}

There should also be a way to enrich SObject records with related data.
A new method, enrichRelated, can be introduced to define the required relationships using a mapping structure:

public Map<SObjectField, List<SObjectField>> enrichRelated() {
    return new Map<SObjectField, List<SObjectField>>{
        Contact.AccountId => new List<SObjectField>{
            Account.Name,
            Account.RecordTypeId
        }
        // etc.
    };
}

Instead of a Map, a composite pattern (something similar to SOQL.FilterGroup) could be used to support more deeply nested relationships, such as: Account.CreatedBy.Manager.Email`.

All enrichRelated definitions from handlers should be aggregated, and the minimum number of SOQL queries should be executed without duplication.
SOQL Lib can be leveraged here to dynamically build optimized queries.

Records passed into the isQualified and execute methods should have related data accessible via dot notation, for example: record.Account.CreatedBy.Manager.Email.

Error handling

The framework should provide top-level error handling. It should be easy to override this behavior with custom logging.

Developers should not be required to add their own try-catch blocks to every populator or handler.

An interface such as Trigger.Logger can be introduced.

• When option A) Interface-based execution is used, the logger should be automatically discovered, queried, and cached.
• When option B) Orchestrator-based execution is used, the logger should be explicitly defined in the orchestrator.

public with sharing class TriggerLogger implements Trigger.Logger {
    public void log(Exception e) {
        // logging logic
    }

    public void finalize() {
        // finalization logic (e.g. flush logs)
    }
}

Bypass

The static flag does not work correctly when there are more than 200 records (trigger chunks). A different approach should be defined to make bypassing work properly, for example using a hashCode-based mechanism (TBD).

Finalizer

A finalizer should be defined. The finalizer can be implemented as a class with a dedicated interface, or the logic can be added to the orchestrator to specify a finalizer (similar to the Logger concept).

The finalizer can be used to commit all DML operations when a Unit of Work pattern is used.

[pgajek2]

• Validators - to make custom validations when validation rules are not enough.