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