# commercetools/connect-shipping-integration-ingrid architecture

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

- Interactive diagram: https://gitdiagram.com/commercetools/connect-shipping-integration-ingrid
- Repository: https://github.com/commercetools/connect-shipping-integration-ingrid

## Overview

##### Project type and purpose
- This is a full-stack “Connect” connector integrating Commercetools Composable Commerce with Ingrid shipping.
- It is composed of three modules:
- Enabler (frontend assets & JS SDK for checkout page)
- Processor (HTTP service/API for session init & updates)
- Event-handler (event-driven service for order completion)

##### File structure
- Top-level contains three folders:
- enabler/ – React/TypeScript SDK, static assets, build & test config
- processor/ – Fastify HTTP service, business logic, Commercetools & Ingrid clients, auth, retry engine
- event-handler/ – Express/Fastify event service, processes Commercetools subscription messages
- Docker-compose, connect.yaml orchestrate local dev & Connect publishing
- Each module has its own src/, test/, package.json, tsconfig, configs, and CI workflows
- External dependencies: Commercetools SDK, Ingrid REST API

##### README for additional insights
- Describes three flows: Initial (session init), Update (sync changes), Completion (orderCreated event)
- Deployment config defined in connect.yaml

a. Main components
1. User’s Checkout Page (browser UI)
2. Enabler Module (JS SDK & iFrame widget)
3. Processor Module (HTTP API: /sessions/init, /sessions/update)
4. Event-handler Module (event endpoint for Commercetools subscriptions)
5. Commercetools Composable Commerce (Cart, Checkout Session, Order, Subscription)
6. Ingrid Platform (session.create, session.get/update, session.complete)
7. Configuration Store (environment variables, Connect configuration)

b. Relationships & interactions
- User → Enabler SDK → Processor API → Commercetools → Ingrid
- Enabler captures user events (address/method change) → Processor → Commercetools & Ingrid
- Commercetools subscription pushes OrderCreated message → Event-handler → Ingrid → Commercetools
- Processor and Event-handler authenticate via Commercetools SDK and Ingrid API key

c. Architectural patterns & design principles
- Separation of concerns: frontend (enabler), backend REST (processor), event service (event-handler)
- Microservices / modular services—each module deploys independently
- Event-driven architecture for order completion via Commercetools subscription
- Retry logic in processor when communicating with Ingrid
- Shared authentication & context provider layers (Fastify context)

d. Key technologies
- TypeScript, React, Vite (enabler)
- Fastify (processor), Express/Fastify (event-handler)
- @commercetools/sdk-client, Ingrid REST APIs
- Docker Compose for local dev
- Jest for unit tests

