# nimitshukla123/sfcc-marketting-cloud-connector architecture

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

- Interactive diagram: https://gitdiagram.com/nimitshukla123/sfcc-marketting-cloud-connector
- Repository: https://github.com/nimitshukla123/sfcc-marketting-cloud-connector

## Overview

##### Project Type and Purpose
- This is a Salesforce B2C Commerce “cartridge‐based” integration connector that sits inside a B2C Commerce (Demandware) instance. It implements an above-the-API integration between B2C Commerce (both SiteGenesis and SFRA storefronts) and Salesforce Marketing Cloud (MC) via REST and SOAP APIs. It includes:
- A handler framework (int_handlerframework) that abstracts MC API calls and event tracking hooks.
- A marketing-cloud cartridge (int_marketing_cloud) that provides feeds, triggered-send logic, data-export jobs, models and webservice adapters.
- SiteGenesis/SFRA controller overlays (int_sitegenesis_marketing_cloud_controllers) for transactional emails and form handlers.
- A core cartridge (int_sitegenesis_marketing_cloud_core) that supplies ISML templates for UI components and hooks.
- A plugin cartridge (plugin_marketing_cloud) for SFRA-style controller overrides and helper methods.
- Postman collections for API testing and environment setups.
- Scheduled jobs (in sites/site_template) to push data syncs (catalog, orders, promotions, customers) to MC.

##### High-Level Architecture – Main Components
A. Storefront Layer (SiteGenesis or SFRA)
- Controllers (e.g., Cart, Account, Order) loaded from the storefront code and overlaid by int_* cartridges.
- ISML templates for pages/forms (opt-in, subscription, preferences).
- collect.js snippet for client-side analytics tracking.

B. Handler Framework Cartridge (int_handlerframework)
- Hook proxies and communication scripts that intercept platform hooks (onRequest, email, tracking) and route requests to handlers.
- Object mappers and velocity templates for data transformation.
- A thin façade over dw.svc.* to call MC REST/SOAP services.

C. Marketing-Cloud Cartridge (int_marketing_cloud)
- REST/SOAP service definitions (helper.js, rest.js, soap.js) for Marketing Cloud endpoints.
- Data models (authToken, dataExport, message, subscriber, trigger) to structure MC payloads and responses.
- Feed jobs (catalog.js, content.js, orders.js, customers.js, promotions.js, upload.js) under scripts/feeds and scripts/jobs to push CSV/XML via services or FTP.
- Triggered-send transactional email handlers.
- Custom Objects and site preferences for mapping configuration (steptypes.json, properties files).

D. Plug-in Cartridge (plugin_marketing_cloud)
- SFRA controller overrides and helper JS modules for account, email, contact-us.

E. Data Persistence & Configuration
- Custom Objects defined in sites/site_template/meta (e.g., MarketingCloudAuthToken, MarketingCloudTriggers, MarketingCloudDataExportStatus).
- Services.xml and jobs.xml to register scheduled tasks.
- cartridge int_* .properties and steptypes.json for cartridge order and metadata.

F. External Systems
- Marketing Cloud (REST & SOAP endpoints)
- FTP/SFTP (optional) for bulk data feeds.

##### Relationships & Interactions
1. Storefront controller receives HTTP request → If hook enabled, handler framework’s onRequest hook triggers data-layer script → event sent to MC via REST collect.js or server-side service call.
2. Cart/Order actions invoke hookProxy scripts → HandlerInclude routes to communication scripts → appropriate MC API method invoked (REST/SOAP).
3. Scheduled jobs (cron) run data-export cartridges → generate payload via Velocity templates → send to MC via bulk API or FTP.
4. Transactional email hooks intercept platform emails → map trigger keys and attributes → send triggered-send calls to MC.
5. Custom Objects store mapping configs, trigger definitions, token cache; ServiceRegistry handles credentials fallback per site.

