Atlantes Integration

Atlantes adapter for the Marchay Integration Gateway. Atlantes is a consumer that connects to Salesforce through the Gateway's connector abstraction.

LOE: ~28-42 hours (~1 week)

---

Epic: Salesforce Schema Configuration

Plan: Create Salesforce custom objects and fields to support the integration. This is a blocker for endpoint testing.

Architectural Context: The connector uses External ID pattern for server-side UUID generation. Custom fields must be created before endpoints can be fully tested. Field-level security and page layouts need configuration.

Tasks

• [ ] Create External_Id__c field on Contact object
• [ ] Create Quote__c custom object with all fields
• [ ] Create Booking__c custom object with all fields
• [ ] Configure field-level security and page layouts
• [ ] Set up validation rules

---

Epic: Connector Error Handling

Plan: Implement error handling within the Salesforce connector, leveraging the Gateway's error categorization and resilience patterns.

Architectural Context: The Gateway provides error categorization (Transient, Permanent, Quota), bounded retries, idempotency keys, and circuit breakers. The Salesforce connector maps Salesforce-specific errors to these categories and implements retry logic for transient failures.

Tasks

• [ ] Map Salesforce errors to Gateway error categories
• [ ] Implement retry logic for transient Salesforce failures
• [ ] Add input validation for Salesforce API calls
• [ ] Build circuit breaker integration for Salesforce API limits
• [ ] Implement idempotency for write operations

---

Epic: Webhook Integration

Plan: Implement inbound webhook verification and outbound webhook delivery for real-time sync with Salesforce through the Gateway's webhook infrastructure.

Architectural Context: The Gateway handles webhook termination, signature verification, deduplication, and async processing. The Salesforce connector implements vendor-specific webhook handling (Platform Events, Change Data Capture).

Tasks

• [ ] Implement Salesforce webhook signature verification
• [ ] Build inbound webhook processing for member events
• [ ] Implement outbound webhook delivery via Platform Events
• [ ] Add webhook retry logic
• [ ] Build webhook event logging

---

Epic: Connector Testing

Plan: Write unit and integration tests for the Salesforce connector, validating authentication, API operations, and error scenarios.

Architectural Context: Tests follow the Gateway's testing patterns. Integration tests validate Salesforce connectivity in sandbox environments. Unit tests cover connector-specific logic.

Tasks

• [ ] Write unit tests for Salesforce connector
• [ ] Write integration tests for Salesforce connectivity
• [ ] Test JWT authentication flows
• [ ] Test error scenarios and edge cases
• [ ] Load testing for Salesforce API throughput

---

Epic: Connector Production Readiness

Plan: Prepare the Salesforce connector for production deployment, following the Gateway's deployment and operations patterns.

Architectural Context: The connector deploys as part of the Gateway service. Production readiness includes credential management, monitoring, and rate limiting specific to Salesforce.

Tasks

• [ ] Move JWT private key to Doppler
• [ ] Implement per-environment credentials (dev, staging, prod)
• [ ] Configure Salesforce-specific rate limiting
• [ ] Add Salesforce API usage monitoring
• [ ] Build Salesforce-specific alerting

---

Epic: Consumer Documentation

Plan: Document the Salesforce connector API for consumers like Atlantes, including authentication, endpoints, and error handling.

Architectural Context: Documentation follows the Gateway's OpenAPI standards. Consumers need clear guidance on how to use the connector through the Gateway.

Tasks

• [ ] Document Salesforce connector endpoints
• [ ] Create consumer authentication guide
• [ ] Document error codes and handling
• [ ] Build example requests and responses