customerio-reference-architecture

name	customerio-reference-architecture
description	Implement Customer.io enterprise reference architecture. Use when designing integration layers, event-driven architectures, or enterprise-grade Customer.io setups. Trigger: "customer.io architecture", "customer.io design", "customer.io enterprise", "customer.io integration pattern".
allowed-tools	Read, Write, Edit, Bash(npm:*), Bash(npx:*), Glob, Grep
version	1.14.0
license	MIT
author	Jeremy Longshore <[e-mail]>
tags	["saas","customer-io","architecture","enterprise"]
compatibility	Designed for Claude Code, also compatible with Codex and OpenClaw

Customer.io Reference Architecture

Overview

Enterprise-grade reference architecture for Customer.io: a service layer separating Track and App API concerns, event-driven processing with message queues, repository pattern for user-to-CIO sync, webhook event bus, and infrastructure as code.

Architecture Principles

1. Two Clients, Two Concerns — TrackClient for behavioral data in, APIClient for messages out
2. Event-Driven — Message queues decouple your app from Customer.io API availability
3. Idempotent Operations — All writes safely retryable via content hashing
4. Service Layer — Business logic never calls Customer.io SDK directly
5. Observability — Every operation emits timing and error metrics

Architecture Diagram

┌─────────────┐    ┌───────────────────┐    ┌──────────────┐
│ Application │───>│ MessagingService  │───>│ Track API    │
│ Routes      │    │ (service layer)   │    │ identify()   │
└─────────────┘    │                   │    │ track()      │
                   │ - identify users  │    └──────────────┘
                   │ - track events    │
                   │ - send txn emails │    ┌──────────────┐
                   │                   │───>│ App API      │
                   └───────────────────┘    │ sendEmail()  │
                          │                 │ broadcast()  │
                          │                 └──────────────┘
                          v
                   ┌───────────────────┐
                   │ Event Queue       │    ┌──────────────┐
                   │ (Redis/Kafka)     │───>│ DLQ          │
                   │ for reliability   │    │ (failures)   │
                   └───────────────────┘    └──────────────┘

┌─────────────┐    ┌───────────────────┐    ┌──────────────┐
│ Customer.io │───>│ Webhook Handler   │───>│ BigQuery     │
│ Webhooks    │    │ HMAC verification │    │ (analytics)  │
└─────────────┘    │ Event routing     │    └──────────────┘

Instructions

Step 1: Core Service Layer

// services/messaging-service.ts
import { EventEmitter } from "events";
import { TrackClient, APIClient, SendEmailRequest, RegionUS, RegionEU }  ;

  {
  : ;
  : ;
  : ;
  :  | ;
}

     {
   : ;
   : ;

  () {
    ();
     region = config. ===  ?  : ;
    . =  (config., config., { region });
    . =  (config., { region });
  }

   (: , : <, >): <> {
     start = .();
     {
       ..(userId, {
        ...attrs,
        : .(.() / ),
      });
      .(, { userId, : .() - start });
    }  (err) {
      .(, { : , userId, err });
       err;
    }
  }

   (
    : ,
    : ,
    ?: <, >
  ): <> {
     start = .();
     {
       ..(userId, { name, data });
      .(, { userId, name, : .() - start });
    }  (err) {
      .(, { : , userId, name, err });
       err;
    }
  }

   (
    : ,
    : ,
    : <, >,
    ?: { ?: ; ?:  }
  ): <{ :  }> {
     start = .();
     {
       request =  ({
        to,
        : templateId,
        : data,
        identifiers,
      });
       result =  ..(request);
      .(, { to, templateId, : .() - start });
       result;
    }  (err) {
      .(, { : , to, templateId, err });
       err;
    }
  }

   (
    : ,
    : <, >,
    : { ?: { :  }; ?: []; ?: [] }
  ): <> {
     ..(broadcastId, data, options);
    .(, { broadcastId });
  }

   (: ): <> {
     ..(userId);
  }

   (: ): <> {
     ..(userId);
  }
}