# Customerio Reference Architecture

> Implement Customer.io reference architecture. Use when designing integrations, planning architecture, or implementing enterprise patterns. Trigger with phrases like "customer.io architecture", "customer.io design", "customer.io enterprise", "customer.io integration pattern".

- Skill: `micsapp/customerio-reference-architecture` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add micsapp/customerio-reference-architecture`
- Raw SKILL.md: https://api.skillmd.com/api/skills/micsapp/customerio-reference-architecture/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- License: MIT
- Author: micsapp (https://skillmd.com/u/micsapp)
- Updated: 2026-09-08
- Page: https://skillmd.com/skills/micsapp/customerio-reference-architecture

---

# 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](https://customer.io/docs/api/)
- [Webhook Documentation](https://customer.io/docs/webhooks/)

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