customerio-reference-architecture

# 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 ``` ┌─────────────┐ ┌───────────────────┐ ┌──────────────┐ │ Application │───>│ MessagingService │───>│ Track API │ │ Routes │ │ (service layer) │ │ identify() │ └─────────────┘ │ │ │ track() │ │ - identify users │ └──────────────┘ │ - track events │ │ - send txn emails │ ┌──────────────┐ │ │───>│ App API │ └───────────────────┘ │ sendEmail() │ │ │ broadcast() │ │ └──────────────┘ v ┌───────────────────┐ ...