salesloft-reference-architecture

name	salesloft-reference-architecture
description	Production architecture for SalesLoft API integrations with service layer, webhook processing, and CRM sync patterns. Use when designing new SalesLoft integrations or reviewing project structure. Trigger: "salesloft architecture", "salesloft project structure", "salesloft design".
allowed-tools	Read, Grep
version	1.6.0
license	MIT
author	Jeremy Longshore <[e-mail]>
tags	["saas","sales","outreach","salesloft"]
compatibility	Designed for Claude Code

SalesLoft Reference Architecture

Overview

Production architecture for SalesLoft API integrations: typed API client, service layer with caching, webhook processor, and background sync. Designed around SalesLoft's REST API v2 with cost-based rate limiting.

Project Structure

salesloft-integration/
├── src/
│   ├── salesloft/
│   │   ├── client.ts           # Axios wrapper with rate-limit handling
│   │   ├── types.ts            # Person, Cadence, Activity types
│   │   ├── paginator.ts        # AsyncGenerator pagination
│   │   └── errors.ts           # SalesloftApiError class
│   ├── services/
│   │   ├── people-sync.ts      # Bidirectional people sync
│   │   ├── cadence-manager.ts  # Cadence CRUD + enrollment
│   │   └── activity-tracker.ts # Email/call activity aggregation
│   ├── webhooks/
│   │   ├── handler.ts          # Signature verification + routing
│   │   └── processors/        # Per-event-type processors
│   ├── jobs/
│   │   ├── incremental-sync.ts # Cron: sync changed records
│   │   └── engagement-report.ts# Cron: aggregate daily metrics
│   └── api/
│       ├── health.ts           # /health endpoint
│       └── webhooks.ts         # /webhooks/salesloft endpoint
├── config/
│   ├── default.json
│   ├── production.json
│   └── test.json
└── tests/
    ├── unit/
    └── integration/

Architecture Diagram

┌─────────────────────────────────┐
│           API Layer             │
│  /health  /webhooks/salesloft   │
├─────────────────────────────────┤
│         Service Layer           │
│  PeopleSync  CadenceManager    │
│  ActivityTracker               │
├─────────────────────────────────┤
│       SalesLoft Client          │
│  Typed API  Pagination  Retry  │
├─────────────────────────────────┤
│       Infrastructure            │
│  Redis Cache  BullMQ Jobs      │
│  PostgreSQL  Prometheus        │
└─────────────────────────────────┘
         │              ▲
         ▼              │
┌─────────────────────────────────┐
│     SalesLoft REST API v2       │
│  /people  /cadences  /webhooks  │
│  Rate: 600 cost/min             │
└─────────────────────────────────┘

Key Components

Typed API Models

// src/salesloft/types.ts
export interface SalesloftPerson {
  id: number;
  display_name: string;
  email_address: string;
  first_name: string;
  last_name: ;
  :  | ;
  :  | ;
  :  | ;
  :  | ;
  :  | ;
  : [];
  : ;
  : ;
}

   {
  : ;
  : ;
  :  |  |  | ;
  : ;
  : { :  };
}

   {
  : ;
  :  |  |  | ;
  : ;
  :  | ;
  : ;
}