Am Driver Laravel Package

Technical Evaluation

Architecture Fit

• Enhanced Callback Context: The addition of integrationInstanceId in callbacks (PR #11) improves traceability for multi-tenant or multi-integration scenarios. This aligns with SaaS architectures where:
  • Tenant isolation is critical (e.g., integrationInstanceId can map to a tenant workspace).
  • Debugging is simplified by correlating callbacks to specific AM integrations (e.g., captain-learning vs. captain-analytics).
• Orchestration Granularity: The change supports fine-grained command tracking, useful for:
  • Audit logging (e.g., CREATE_INSTANCE for tenant X triggered by integrationInstanceId: Y).
  • Idempotency keys (e.g., combining integrationInstanceId with command UUIDs to avoid duplicate processing).
• Hybrid Deployments: Useful for shared AM instances managing multiple products (e.g., integrationInstanceId distinguishes between productA and productB callbacks).

Integration Feasibility

• Minimal Breaking Change: The integrationInstanceId addition is backward-compatible (optional field in callbacks). Existing integrations do not require updates unless they rely on callback parsing.
• OpenAPI Impact: The OpenAPI spec likely includes this field in callback responses. Validate with:

  vendor/bin/openapi --validate spec/openapi.yaml
  

• CLI Tooling: The am-driver serve command may now log integrationInstanceId in simulated callbacks, aiding local testing.

Technical Risk

Key Questions for TPM

1. Callback Handling:

   • How will integrationInstanceId be used in custom handlers? Will it replace, extend, or complement existing tenant/workspace identifiers?
   • Are there SLA implications for processing callbacks with this new field? (e.g., slower parsing due to additional data.)

2. Tenant/Integration Mapping:

   • Is integrationInstanceId static per tenant or dynamic per command? Clarify with AM’s team to avoid misalignment.
   • How will this field interact with existing tenant isolation strategies (e.g., FileTenantWorkspace vs. database namespaces)?

3. Backward Compatibility:

   • Should legacy integrations (pre-v0.0.16) be deprecated or supported in parallel? Plan for a deprecation timeline if needed.
   • How will migration scripts handle callbacks missing integrationInstanceId? (e.g., default values, alerts.)

4. Observability:

   • Will integrationInstanceId be logged/monitored in production? If so, design filters to avoid cardinality explosions (e.g., high-cardinality metrics).
   • Should alerts be triggered for missing or malformed integrationInstanceId values?

5. Testing:

   • Update integration tests to include integrationInstanceId in callback assertions. Example:

     $this->assertEquals('tenant-123', $callback->getIntegrationInstanceId());
     

   • Test edge cases: null values, duplicate IDs, and cross-integration conflicts.

Integration Approach

Stack Fit

• Symfony/Laravel: No changes needed for existing integrations. The field is optional in callbacks.
• Custom Servers: If using the core library, ensure CallbackDto parsing handles integrationInstanceId. Example:

  $callback = new CallbackDto(
      $rawPayload['commandId'],
      $rawPayload['integrationInstanceId'] ?? null, // Handle optional field
      $rawPayload['state']
  );
  

• Microservices: The field adds context to CLI-driven orchestration (e.g., am-driver serve logs). Useful for multi-product AM instances.

Migration Path

1. Validation Phase (1 day):

   • Update OpenAPI validation to include integrationInstanceId in callback schemas.
   • Test with orchestration:simulate create --integration-instance-id=test-123.

2. Handler Updates (2 days):

   • Modify custom handlers to extract and log integrationInstanceId. Example:

     public function handle(CreateInstanceCommand $command, CallbackDto $callback): void {
         $this->logger->info('Processing command', [
             'integrationInstanceId' => $callback->getIntegrationInstanceId(),
             'commandId' => $command->getId(),
         ]);
     }
     

   • Add fallback logic for pre-v0.0.16 callbacks (if supporting legacy systems).

3. Observability (1 day):

   • Instrument metrics/logs to track integrationInstanceId distribution. Example Prometheus metric:

     # Metrics for callback processing by integrationInstanceId
     am_callbacks_processed_total{integration_instance_id="<ID>"} 1
     

Compatibility

Operational Impact

Maintenance

• Handler Updates: Minimal effort for new integrations; legacy systems may require backward-compatible parsing.
• Schema Management: Monitor AM’s OpenAPI spec for future callback changes. Use CI checks to validate schema compatibility.
• Logging: Expect increased log volume due to integrationInstanceId. Implement log sampling or retention policies for high-cardinality IDs.

Support

• Debugging: The field reduces ambiguity in callback logs (e.g., "Which tenant/product triggered this?"). Document its usage in runbooks.
• Onboarding: Update developer docs to highlight integrationInstanceId in callback examples. Example:

  ## Handling Callbacks
  ```php
  $callback = $this->amDriver->processCallback($rawPayload);
  $integrationId = $callback->getIntegrationInstanceId(); // New in v0.0.16
  

• Legacy Support: Plan for support queries on missing integrationInstanceId in callbacks. Provide migration guides for pre-v0.0.16 integrations.

Scaling

• Performance: Parsing integrationInstanceId adds negligible overhead (string extraction). No scaling impact expected.
• Database Backend: If using integrationInstanceId for tenant isolation, ensure the backend (e.g., Redis, DB) scales with ID cardinality.
• AM Load: High-volume callbacks with integrationInstanceId may increase AM’s payload size. Monitor AM’s throughput metrics.

Failure Modes