Klaviyo Reference Architecture

What it does

When your agent uses it

• Designing new Klaviyo integrations
• Reviewing project structure
• Establishing architecture standards for email/SMS marketing applications
• With phrases like klaviyo architecture

Example prompts

• “klaviyo architecture”
• “klaviyo project structure”
• “klaviyo design”
• “/klaviyo-reference-architecture”

Requirements

• Compatibility (from SKILL.md): Designed for Claude Code
• Pre-approved tools (allowed-tools): Read, Write, Edit, Grep

Workflow steps

4 steps, taken from the first numbered list in SKILL.md.

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

What it can do on your machine

Read from SKILL.md and the folder at commit cfae287. It shows what the files ask for, not the result of running them.

• Tool permissions

  Pre-approves these tools, so the agent can use them without asking each time:

  • Read
  • Write
  • Edit
  • Grep

  From allowed-tools in the SKILL.md frontmatter.

• Runs code

  Shell commands in SKILL.md call:

  • tsc

  From the folder's file list and the shell code blocks in SKILL.md.

• Network

  Links to these hosts (documentation or services it may open):

  • developers.klaviyo.com

  From URLs in SKILL.md, links to its own repository left out.

• Credentials

  Names no API keys, tokens, secrets or passwords.

  From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

• Compatibility

  Designed for Claude Code

  From compatibility in the SKILL.md frontmatter.

Context cost

Klaviyo Reference Architecture loads about 1.3k tokens when it runs, and up to ~3.7k if it reads all its reference files. Until then it costs about 100 tokens; SKILL.md has 418 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it

~100

When it runs · the whole SKILL.md, loaded when a task matches

~1.3k

With references · SKILL.md plus every file in references/, read only if the agent opens them

~3.7k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from jeremylongshore/tons-of-skills-marketplace at commit cfae287, republished under its MIT licence (© jeremylongshore). 418 words, ~1,261 tokens.

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

compatibility

Designed for Claude Code

version

1.7.0

license

MIT

author

Jeremy Longshore <jeremy@intentsolutions.io>

tags

saas, klaviyo, email-marketing, cdp

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

await new EventTracker().trackPurchase({
  email: order.email,
  orderId: order.id,
  total: order.total,
  items: order.lineItems,
});

© jeremylongshore, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 2 other files (references) in skills/.curated/klaviyo-reference-architecture of jeremylongshore/tons-of-skills-marketplace.

• SKILL.md
• references/architecture.md
• references/implementation.md

Open the folder on GitHubat commit cfae287