##### Essential elements to capture
- Initialization Flow: Checkout → Enabler → Processor → Commercetools & Ingrid → Widget HTML
- Update Flow: Widget events → Enabler → Processor → Ingrid → Processor → Commercetools
- Completion Flow: OrderCreated → Commercetools Subscription → Event-handler → Ingrid → Commercetools
- Configurations (env vars) feeding into services
- Authentication layers (Commercetools OAuth, Ingrid API key)

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Connector Modules"
        subgraph "Enabler Module"
            direction TB
            ENRoot["Enabler Module (Frontend SDK)"]:::frontend
            Entry["Widget Bootstrap"]:::frontend
            CartEditor["Cart Editor Components"]:::frontend
            Stores["State Stores"]:::frontend
            Style["Styles & Assets"]:::frontend
            ConfigEnabler["Build & Config"]:::frontend
            ENRoot --> Entry
            ENRoot --> CartEditor
            ENRoot --> Stores
            ENRoot --> Style
            ENRoot --> ConfigEnabler
        end
        subgraph "Processor Module"
            direction TB
            PROot["Processor Module (HTTP API)"]:::backend
            MainServer["Main Server Bootstrap"]:::backend
            Routes["Sessions Init/Update Routes"]:::backend
            BizLogic["Shipping Service Logic"]:::backend
            Retry["Retry Engine"]:::backend
            CTClient["Commercetools Client"]:::backend
            IngridClient["Ingrid Client"]:::backend
            AuthLayer["Auth Layer"]:::backend
            FastifyLib["Fastify Context & Error Handling"]:::backend
            ProcConfig["Config & Env"]:::backend
            BuildProc["Build & Config"]:::backend
            PROot --> MainServer
            PROot --> Routes
            PROot --> BizLogic
            PROot --> Retry
            PROot --> CTClient
            PROot --> IngridClient
            PROot --> AuthLayer
            PROot --> FastifyLib
            PROot --> ProcConfig
            PROot --> BuildProc
        end
        subgraph "Event-handler Module"
            direction TB
            ERoot["Event-handler Module"]:::backend
            AppEntry["App Entry"]:::backend
            RouteEH["Subscription Webhook Route"]:::backend
            ControllerEH["OrderCreated Controller"]:::backend
            CTClientEH["Commercetools Client"]:::backend
            IngridClientEH["Ingrid Client"]:::backend
            Lifecycle["Connector Lifecycle Hooks"]:::backend
            MiddlewareEH["Middleware"]:::backend
            UtilsEH["Utils & Validation"]:::backend
            ConfigEH["Config & Types"]:::backend
            ERoot --> AppEntry
            ERoot --> RouteEH
            ERoot --> ControllerEH
            ERoot --> CTClientEH
            ERoot --> IngridClientEH
            ERoot --> Lifecycle
            ERoot --> MiddlewareEH
            ERoot --> UtilsEH
            ERoot --> ConfigEH
        end
    end
    subgraph "External Systems"
        direction TB
        CT["Commercetools Composable Commerce"]:::external
        Ingrid["Ingrid Platform"]:::external
    end
    User["User Checkout Page"]:::external
    ConfigStore["Configuration Store"]:::external

    User -->|"0: load widget"| ENRoot
    ENRoot -->|"1: POST /sessions/init"| PROot
    PROot -->|"2a: create session in CT"| CT
    PROot -->|"2b: session.create"| Ingrid
    PROot -->|"env configs"| ConfigStore
    ENRoot -->|"load widget HTML"| User

    ENRoot -->|"3: update events"| PROot
    PROot -->|"3b: session.get/update"| Ingrid
    PROot -->|"3c: update CT session"| CT

    CT -->|"4: subscription orderCreated"| ERoot
    ERoot -->|"5a: complete session"| Ingrid
    ERoot -->|"5b: update CT order"| CT
    ERoot -->|"env configs"| ConfigStore

    click ENRoot "https://github.com/commercetools/connect-shipping-integration-ingrid/tree/main/enabler/"
    click Entry "https://github.com/commercetools/connect-shipping-integration-ingrid/blob/main/enabler/src/shipping-enabler/shipping-enabler.ts"
    click CartEditor "https://github.com/commercetools/connect-shipping-integration-ingrid/tree/main/enabler/src/configurator/cartEditor/"
    click Stores "https://github.com/commercetools/connect-shipping-integration-ingrid/tree/main/enabler/src/configurator/stores/"
    click Style "https://github.com/commercetools/connect-shipping-integration-ingrid/tree/main/enabler/src/style/"
    click ConfigEnabler "https://github.com/commercetools/connect-shipping-integration-ingrid/blob/main/enabler/vite.config.ts"
    click ConfigEnabler "https://github.com/commercetools/connect-shipping-integration-ingrid/blob/main/enabler/tsconfig.json"
    click ConfigEnabler "https://github.com/commercetools/connect-shipping-integration-ingrid/blob/main/enabler/package.json"

    click PROot "https://github.com/commercetools/connect-shipping-integration-ingrid/tree/main/processor/"
    click MainServer "https://github.com/commercetools/connect-shipping-integration-ingrid/blob/main/processor/src/main.ts"
    click Routes "https://github.com/commercetools/connect-shipping-integration-ingrid/blob/main/processor/src/routes/ingrid-shipping.route.ts"
    click BizLogic "https://github.com/commercetools/connect-shipping-integration-ingrid/blob/main/processor/src/services/ingrid-shipping.service.ts"
    click Retry "https://github.com/commercetools/connect-shipping-integration-ingrid/blob/main/processor/src/engines/retry.engine.ts"
    click CTClient "https://github.com/commercetools/connect-shipping-integration-ingrid/blob/main/processor/src/clients/commercetools/api.client.ts"
    click IngridClient "https://github.com/commercetools/connect-shipping-integration-ingrid/blob/main/processor/src/clients/ingrid/ingrid.client.ts"
    click AuthLayer "https://github.com/commercetools/connect-shipping-integration-ingrid/tree/main/processor/src/libs/auth/"
    click FastifyLib "https://github.com/commercetools/connect-shipping-integration-ingrid/tree/main/processor/src/libs/fastify/"
    click ProcConfig "https://github.com/commercetools/connect-shipping-integration-ingrid/blob/main/processor/src/config/index.ts"
    click ProcConfig "https://github.com/commercetools/connect-shipping-integration-ingrid/blob/main/processor/.env.template"
    click BuildProc "https://github.com/commercetools/connect-shipping-integration-ingrid/blob/main/processor/tsconfig.json"
    click BuildProc "https://github.com/commercetools/connect-shipping-integration-ingrid/blob/main/processor/package.json"

    click ERoot "https://github.com/commercetools/connect-shipping-integration-ingrid/tree/main/event-handler/"
    click AppEntry "https://github.com/commercetools/connect-shipping-integration-ingrid/blob/main/event-handler/src/app.ts"
    click AppEntry "https://github.com/commercetools/connect-shipping-integration-ingrid/blob/main/event-handler/src/index.ts"
    click RouteEH "https://github.com/commercetools/connect-shipping-integration-ingrid/blob/main/event-handler/src/routes/event.route.ts"
    click ControllerEH "https://github.com/commercetools/connect-shipping-integration-ingrid/blob/main/event-handler/src/controllers/event.controller.ts"
    click CTClientEH "https://github.com/commercetools/connect-shipping-integration-ingrid/tree/main/event-handler/src/client/commercetools/"
    click IngridClientEH "https://github.com/commercetools/connect-shipping-integration-ingrid/tree/main/event-handler/src/client/ingrid/"
    click Lifecycle "https://github.com/commercetools/connect-shipping-integration-ingrid/tree/main/event-handler/src/connector/"
    click MiddlewareEH "https://github.com/commercetools/connect-shipping-integration-ingrid/tree/main/event-handler/src/middleware/"
    click UtilsEH "https://github.com/commercetools/connect-shipping-integration-ingrid/tree/main/event-handler/src/utils/"
    click UtilsEH "https://github.com/commercetools/connect-shipping-integration-ingrid/tree/main/event-handler/src/validators/"
    click ConfigEH "https://github.com/commercetools/connect-shipping-integration-ingrid/tree/main/event-handler/src/interfaces/"
    click ConfigEH "https://github.com/commercetools/connect-shipping-integration-ingrid/tree/main/event-handler/src/types/"
    click ConfigEH "https://github.com/commercetools/connect-shipping-integration-ingrid/blob/main/event-handler/.env.example"

    classDef frontend fill:#ADD8E6,stroke:#000;
    classDef backend fill:#90EE90,stroke:#000;
    classDef external fill:#FFA500,stroke:#000;
```
