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