Customer.io Reference Architecture

Overview

Enterprise-grade reference architecture for Customer.io integration with proper separation of concerns, event-driven processing, and infrastructure as code.

Architecture Principles

• Separation of Concerns: Track API, App API, and Webhooks handled by separate services

• Event-Driven: Message queues for reliable async processing

• Idempotency: All operations safely retryable

• Observability: Events emitted for monitoring and debugging

• Infrastructure as Code: All resources defined in Terraform

Instructions

Step 1: Build Core Service Layer

Create a CustomerIOService class extending EventEmitter with typed config, Track and App API clients, and lifecycle events for identify, track, and transactional operations.

Step 2: Add Event Bus Integration

Implement Kafka-based event processing with topics for identify, track, and transactional operations, plus dead letter queue for failures.

Step 3: Create Repository Pattern

Build a UserMessagingRepository that syncs user data from your database to Customer.io and manages messaging preferences.

Step 4: Implement Webhook Handler

Create an EventEmitter-based webhook handler with signature verification, per-event-type listeners, and wildcard streaming to data warehouse.

Step 5: Define Infrastructure as Code

Write Terraform for GCP Secret Manager secrets, Cloud Run service, Pub/Sub topics, and BigQuery tables for event analytics.

For detailed implementation code and Terraform configurations, load the reference guide: Read(${CLAUDE_SKILL_DIR}/references/implementation-guide.md)

Output

• Core Customer.io service layer with EventEmitter

• Kafka event bus integration with DLQ

• Repository pattern for user messaging

• Webhook handler with signature verification

• Terraform infrastructure definitions

Error Handling

Issue Solution

Event processing failure Routes to dead letter queue

Secret rotation needed Update via Terraform + secrets manager

Webhook signature invalid Verify secret matches dashboard

Resources

• Customer.io API Reference

• Webhook Documentation

Next Steps

After implementing architecture, proceed to customerio-multi-env-setup for multi-environment configuration.

Prerequisites

• Access to the design environment or API

• Required CLI tools installed and authenticated

• Familiarity with design concepts and terminology

Examples

Basic usage: Apply customerio reference architecture to a standard project setup with default configuration options.

Advanced scenario: Customize customerio reference architecture for production environments with multiple constraints and team-specific requirements.