System Diagram

The DSLCore Orchestrator data model, mapped — 27 models (23 entity-sync + 4 message- protocol), 17 physical relationships

🔍 Open the Interactive Diagram Viewer — pan, mouse-wheel zoom, fit-to-screen, full-screen, per-module tabs, the full ERD, and a focus mode that draws one model and its neighbours at a chosen depth. This is a deliberately shallow control-plane schema: most tables are flat registry/history records keyed by business codes, so the physical foreign-key graph is small — 17 edges: 10 in the entity-sync model and 7 added by the message protocol (route decisions, acknowledgements, reconciliation). The logical flow — how events, schedules, controls and exceptions actually chain together — is richer than the FK graph, so the Overview tab and the diagrams below show that logical flow, not only the physical keys.

Architecture Overview

Six areas mirror the sidebar menu. Solid arrows are physical foreign keys; dashed arrows are the logical flow the control plane follows (matched by business code, not a stored FK). Entity sync and the message protocol share EventMessage, DeliveryAttempt and DeadLetterItem; each message is marked with its protocol.

flowchart LR
    subgraph REG["🧭 Registry & identity"]
        ApplicationInstance --> HealthCheck
        ApplicationInstance -.-> Connector
        CanonicalEntity --> EntityOwnership
        CanonicalEntity --> EntityMapping
    end

    subgraph INT["🔀 Integration"]
        EventDefinition -.-> EventMessage
        EventMessage -.-> RouteDefinition
        RouteDefinition --> FieldMapping
        RouteDefinition --> DeliveryAttempt
        EventMessage --> DeliveryAttempt
        DeliveryAttempt -.-> DeadLetterItem
    end

    subgraph MSG["✉️ Message protocol"]
        Subscription -.-> RouteDecision
        RouteDecision --> Acknowledgement
        RouteDecision --> MessageReconciliation
    end

    subgraph SCH["⏱️ Scheduling"]
        ActionDefinition -.-> JobDefinition
        JobDefinition -.-> Schedule
        Schedule -.-> JobExecution
        RetryPolicy -.-> JobDefinition
        SyncCheckpoint
    end

    subgraph GOV["🛡️ Governance"]
        ControlDefinition --> ControlExecution
        ControlDefinition -.-> GovernanceException
        GovernanceException --> ExceptionAction
    end

    subgraph ADM["📜 Admin"]
        AuditRecord
    end

    EventMessage -.-> RouteDefinition
    EventMessage --> RouteDecision
    RouteDecision --> DeliveryAttempt
    RouteDecision --> DeadLetterItem
    Schedule -.-> ControlDefinition
    ControlExecution -.-> GovernanceException
    GovernanceException -.-> AuditRecord

Registry & identity

Who is out there, how we reach them, and the shared vocabulary that lets them refer to the same business things. EntityOwnership and EntityMapping both key off CanonicalEntity; HealthCheck keys off ApplicationInstance.

