Attio Integration Reference Architecture

Overview

This skill produces a repo-grounded architecture for reliable Attio reads, writes, and events. It treats tenant isolation, duplicate delivery, schema evolution, and reconciliation as first-class controls.

Prerequisites

• Workspace and tenancy model
• Required objects, lists, attributes, records, entries, and events
• Availability, freshness, recovery, and retention objectives
• Owners for credentials, queues, data mapping, and incident response

Tool Discipline

Use Read, Glob, and Grep to map components, trust boundaries, state, and existing clients. Use WebFetch only for current official Attio contracts. Use Write or Edit after the architecture, ownership, and approval boundaries are agreed.

Current Contract

• Use OAuth for multi-workspace applications and a workspace key only for a controlled single-workspace integration.
• Discover object and attribute identifiers rather than hard-coding display labels.
• Pagination differs by endpoint, and record or entry queries can carry score-based rate cost.
• Webhooks are at-least-once signals; durable processing needs signature verification, idempotency, a queue, and reconciliation.

Authentication

Place a tenant credential resolver behind a server-side interface. Bind each encrypted token to one workspace identity and exact scopes; never accept a workspace identifier from a caller without authorization.

Instructions

1. Map ingress, egress, data stores, trust boundaries, tenant context, and failure domains from the repository.
2. Define a credential resolver and auditable endpoint-to-scope map.
3. Add a bounded schema registry or cache with explicit refresh and invalidation.
4. Route outbound mutations through idempotent jobs with separate read and write governors.
5. Terminate webhooks at an HTTPS receiver that verifies the raw body, deduplicates by idempotency key, acknowledges quickly, and queues work.
6. Add replay, dead-letter handling, periodic reconciliation, and operator-visible lag metrics.
7. Specify deployment order, canary cohort, rollback, recovery exercise, and component owners.

Approval Boundaries

Do not broaden data collection, scopes, retention, tenant access, or mutation authority without approval from the relevant data and service owners.

Output

Return a component-and-data-flow design, trust boundaries, endpoint contracts, failure controls, ownership matrix, rollout sequence, and rollback plan.

Error Handling

Condition	Response
Tenant cannot be resolved safely	Reject the operation before credential lookup.
Schema cache is stale	Refresh discovery and pause incompatible writes.
Webhook queue is unavailable	Fail closed so Attio can retry; preserve observability.
Reconciliation finds drift	Quarantine conflicting mutations and assign an owner.

Examples

Input:

tenancy=multi-workspace; flows=record sync and webhooks; recovery=required

Expected handoff:

auth=oauth resolver; writes=queued; webhooks=verified; reconciliation=scheduled

Resources

• Skill-specific official documentation
• REST API overview
• Objects and lists
• Webhooks