Integration Architecture — Overview

Our integration layer is a single, versioned API Gateway that protects and aggregates our resources (Salesforce, databases, partner accounts, payment providers) behind one contract. Consumers (Atlantes today, others tomorrow) talk only to the gateway. Our resources live behind it.

The gateway is the boundary we own. It enforces auth, rate limits, retries, circuit breakers, and observability in one place. It is the air gap between consumers and our vendor relationships.

What This Is

• A single versioned REST API for all consumers
• Auth, rate limiting, retries, circuit breakers enforced at the boundary
• Connector-based resource integration (Salesforce, partners, databases)
• Uniform error contract and idempotency for all writes
• Full observability — every call traced, logged, and metered

What This Is Not

• Not a data layer or business intelligence produce (that's the Intelligence Layer)
• Not a business logic layer — the gateway routes and protects, it doesn't decide
• Not a consumer SDK — consumers get a contract, not our implementation
• Not a vendor abstraction — we own the vendor relationship, not hide it

Architecture

Consumers — Talk only to the gateway. They never see our vendor credentials, SDKs, or internal implementations.

API Gateway — The single boundary we own. Enforces auth, rate limits, retries, circuit breakers, and observability. Routes to the right connector.

Resources — Our vendor relationships and data stores. Hidden behind the gateway. Swappable without consumer impact.

Key Concepts

• The gateway is our service, running in our infrastructure, enforcing our policy.
• Our resources are hidden behind the gateway. Consumers see the contract, not the implementation.
• One contract for consumers — vendor swaps and backend changes don't ripple.
• Idempotency is required for all writes.
• Secrets stay on our side — vendor credentials never reach consumer processes.

Chapters

1. Design Principles — non-negotiable rules for the boundary
2. API Gateway — the air gap: responsibilities, internals, why we own it
3. Authentication — consumer→gateway and gateway→resource auth
4. API Surface — versioned REST contract, conventions, OpenAPI
5. Error Handling & Retries — error contract, retry policy, circuit breakers
6. Webhooks — inbound from resources, outbound to consumers
7. Rate Limiting & Quotas — per-consumer and per-resource limits
8. Observability — tracing, logging, metrics, alerts
9. Security — threat model, secrets, PII, input validation
10. Deployment — container layout, CI/CD, configuration