# marsson/eventqueue architecture

> Architecture diagram of the GitHub repository marsson/eventqueue, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/marsson/eventqueue
- Repository: https://github.com/marsson/eventqueue

## Overview

##### Project type and purpose
- This is a Salesforce-centric automation framework implemented as an SFDX package (“Execution Queue”).
- It uses the Command design pattern in Apex to orchestrate critical business processes (inbound/outbound events, messaging) with retry, error handling, and extension capabilities.

##### File structure
- Top-level config files: sfdx-project.json, package.json, jest.config.js, manifest/package.xml.
- force-app/main/default:
- classes/: Apex command interfaces, abstract implementations, concrete commands, tests
- triggers/: two Apex triggers (EventConsumer.trigger, queueProcessor.trigger)
- objects/: custom objects Queue__c and platform event queueEvent__e definitions, plus custom metadata type Event_Configuration__mdt
- customMetadata/: metadata records mapping event types to Apex command classes
- flexipages, layouts, permissionsets, tabs: UI/perms for admin and running users
- aura, lwc: if any Lightning components are present (empty in this tree)
- config/: scratch org definition files for local development
- manifest/: package.xml for deployment

##### Extract insights from README
- Single custom object (“Queue__c”) drives execution via Apex triggers or scheduled job (every 5 minutes).
- Command pattern: ICommand interface, AbstractCommand base classes, CommandFactory to instantiate concrete commands.
- Custom metadata (Event_Configuration__mdt) to map event types to implementing Apex classes.
- Retry mechanism implemented via scheduled apex (JobPendingEvents, JobRetryEventProcessor, JobOldQueuedEvents).
- Optional performance boost through platform events (queueEvent__e).

a. Main components
- Salesforce Platform
- Queue__c Custom Object (the “queue table”)
- Apex Triggers:
– EventConsumer.trigger (platform event consumer)
– queueProcessor.trigger (on insert/update of Queue__c)
- Scheduled Apex Jobs:
– JobPendingEvents, JobRetryEventProcessor, JobOldQueuedEvents
- Command Framework:
– ICommand interface
– AbstractCommand, AbstractOutboundCommand, AbstractOutboundInboundCommand
– Concrete Commands (e.g., EventUnitTestCommand, MockThrowsExceptionCommand)
– CommandFactory
- Custom Metadata Type (Event_Configuration__mdt)
- Platform Event queueEvent__e (optional high-volume channel)
- External Systems (email/SMS providers, REST endpoints)
- UI/Configuration: Custom metadata setup UI, Lightning pages, permission sets

b. Relationships & interactions
1. User/Integration creates or updates a Queue__c record (“Queued” status).
2. queueProcessor.trigger fires → enqueues execution by instantiating correct ICommand via CommandFactory (using custom metadata mapping).
3. Concrete Command executes business logic (e.g., callout via RestProxy, create records), updates Queue__c status and logs errors.
4. On failure or retry count not exceeded, scheduled jobs (JobRetryEventProcessor) query Queue__c for failed or pending records and re-invoke command logic.
5. Optionally, platform event queueEvent__e is published/consumed by EventConsumer.trigger for async processing.
6. Custom metadata entries drive which command class to execute for each event type.

c. Architectural patterns & design principles
- Command pattern for pluggable business processes
- Trigger+Scheduling hybrid for immediate and batched retry execution
- Custom metadata for configuration-driven wiring
- Clear separation: Data (Queue__c), Orchestration (triggers/jobs), Execution (commands), Configuration (metadata)

