Imported from jeremylongshore/tons-of-skills-marketplace (plugins/saas-packs/salesforce-pack/skills/salesforce-architecture-variants/SKILL.md). Install upstream with npx skills add jeremylongshore/tons-of-skills-marketplace --skill salesforce-architecture-variants. Copyright stays with the author (MIT).

Salesforce Architecture Variants

Overview

Three validated architecture blueprints for Salesforce integrations: Direct API (simple), Event-Driven (scalable), and Middleware/iPaaS (enterprise). Each pattern addresses different scale, latency, and complexity requirements.

Prerequisites

• Understanding of your data volume and sync frequency requirements
• Decision on unidirectional vs bidirectional data flow
• Knowledge of Salesforce edition (affects available features like CDC)

Variant A: Direct API Integration (Simple)

Best for: MVPs, < 50K records/day, single-direction sync

┌─────────────┐     jsforce       ┌─────────────┐
│   Your App  │ ──── REST API ──▶ │  Salesforce  │
│ (Node.js)   │ ◀── SOQL/SOSL ── │     Org      │
└─────────────┘                   └─────────────┘

Data flow:
- App queries SF via SOQL (polling or on-demand)
- App writes to SF via sObject CRUD
- Scheduled cron for periodic sync

Key Characteristics

• Single jsforce connection per process
• Polling-based reads (cron schedule)
• Direct REST writes
• In-memory or Redis caching for describe/metadata
• Suitable for: internal tools, admin dashboards, simple data sync

Code Pattern

// Cron-based sync — runs every 15 minutes
import cron from 'node-cron';

cron.schedule('*/15 * * * *', async () => {
  const conn = await getConnection();

  // Fetch recently modified accounts
  const accounts = await conn.query(`
    SELECT Id, Name, Industry, AnnualRevenue
    FROM Account
    WHERE LastModifiedDate >= ${fifteenMinutesAgo}
  `);

  // Sync to local database
  for (const account of accounts.records) {
    await localDb.upsert('accounts', mapFromSalesforce(account));
  }
});

Variant B: Event-Driven Integration (Scalable)

Best for: Real-time sync, 50K-5M records/day, bidirectional flow

┌─────────────┐                      ┌─────────────┐
│   Your App  │ ◀─── CDC Events ───  │  Salesforce  │
│  (listener) │   Change Data Capture │     Org      │
│             │                      │              │
│             │ ── Bulk API 2.0 ──▶  │              │
│             │    (write-back)      │              │
└──────┬──────┘                      └─────────────┘
       │
  ┌────▼────┐
  │  Queue  │  (Redis/SQS/Pub-Sub)
  │  (async │
  │  writes)│
  └─────────┘

Key Characteristics

• CDC for real-time change notifications (no polling waste)
• Bulk API 2.0 for high-volume writes
• Queue-based async processing for write-back
• ReplayId tracking for event resumption
• Suitable for: CRM sync, data warehouse ETL, real-time dashboards

Code Pattern

// Event-driven — near-real-time sync
import { getConnection } from './salesforce/connection';

const conn = await getConnection();

// Subscribe to Account changes via CDC
conn.streaming.topic('/data/AccountChangeEvent').subscribe(async (event) => {
  const { changeType, recordIds, changedFields } = event.payload.ChangeEventHeader;

  switch (changeType) {
    case 'CREATE':
      await localDb.insert('accounts', mapFromSalesforce(event.payload));
      break;
    case 'UPDATE':
      await localDb.update('accounts', recordIds[0], mapChangedFields(event.payload, changedFields));
      break;
    case 'DELETE':
      await localDb.delete('accounts', recordIds[0]);
      break;
  }
});

// Write-back via queue (async, decoupled)
queue.process('sync-to-salesforce', async (job) => {
  const conn = await getConnection();
  await conn.sobject(job.data.objectType).upsert(
    job.data.records,
    'External_ID__c'
  );
});

Required Salesforce Features

• Change Data Capture (Enterprise Edition+)
• Platform Events (all editions)
• Bulk API 2.0 (all editions with API access)

Variant C: Middleware/iPaaS Integration (Enterprise)

Best for: Multi-system integration, 5M+ records/day, complex transformations

┌─────────────┐                ┌─────────────┐               ┌─────────────┐
│   Your App  │ ── API ──────▶ │  Middleware  │ ── REST ────▶ │  Salesforce  │
│             │                │ (MuleSoft/   │               │     Org      │
│             │                │  Workato/    │ ◀─ CDC ──────│              │
│             │ ◀─ Webhooks ── │  Zapier)     │               │              │
└─────────────┘                └──────┬───────┘               └─────────────┘
                                      │
                                ┌─────▼──────┐
                                │  Other      │
                                │  Systems    │
                                │ (ERP, DW,   │
                                │  Marketing) │
                                └─────────────┘

Key Characteristics

• Middleware handles transformation, routing, error handling
• Pre-built Salesforce connectors (no custom code for basic sync)
• Visual flow builders for business users
• Enterprise monitoring and audit trails
• Suitable for: multi-system integration, complex business rules, compliance-heavy

iPaaS Options

Decision Matrix

Migration Path

Variant A (Direct API)
    │
    │  Growing data volume / need real-time sync
    ▼
Variant B (Event-Driven)
    │
    │  Multiple systems / compliance / no-code needed
    ▼
Variant C (Middleware/iPaaS)

Output

• Architecture variant selected based on requirements
• Integration pattern implemented
• Data flow documented
• Scaling path planned

Error Handling

Resources

• Salesforce Integration Patterns
• Change Data Capture
• MuleSoft Salesforce Connector
• Heroku Connect

Next Steps

For common anti-patterns, see salesforce-known-pitfalls.