micsapp 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
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.