klaviyo-reference-architecture

# Klaviyo Reference Architecture ## Overview Production-ready architecture for Klaviyo integrations: layered project structure, service patterns, event-driven sync, and the `klaviyo-api` SDK wired into a real application. ## Prerequisites - TypeScript project with `klaviyo-api` installed - Understanding of layered architecture - Redis (for caching/queuing) and database (for audit/sync state) ## Project Structure ``` src/ ├── klaviyo/ # SDK layer (thin wrappers) │ ├── session.ts # ApiKeySession singleton │ ├── api.ts # Lazy API client getters │ ├── types.ts # Shared Klaviyo types │ └── errors.ts # Error parsing/classification ├── services/ # Business logic layer │ ├── profile-sync.ts # Bidirectional profile sync │ ├── event-tracker.ts # Server-side event tracking │ ├── campaign-manager.ts # Campaign create/send │ ├── list-manager.ts # List/subscription management │ └── segment-query.ts # Segment membership queries ├── webhooks/ # Inbound webhook handlers │ ├── router.ts # Topic-based event routing │ ├── verify.ts # HMAC-SHA256 signature verification │ └── handlers/ │ ├── profile-events.ts # profile.created, profile.updated │ ├── list-events.ts # list.member.added/removed │ └── campaign-events.ts # campaign.sent, delivered ├── jobs/ ...