intercom-reference-architecture

name	intercom-reference-architecture
description	Implement Intercom reference architecture with layered project structure. Use when designing new Intercom integrations, reviewing project structure, or establishing architecture standards for Intercom applications. Trigger with phrases like "intercom architecture", "intercom project structure", "how to organize intercom", "intercom layout", "intercom design patterns".
allowed-tools	Read, Grep
version	1.6.0
license	MIT
author	Jeremy Longshore <[e-mail]>
tags	["saas","support","messaging","intercom"]
compatibility	Designed for Claude Code

Intercom Reference Architecture

Overview

A production-ready reference architecture for Intercom integrations built on four layers — API/webhook, service, Intercom client, and infrastructure — with type-safe SDK usage, webhook processing, contact sync, and Help Center management. Use it to scaffold a new integration or to review an existing one against a known-good structure.

The layers (top to bottom): the API / Webhook layer (Express routes, webhook endpoints) calls into the service layer (contacts, conversations, articles — business logic and orchestration), which calls the Intercom client layer (a singleton intercom-client SDK wrapper with typed errors, caching, and rate limit handling), all resting on infrastructure (Redis cache, job queue, monitoring). Keeping dependencies flowing strictly downward is what prevents the circular imports and test-isolation problems listed under Error Handling.

Prerequisites

• Node.js project with TypeScript and the intercom-client npm package installed.
• An Intercom access token — the SDK authenticates every request with a Bearer token read from the INTERCOM_ACCESS_TOKEN environment variable (see Step 1). Create one under Intercom → Developer Hub → your app → Authentication. Never commit it; load it from the environment.
• For webhook verification, your app's client secret to validate the X-Hub-Signature header on inbound webhook POSTs.
• Redis (optional) if you enable the caching layer.

Instructions

Use Read/Grep to inspect the current project layout, then build each layer in order — the client layer is the dependency root for every service.

1. Client layer (src/intercom/client.ts) — a lazy singleton getClient() that reads INTERCOM_ACCESS_TOKEN once, plus an IntercomServiceError that wraps raw SDK errors into a typed, retry-aware shape. Skeleton:

   let instance: IntercomClient | null = null;
   export function getClient():  {
      (!instance) {
        token = process..;
        (!token)   ();
       instance =  ({ token });
     }
      instance;
   }