Clay Architecture VariantsSAFE

Model-agnostic agent-skills platform with a harness-free canonical layer, verified adapters, and the ccpi package manager. Explore at tonsofskills.com.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: clay-architecture-variants
description: 'Choose and implement Clay integration architecture for different scales
  and use cases.

  Use when designing new Clay integrations, comparing direct vs queue-based vs event-driven,

  or planning architecture for Clay-powered data operations.

  Trigger with phrases like "clay architecture", "clay blueprint",

  "how to structure clay", "clay integration design", "clay event-driven".

  '
allowed-tools: Read, Write, Edit, Grep
version: 1.14.0
license: MIT
author: Jeremy Longshore <[email protected]>
tags:
- saas
- clay
- migration
- scaling
compatibility: Designed for Claude Code
---
# Clay Architecture Variants

## Overview

Three proven architecture patterns for Clay data enrichment at different scales. Clay is a hosted SaaS -- your architecture decisions focus on how you send data in (webhooks), how you get enriched data out (HTTP API columns, CRM sync, or CSV export), and how you orchestrate the flow.

## Prerequisites

- Clay account with appropriate plan tier
- Clear understanding of data volume and latency requirements
- Infrastructure for chosen architecture tier (if queue-based or event-driven)

## Instructions

### Architecture 1: Direct Integration (Simple)

**Best for:** Small teams, < 1K enrichments/day, ad-hoc usage.

```
┌──────────────┐     webhook     ┌───────────┐
│ Your App     │───────POST─────>│ Clay Table │
│ (or CSV)     │                 │ (enriches) │
└──────────────┘                 └─────┬─────┘
                                       │
                                  CRM action
                                  or CSV export
                                       │
                                       v
                                 ┌───────────┐
                                 │ CRM / DB  │
                                 └───────────┘
```

```typescript
// Direct: send leads synchronously, export results manually
async function directEnrich(leads: Lead[]): Promise<void> {
  for (const lead of leads) {
    await fetch(process.env.CLAY_WEBHOOK_URL!, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(lead),
    });
    await new Promise(r => setTimeout(r, 250)); // Rate limit
  }
  console.log(`Sent ${leads.length} leads. Check Clay table for enriched data.`);
  // Enriched data reaches CRM via Clay's native CRM action column
}
```

**Pros:** Zero infrastructure, 5-minute setup, works on all Clay plans.
**Cons:** No retry logic, no programmatic access to enriched data, manual export only.

---

### Architecture 2: Webhook-in, HTTP API-out (Standard)

**Best for:** Growing teams, 1K-10K enrichments/day, CRM integration.

```
┌──────────────┐     webhook     ┌───────────┐   HTTP API col   ┌──────────────┐
│ Your App     │───────POST─────>│ Clay Table │──────POST──────>│ Your Webhook │
│              │                 │ (enriches) │                 │ Handler      │
└──────────────┘                 └───────────┘                 └──────┬───────┘
                                                                      │
                                                                 Process +
                                                                 Route
                                                                      │
                                                          ┌───────────┼───────────┐
                                                          │           │           │
                                                          v           v           v
                                                       ┌─────┐   ┌───────┐   ┌──────┐
                                                       │ CRM │   │Outreach│  │ DB   │
                                                       └─────┘   └───────┘   └──────┘
```

```typescript
// Standard: send leads via webhook, receive enriched data via HTTP API column
// Inbound: Your app -> Clay
async function sendLeads(leads: Lead[]): Promise<void> {
  const batchResult = await clayClient.sendBatch(leads, 200);
  console.log(`Sent: ${batchResult.sent}, Failed: ${batchResult.failed}`);
}

// Outbound: Clay HTTP API column -> Your webhook handler
app.post('/api/clay/enriched', async (req, res) => {
  res.json({ ok: true }); // Respond fast

  const lead = req.body;
  if (lead.icp_score >= 80 && lead.work_email) {
    await pushToCRM(lead);
    await addToOutreachSequence(lead);
  } else if (lead.icp_score >= 50) {
    await addToNurtureCampaign(lead);
  }
});
```

**Pros:** Full automation, programmatic access to enriched data, flexible routing.
**Cons:** Requires Growth plan (HTTP API columns), needs public HTTPS endpoint.

---

### Architecture 3: Queue-Based Pipeline (Scale)

**Best for:** Enterprise, 10K+ enrichments/day, multiple data sources.

```
┌───────────┐
│ Web Forms │──┐
└───────────┘  │     ┌───────────┐     webhook     ┌───────────┐
               ├────>│ Job Queue │───────POST─────>│ Clay Table │
┌───────────┐  │     │ (BullMQ)  │                 │ (enriches) │
│ CRM Events│──┘     └───────────┘                 └─────┬─────┘
└───────────┘              │                              │
                      DLQ on fail                   HTTP API col
┌───────────┐              │                              │
│ CSV Import│──────────────┘                              v
└───────────┘                                   ┌──────────────┐
                                                │ Your Handler │
                                                │ (w/ circuit  │
                                                │  breaker)    │
                                                └──────┬───────┘
                                                       │
                                            ┌──────────┼──────────┐
                                            │          │          │
                                            v          v          v
                               

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (0)

No findings outside the package's declared scope.

Gates applied: no_behavioural_pass.