klaviyo-reference-architecture

name	klaviyo-reference-architecture
description	Implement Klaviyo reference architecture with best-practice project layout. Use when designing new Klaviyo integrations, reviewing project structure, or establishing architecture standards for email/SMS marketing applications. Trigger with phrases like "klaviyo architecture", "klaviyo project structure", "klaviyo design", "how to organize klaviyo", "klaviyo layout".
allowed-tools	Read, Write, Edit, Grep
version	1.7.0
license	MIT
author	Jeremy Longshore <[e-mail]>
tags	["saas","klaviyo","email-marketing","cdp"]
compatibility	Designed for Claude Code

Klaviyo Reference Architecture

Overview

Production-ready architecture for Klaviyo integrations: a layered project structure, service patterns, event-driven sync, and the klaviyo-api SDK wired into a real application. SKILL.md gives you the four-layer contract and the skeleton you scaffold from; the deep material lives in references/ so you pull code only when you reach that layer.

• Layout & layering (full directory tree, layer contract, data flow): architecture.md
• Working code for every layer (config, profile sync, event tracker): implementation.md

Prerequisites

• TypeScript project with klaviyo-api installed
• Understanding of layered architecture
• Redis (for caching/queuing) and database (for audit/sync state)

Instructions

Use Write to scaffold the directory tree, then fill each layer bottom-up. The four layers and their one-way call rule:

API / Webhook Layer   →  routes + webhook handlers (calls Service only)
Service Layer         →  profile-sync, event-tracker, campaigns (calls SDK + Infra)
Klaviyo SDK Layer     →  ApiKeySession, ProfilesApi, EventsApi (never calls upward)
Infrastructure Layer  →  Redis cache, BullMQ queue, Prisma DB, OTel monitoring

1. Scaffold the tree. Create the src/{klaviyo,services,webhooks,jobs,middleware,config,health} layout. Full annotated tree: architecture.md.
2. Config layer first. A single loadConfig() returns environment-specific keys, rate limits, and cache TTLs — every other layer reads from it. Code: implementation.md Step 1.
3. Service layer. Build ProfileSyncService (bidirectional upsert) and EventTracker (server-side Placed Order / custom events). Both route Klaviyo calls through withRateLimitRetry. Code: implementation.md Steps 2–3.
4. Wire the data flow. Signup → syncToKlaviyo(), purchase → trackPurchase(), inbound profile.updated webhook → WebhookRouter.routeEvent() → local DB. Diagram: architecture.md.