attio-reference-architecture

# Attio Reference Architecture ## Overview Production architecture for CRM integrations with the Attio REST API (`https://api.attio.com/v2`). Designed for contact enrichment pipelines, deal tracking across custom lists, bi-directional activity sync with external systems, and workspace isolation for multi-tenant deployments. Key design drivers: webhook-driven data freshness, idempotent upserts via PUT assertions, schema-aware caching, and layered separation between API client, business logic, and infrastructure. ## Architecture Diagram ``` Your App ──→ Service Layer ──→ Cache (Redis) ──→ Attio REST API v2 ↓ /objects/people/records Queue (p-queue) ──→ Sync Worker /lists/{slug}/entries ↓ /notes, /tasks Webhook Handler ←── Attio Events /webhooks ↓ External CRM Sync ──→ HubSpot/Salesforce ``` ## Service Layer ```typescript class ContactService { constructor(private client: AttioClient, private cache: CacheLayer) {} async findByEmail(email: string): Promise<AttioRecord | null> { const res = await this.client.post('/objects/people/records/query', { filter: { email_addresses: email }, limit: 1 }); return res.data[0] || null; } async upsertPerson(data: { email: string; firstName: string; lastName: string }): Promise<AttioRecord> { const res = await this.client.put('/objects/people/records', { d...