d. Key technologies
- Salesforce Apex (classes, triggers, schedulable apex)
- Custom Objects & Platform Events
- SFDX and scratch org configs
- Lightning (LWC/Aura) for configuration UI
- Jest and Apex tests for code coverage

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% UI / Administrative Configuration
    subgraph "UI / Admin Config"
        direction TB
        Flexipages["Flexipages"]:::config
        Layouts["Layouts"]:::config
        Permissions["Permission Sets"]:::config
        Tabs["Tabs"]:::config
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        QueueObj["Queue__c"]:::salesforce
        PlatformEvent["queueEvent__e"]:::salesforce
    end

    %% Configuration-Driven Wiring
    subgraph "Configuration"
        direction TB
        CmdMetadataType["Event_Configuration__mdt (Type)"]:::config
        CmdMetadataRecords["Event_Configuration__mdt Records"]:::config
    end

    %% Orchestration Layer
    subgraph "Orchestration"
        direction TB
        TriggerQueue["queueProcessor.trigger"]:::apex
        TriggerEvent["EventConsumer.trigger"]:::apex
        subgraph "Scheduled Jobs"
            direction TB
            JobPending["JobPendingEvents"]:::apex
            JobRetry["JobRetryEventProcessor"]:::apex
            JobOld["JobOldQueuedEvents"]:::apex
            ScheduleHelper["ScheduleHelper"]:::apex
        end
    end

    %% Execution Layer (Command Framework)
    subgraph "Command Framework"
        direction TB
        ICommand["ICommand"]:::apex
        AbstractCmd["AbstractCommand"]:::apex
        AbstractOutbound["AbstractOutboundCommand"]:::apex
        Factory["CommandFactory"]:::apex
        subgraph "Concrete Commands"
            direction TB
            EventTestCmd["EventUnitTestCommand"]:::apex
            MockExceptionCmd["MockThrowsExeceptionCommand"]:::apex
        end
    end

    %% Integration & External Systems
    subgraph "Integration & External"
        direction TB
        RestProxy["RestProxy"]:::apex
        BaseRest["BaseRestProxy"]:::apex
        ExternalSys["External Systems"]:::external
    end

    %% Legend
    subgraph "Legend"
        direction LR
        SF["Salesforce Entities"]:::salesforce
        APEX["Apex Components"]:::apex
        EXT["External Systems"]:::external
        CFG["Configuration Items"]:::config
    end

    %% Connections
    Flexipages --> QueueObj
    Layouts --> QueueObj
    Permissions --> QueueObj
    Tabs --> QueueObj

    QueueObj -->|on insert/update| TriggerQueue
    TriggerQueue -->|uses mapping| Factory
    CmdMetadataType --> Factory
    CmdMetadataRecords --> Factory

    TriggerEvent --> Factory

    Factory -->|implements| ICommand
    ICommand --> AbstractCmd
    AbstractCmd --> AbstractOutbound
    Factory --> EventTestCmd
    Factory --> MockExceptionCmd

    EventTestCmd --> RestProxy
    MockExceptionCmd --> RestProxy
    RestProxy --> BaseRest
    BaseRest --> ExternalSys

    JobPending --> QueueObj
    JobRetry --> QueueObj
    JobOld --> QueueObj
    JobPending --> Factory
    JobRetry --> Factory
    JobOld --> Factory

    QueueObj -->|publishes| PlatformEvent
    PlatformEvent --> TriggerEvent

    %% Click Events
    click QueueObj "https://github.com/marsson/eventqueue/tree/master/force-app/main/default/objects/Queue__c"
    click PlatformEvent "https://github.com/marsson/eventqueue/tree/master/force-app/main/default/objects/queueEvent__e"
    click TriggerQueue "https://github.com/marsson/eventqueue/blob/master/force-app/main/default/triggers/queueProcessor.trigger"
    click TriggerEvent "https://github.com/marsson/eventqueue/blob/master/force-app/main/default/triggers/EventConsumer.trigger"
    click JobPending "https://github.com/marsson/eventqueue/blob/master/force-app/main/default/classes/JobPendingEvents.cls"
    click JobRetry "https://github.com/marsson/eventqueue/blob/master/force-app/main/default/classes/JobRetryEventProcessor.cls"
    click JobOld "https://github.com/marsson/eventqueue/blob/master/force-app/main/default/classes/JobOldQueuedEvents.cls"
    click ScheduleHelper "https://github.com/marsson/eventqueue/blob/master/force-app/main/default/classes/ScheduleHelper.cls"
    click ICommand "https://github.com/marsson/eventqueue/blob/master/force-app/main/default/classes/ICommand.cls"
    click AbstractCmd "https://github.com/marsson/eventqueue/blob/master/force-app/main/default/classes/AbstractCommand.cls"
    click AbstractOutbound "https://github.com/marsson/eventqueue/blob/master/force-app/main/default/classes/AbstractOutboundCommand.cls"
    click Factory "https://github.com/marsson/eventqueue/blob/master/force-app/main/default/classes/CommandFactory.cls"
    click EventTestCmd "https://github.com/marsson/eventqueue/blob/master/force-app/main/default/classes/EventUnitTestCommand.cls"
    click MockExceptionCmd "https://github.com/marsson/eventqueue/blob/master/force-app/main/default/classes/MockThrowsExeceptionCommand.cls"
    click RestProxy "https://github.com/marsson/eventqueue/blob/master/force-app/main/default/classes/RestProxy.cls"
    click BaseRest "https://github.com/marsson/eventqueue/blob/master/force-app/main/default/classes/BaseRestProxy.cls"
    click CmdMetadataType "https://github.com/marsson/eventqueue/tree/master/force-app/main/default/objects/Event_Configuration__mdt"
    click CmdMetadataRecords "https://github.com/marsson/eventqueue/blob/master/force-app/main/default/customMetadata/Event_Configuration.*.md-meta.xml"
    click Flexipages "https://github.com/marsson/eventqueue/tree/master/force-app/main/default/flexipages"
    click Layouts "https://github.com/marsson/eventqueue/blob/master/force-app/main/default/layouts/Event_Configuration__mdt-Event Configuration Layout.layout-meta.xml"
    click Permissions "https://github.com/marsson/eventqueue/blob/master/force-app/main/default/permissionsets/Event_Queue_Admin.permissionset-meta.xml"
    click Tabs "https://github.com/marsson/eventqueue/blob/master/force-app/main/default/tabs/Queue__c.tab-meta.xml"

    %% Styles
    classDef salesforce fill:#dae8fc,stroke:#6c8ebf,color:#1a1a1a
    classDef apex fill:#d5e8d4,stroke:#82b366,color:#1a1a1a
    classDef external fill:#ffe6cc,stroke:#d79b00,color:#1a1a1a
    classDef config fill:#f8cecc,stroke:#b85450,color:#1a1a1a
    class SF,salesforce legend
    class APEX,apex legend
    class EXT,external legend
    class CFG,config legend
```
