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

1. Separation of Concerns: Track API, App API, and Webhooks handled by separate services
2. Event-Driven: Message queues for reliable async processing
3. Idempotency: All operations safely retryable
4. Observability: Events emitted for monitoring and debugging
5. 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.