apollo-reference-architecture

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".

الانتقال إلى التثبيت

المستودع: jeremylongshore/tons-of-skills-marketplace
آخر نشاط في المصدر: ١٩ أغسطس ٢٠٢٦ في ١٢:١٣
لغة SKILL.md المكتشفة: الإنجليزية
النجوم: ٢٬٦٧٧
التفرعات: ٣٩٢

خيارات التثبيت

يُحدَّد Prompt الذي يراجع المصدر أولًا بشكل افتراضي. يمكنك التبديل إلى أمر مباشر أو تنزيل نسخة محلية.

مراجعة ملفات المصدر

اقرأ SKILL.md وأي ملفات مرافقة يعرضها SkillsMP قبل أن تقرر التثبيت.

العودة إلى البحث العودة إلى التثبيت

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 <jeremy@intentsolutions.io>
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 },
    );
  }
}

// src/services/deal-service.ts
export class DealService {
  private client = getApolloClient();

  async createDeal(params: {
    name: string;
    amount: number;
    ownerId: string;       // Apollo user ID
    accountId?: string;    // Apollo account ID
    contactIds?: string[]; // Apollo contact IDs
    stageId?: string;      // Deal stage ID
  }) {
    const { data } = await this.client.post('/opportunities', {
      name: params.name,
      amount: params.amount,
      owner_id: params.ownerId,
      account_id: params.accountId,
      contact_ids: params.contactIds,
      opportunity_stage_id: params.stageId,
    });
    return { dealId: data.opportunity.id, name: data.opportunity.name };
  }

  async listDeals(page: number = 1) {
    const { data } = await this.client.post('/opportunities/search', { page, per_page: 50 });
    return data.opportunities.map((d: any) => ({
      id: d.id, name: d.name, amount: d.amount,
      stage: d.opportunity_stage?.name, owner: d.owner?.name,
    }));
  }

  async getDealStages() {
    const { data } = await this.client.get('/opportunity_stages');
    return data.opportunity_stages.map((s: any) => ({ id: s.id, name: s.name, order: s.display_order }));
  }

  async updateDeal(dealId: string, updates: { amount?: number; stageId?: string }) {
    await this.client.patch(`/opportunities/${dealId}`, {
      amount: updates.amount,
      opportunity_stage_id: updates.stageId,
    });
  }
}

// src/jobs/enrichment-job.ts
import { Queue, Worker, Job } from 'bullmq';
import { LeadService } from '../services/lead-service';

const connection = { host: process.env.REDIS_HOST ?? 'localhost', port: 6379 };

export const enrichmentQueue = new Queue('apollo-enrichment', {
  connection,
  defaultJobOptions: {
    attempts: 3,
    backoff: { type: 'exponential', delay: 5000 },
    removeOnComplete: 1000,
  },
});

const leadService = new LeadService();

new Worker('apollo-enrichment', async (job: Job) => {
  switch (job.name) {
    case 'enrich-person':
      return leadService.enrichPerson(job.data.email);
    case 'enrich-org':
      return leadService.enrichOrg(job.data.domain);
    case 'bulk-search': {
      const results: any[] = [];
      for (const domain of job.data.domains) {
        const { data } = await leadService.searchPeople({ domains: [domain] });
        results.push(...data.people);
        await job.updateProgress(results.length);
      }
      return { total: results.length };
    }
  }
}, { connection, concurrency: 3, limiter: { max: 50, duration: 60_000 } });

// src/models/contact.ts (Prisma schema excerpt)
// model Contact {
//   id             String   @id @default(cuid())
//   apolloId       String   @unique
//   email          String   @unique
//   name           String
//   title          String?
//   seniority      String?
//   phone          String?
//   linkedinUrl    String?
//   organizationId String?
//   rawApolloData  Json?
//   enrichedAt     DateTime?
//   createdAt      DateTime @default(now())
//   updatedAt      DateTime @updatedAt
// }

// TypeORM version
import { Entity, Column, PrimaryColumn, CreateDateColumn, UpdateDateColumn } from 'typeorm';

@Entity('contacts')
export class Contact {
  @PrimaryColumn() apolloId: string;
  @Column({ unique: true }) email: string;
  @Column() name: string;
  @Column({ nullable: true }) title: string;
  @Column({ nullable: true }) seniority: string;
  @Column({ nullable: true }) phone: string;
  @Column({ nullable: true }) linkedinUrl: string;
  @Column({ type: 'jsonb', nullable: true }) rawApolloData: Record<string, any>;
  @Column({ nullable: true }) enrichedAt: Date;
  @CreateDateColumn() createdAt: Date;
  @UpdateDateColumn() updatedAt: Date;
}

// src/api/routes.ts
import { Router } from 'express';
import { LeadService } from '../services/lead-service';
import { DealService } from '../services/deal-service';

const router = Router();
const leads = new LeadService();
const deals = new DealService();

router.post('/api/leads/search', async (req, res) => {
  const { data } = await leads.searchPeople(req.body);
  res.json({ leads: data.people, pagination: data.pagination });
});

router.post('/api/leads/enrich', async (req, res) => {
  const { data } = await leads.enrichPerson(req.body.email);
  res.json({ contact: data.person });
});

router.get('/api/organizations/:domain', async (req, res) => {
  const { data } = await leads.enrichOrg(req.params.domain);
  res.json({ organization: data.organization });
});

router.post('/api/deals', async (req, res) => {
  const result = await deals.createDeal(req.body);
  res.json(result);
});

router.get('/api/deals', async (req, res) => {
  const list = await deals.listDeals(parseInt(req.query.page as string) || 1);
  res.json({ deals: list });
});

export { router };

Layer	Strategy
Client	Retry with backoff, circuit breaker for prolonged outages
Service	Cache fallback on failure, credit budget enforcement
Jobs	3 retries with exponential backoff, dead letter after max
API	Structured JSON error responses with error codes