erDiagram
    ApplicationInstance ||--o{ HealthCheck : "checked by"
    CanonicalEntity ||--o{ EntityOwnership : "authoritative-owner rows"
    CanonicalEntity ||--o{ EntityMapping : "local-key crosswalk"

    ApplicationInstance {
        string application_code UK
        string application_type "DSLCore/External/Legacy/Infrastructure"
        string operational_status
        string connector_code
    }
    Connector {
        string connector_code UK
        string connector_type
        string direction
        string credential_reference "secret:// reference only"
    }
    CanonicalEntity {
        string entity_code UK
        string canonical_key_field
        bool active
    }
    EntityOwnership {
        int canonical_entity_id FK
        string field_name
        string authoritative_application_code
        string ownership_type "Entity/Field"
    }
    EntityMapping {
        int canonical_entity_id FK
        string canonical_key
        string application_code
        string local_key_value
        string sync_status
    }
    HealthCheck {
        int application_instance_id FK
        int response_time_ms
        string status
    }

Integration

An EventMessage is matched to RouteDefinitions (by source app + event type); each route carries FieldMappings and produces DeliveryAttempts; exhausted deliveries become DeadLetterItems. FieldMapping, DeliveryAttempt and DeadLetterItem are the physical children.

erDiagram
    RouteDefinition ||--o{ FieldMapping : "transforms"
    EventMessage ||--o{ DeliveryAttempt : "delivered via"
    RouteDefinition ||--o{ DeliveryAttempt : "down route"
    EventMessage ||--o{ DeadLetterItem : "dead-lettered"
    RouteDefinition ||--o{ DeadLetterItem : "on route"

    EventDefinition {
        string event_type UK
        string producer_application_code
        string materiality
    }
    EventMessage {
        string event_sid UK
        string event_type
        string canonical_key
        string status
        bool duplicate
    }
    RouteDefinition {
        string route_code UK
        string trigger_type
        string source_event_type
        string target_application_code
        string operation
        string condition_expression
    }
    FieldMapping {
        int route_definition_id FK
        string source_field
        string target_field
        string transform_type
    }
    DeliveryAttempt {
        int event_message_id FK
        int route_definition_id FK
        int attempt_number
        string status
    }
    DeadLetterItem {
        int event_message_id FK
        int route_definition_id FK
        int retry_count
        string status
    }

Message protocol

The message_v1 traffic of networks such as work_supply. An EventMessage gets one RouteDecision per destination (explicit, the entity's owner, or a matching Subscription); each delivery is a DeliveryAttempt, the receiver's answer an Acknowledgement; a route that gives up becomes a DeadLetterItem; open delivery problems are tracked as MessageReconciliation rows. Subscription is matched by message-type pattern, not by a stored FK. See 04 — Message Protocol.

erDiagram
    EventMessage ||--o{ RouteDecision : "routed to"
    RouteDecision ||--o{ DeliveryAttempt : "delivered by"
    RouteDecision ||--o| Acknowledgement : "answered by"
    RouteDecision ||--o{ DeadLetterItem : "gave up as"
    RouteDecision ||--o{ MessageReconciliation : "problem on"
    Subscription ||..o{ RouteDecision : "matches (by message type)"

    EventMessage {
        string event_sid UK
        string protocol "entity_sync / message_v1"
        string message_kind "event / command / query"
        string event_type
        string source_application_code
        string correlation_sid
        string status
    }
    Subscription {
        string subscription_code UK
        string network_code
        string message_type_pattern
        string destination_application_code
    }
    RouteDecision {
        int event_message_id FK
        string destination_application_code
        string route_reason "explicit / owner / subscription"
        string decision_status
        int attempts
        datetime next_attempt_at
    }
    DeliveryAttempt {
        int route_decision_id FK
        int attempt_number
        int response_status
        int duration_ms
        string status
    }
    Acknowledgement {
        int route_decision_id FK
        string acknowledgement_type "Completed / Rejected / Duplicate"
        string result_code
    }
    DeadLetterItem {
        int route_decision_id FK
        string reason_code
        string status "Open / Retrying / Resolved"
    }
    MessageReconciliation {
        int route_decision_id FK
        string reconciliation_type
        string status
    }

Scheduling

Actions are invoked by jobs; jobs run on schedules; schedules produce executions. SyncCheckpoint and RetryPolicy are flat reference tables the rest of the module keys off by code. (These are logical links — job_code, action_code, schedule_code, retry_policy_code are business codes, not stored FKs.)

erDiagram
    ActionDefinition ||..o{ JobDefinition : "runs (by action_code)"
    JobDefinition ||..o{ Schedule : "triggered by (by job_code)"
    Schedule ||..o{ JobExecution : "produces (by schedule_code)"
    RetryPolicy ||..o{ JobDefinition : "governs back-off"

    ActionDefinition {
        string action_code UK
        string application_code
        string http_method
        bool idempotent
    }
    JobDefinition {
        string job_code UK
        string action_code
        string concurrency_mode
        string retry_policy_code
    }
    Schedule {
        string schedule_code UK
        string job_code
        string schedule_type "Cron/Interval/OneTime"
        string misfire_policy
    }
    JobExecution {
        string execution_code UK
        string job_code
        string triggered_by
        string status
    }
    SyncCheckpoint {
        string checkpoint_code UK
        string entity_code
        string checkpoint_type
        string status "Current/Stale/Failed"
    }
    RetryPolicy {
        string retry_policy_code UK
        int max_attempts
        float backoff_multiplier
    }

Governance

Controls run and produce executions; a failed execution raises a governance exception; every step on the exception is logged as an action. ControlExecution and ExceptionAction are the physical children.

erDiagram
    ControlDefinition ||--o{ ControlExecution : "runs"
    ControlDefinition ||..o{ GovernanceException : "raises (by control_code)"
    GovernanceException ||--o{ ExceptionAction : "worked via"

    ControlDefinition {
        string control_code UK
        string control_type "10 assurance types"
        string authoritative_application_code
        string compare_application_code
        string severity
    }
    ControlExecution {
        int control_definition_id FK
        string execution_code UK
        string status "Pass/Fail/Error"
        int exceptions_created
    }
    GovernanceException {
        string exception_code UK
        string name
        string exception_type
        string status "Open..Verified..Closed"
        string severity
    }
    ExceptionAction {
        int governance_exception_id FK
        string action_type
        string actor
        string resulting_status
    }

Regenerating this diagram

The interactive viewer is generated, never hand-edited. It reuses the ggcm/rehab viewer machinery and rebuilds its data block from schema/menu_config.yaml + generated/json/orchestrator_relationship_metadata.json, so the ERD always matches the schema. Re-run after any DSL or menu change:

python scripts/build_diagram_viewer.py orchestrator