##### Architectural Patterns & Design Principles
- Modular Cartridge Architecture: each integration concern is isolated in its own cartridge, loaded in dependency order.
- Adapter/Facade Pattern: handlerframework scripts abstract the MC API calls behind uniform interfaces.
- Hook-Based Extension: leveraging SFCC server and email hooks to inject tracking and transactional email logic without modifying core storefront.
- Template-Driven Data Mapping: Velocity templates drive the transformation of Commerce data into MC API payloads.
- Configuration-First: JSON and properties files define mapping, steptypes, and site preferences to avoid hardcoding.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Storefront Layer
    subgraph "Storefront Layer" 
        direction TB
        FS["SiteGenesis/SFRA"]:::sfcc
        SG_CTRL["Controller Overlays"]:::sfcc
        CORE_ISML["ISML Templates"]:::sfcc
        COLLECT["collect.js Snippet"]:::sfcc
    end

    %% Cartridge Stack
    subgraph "Cartridge Stack"
        direction TB
        HF["int_handlerframework"]:::adapter
        MC["int_marketing_cloud"]:::adapter
        SG_CONT["int_sitegenesis_marketing_cloud_controllers"]:::adapter
        CORE["int_sitegenesis_marketing_cloud_core"]:::adapter
        PL["plugin_marketing_cloud"]:::adapter
    end

    %% Data Persistence & Config
    subgraph "Data Persistence & Configuration"
        direction TB
        CO["Custom Objects"]:::config
        SVC_REG["services.xml"]:::config
        ST_HF["steptypes.json (handlerframework)"]:::config
        ST_MC["steptypes.json (marketing_cloud)"]:::config
        HOOKS["hooks.json (plugin)"]:::config
        PM_COL["Postman Collection"]:::config
        PM_ENV["Postman Environment"]:::config
    end

    %% Scheduled Jobs
    subgraph "Scheduled Jobs Engine"
        direction TB
        JOBS_XML["jobs.xml"]:::sfcc
        FEEDS["Feed Scripts"]:::sfcc
        SCRIPTSJ["Job Scripts"]:::sfcc
    end

    %% External Systems
    subgraph "External Systems"
        direction TB
        MC_REST["MC REST API"]:::external
        MC_SOAP["MC SOAP API"]:::external
        FTP["FTP/SFTP"]:::external
    end

    %% Relationships & Data Flows
    FS -->|HTTP Request| SG_CTRL
    SG_CTRL -->|Overlay Controller| HF
    CORE_ISML -->|Render UI| FS
    COLLECT -->|POST /collect| MC
    HF -->|Invoke REST/SOAP| MC
    HF -->|Triggered Send| MC
    PL -->|SFRA Overrides| SG_CTRL

    JOBS_XML -->|Cron Trigger| FEEDS
    FEEDS -->|Velocity Transform| MC
    FEEDS -->|Upload via FTP| FTP

    MC -->|POST /...| MC_REST
    MC -->|Invoke SOAP API| MC_SOAP

    %% Click Events
    click HF "https://github.com/nimitshukla123/sfcc-marketting-cloud-connector/tree/master/cartridges/int_handlerframework"
    click MC "https://github.com/nimitshukla123/sfcc-marketting-cloud-connector/tree/master/cartridges/int_marketing_cloud"
    click SG_CONT "https://github.com/nimitshukla123/sfcc-marketting-cloud-connector/tree/master/cartridges/int_sitegenesis_marketing_cloud_controllers/cartridge/controllers"
    click CORE "https://github.com/nimitshukla123/sfcc-marketting-cloud-connector/tree/master/cartridges/int_sitegenesis_marketing_cloud_core/cartridge/templates"
    click PL "https://github.com/nimitshukla123/sfcc-marketting-cloud-connector/tree/master/cartridges/plugin_marketing_cloud"
    click CO "https://github.com/nimitshukla123/sfcc-marketting-cloud-connector/blob/master/sites/site_template/meta/custom-objecttype-definitions.xml"
    click SVC_REG "https://github.com/nimitshukla123/sfcc-marketting-cloud-connector/blob/master/sites/site_template/services.xml"
    click ST_HF "https://github.com/nimitshukla123/sfcc-marketting-cloud-connector/blob/master/cartridges/int_handlerframework/steptypes.json"
    click ST_MC "https://github.com/nimitshukla123/sfcc-marketting-cloud-connector/blob/master/cartridges/int_marketing_cloud/steptypes.json"
    click HOOKS "https://github.com/nimitshukla123/sfcc-marketting-cloud-connector/blob/master/cartridges/plugin_marketing_cloud/hooks.json"
    click PM_COL "https://github.com/nimitshukla123/sfcc-marketting-cloud-connector/blob/master/Postman/Automate SFMC Configuration.postman_collection.json"
    click PM_ENV "https://github.com/nimitshukla123/sfcc-marketting-cloud-connector/blob/master/Postman/SFMC Config Automation Variables.postman_environment.json"
    click JOBS_XML "https://github.com/nimitshukla123/sfcc-marketting-cloud-connector/blob/master/sites/site_template/jobs.xml"
    click FEEDS "https://github.com/nimitshukla123/sfcc-marketting-cloud-connector/tree/master/cartridges/int_marketing_cloud/cartridge/scripts/feeds/"
    click SCRIPTSJ "https://github.com/nimitshukla123/sfcc-marketting-cloud-connector/tree/master/cartridges/int_marketing_cloud/cartridge/scripts/jobs/"

    %% Styles
    classDef sfcc fill:#cce5ff,stroke:#004085;
    classDef adapter fill:#ffe5b4,stroke:#cc5500;
    classDef config fill:#e2e3e5,stroke:#6c757d;
    classDef external fill:#d4edda,stroke:#155724;
```
