apollo-reference-architecture

name	apollo-reference-architecture
description	Implement Apollo.io reference architecture. Use when designing Apollo integrations, establishing patterns, or building production-grade sales intelligence systems. Trigger with phrases like "apollo architecture", "apollo system design", "apollo integration patterns", "apollo best practices architecture".
allowed-tools	Read, Write, Edit, Bash(gh:*), Bash(curl:*)
version	1.13.0
license	MIT
author	Jeremy Longshore <[e-mail]>
tags	["saas","apollo","apollo-reference"]
compatibility	Designed for Claude Code

Apollo Reference Architecture

Overview

Production-ready reference architecture for Apollo.io integrations. Layered design with API client, service layer, background jobs, database models, CRM sync, and deals pipeline — all built around Apollo's REST API with correct endpoints and x-api-key authentication.

Prerequisites

• Apollo master API key
• Node.js 18+ with TypeScript
• PostgreSQL for data layer
• Redis for job queues

Instructions

Step 1: Architecture Diagram

┌───────────────────────────────────────────────┐
│                 API Layer                      │  Express routes
│  POST /api/leads/search     GET /api/org/:d    │  POST /api/deals
├───────────────────────────────────────────────┤
│              Service Layer                     │  Business logic
│  LeadService    EnrichService   DealService    │  SequenceService
├───────────────────────────────────────────────┤
│              Client Layer                      │  Apollo API wrapper
│  ApolloClient   RateLimiter   Cache            │  CreditTracker
├───────────────────────────────────────────────┤
│            Background Jobs                     │  BullMQ queues
│  EnrichJob    SyncJob    StageChangeJob        │  TaskCreatorJob
├───────────────────────────────────────────────┤
│              Data Layer                        │  Prisma/TypeORM
│  Contact   Organization   Deal   AuditLog      │
└───────────────────────────────────────────────┘

Step 2: Service Layer

// src/services/lead-service.ts
import { getApolloClient } from '../apollo/client';
import { withRetry } from '../apollo/retry';
import { cachedRequest } from '../apollo/cache';

export class LeadService {
  private client = getApolloClient();

  async searchPeople(params: { domains: string[]; titles?: string[]; seniorities?: string[]; page?:  }) {
     (,
       ( ..(, {
        : params.,
        : params.,
        : params.,
        : params. ?? , : ,
      })),
      params,
    );
  }

   () {
     ( ..(, { email }));
  }

   () {
     (,
       ( ..(, { : { domain } })),
      { domain },
    );
  }
}