How commercetools/connect-shipping-integration-ingrid works
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)