Design Principles

The gateway is the boundary we own around our resources. These principles are non-negotiable.

1. We Own the Boundary

The gateway is our service, running in our infrastructure, enforcing our policy. Consumers — Atlantes today, others tomorrow — cross this boundary on our terms.

2. Our Resources Are Hidden

Consumers never see our Salesforce org, our database credentials, our partner account details, or our vendor SDKs. They see our contract. The implementation behind it is ours to change.

3. One Contract for Consumers

Consumers see a single, versioned API. We can swap, replace, or remove the underlying vendors without any consumer change. Salesforce today, something else tomorrow — the consumer contract is stable.

4. Server-to-Server Only

No consumer requires human interaction. JWT Bearer (or equivalent) for outbound to our vendors; API key or mTLS for inbound from consumers. The same pattern applies to every connection across the boundary.

5. Idempotency by Default

Every write accepts an idempotency key. Retries are safe. This protects our resources from accidental duplicate writes.

6. Uniform Error Shape

Every endpoint, every vendor, every consumer sees the same error contract:

{
  "error": {
    "code": "string",
    "message": "string",
    "retryable": true,
    "vendor_code": "string",
    "request_id": "uuid"
  }
}

7. Bounded Retries, No Infinite Loops

Retries are bounded by attempt count, total elapsed time, and a circuit breaker. A flaky vendor cannot cascade into damage to our resources or our reputation.

8. Observability Is Not Optional

Every call through the gateway is traced, logged, and metered. We own this — it's how we know what's happening at our boundary.

9. Vendor Limits Are First-Class

Salesforce governor limits, partner API quotas, payment provider rate limits — all tracked and budgeted inside the gateway. We protect our quotas because they're our resources.

10. Secrets Stay on Our Side

Vendor credentials, database passwords, partner secrets — all live in Doppler. Consumers never see them. Consumers only see their own API key.

11. Webhooks Flow Through the Gateway

Inbound webhooks from our vendors terminate at the gateway. Outbound webhooks to consumers originate from the gateway. The boundary is ours; webhooks respect it.