Cross-product integration

import { z } from 'zod';

// Base Asset Interface shared across products
export const DigitalAssetSchema = z.object({
  assetId: z.string().uuid(),
  assetType: z.enum(['USER_PROFILE', 'MEDIA', 'TRANSACTION']),
  version: z.number().int().min(1),
  metadata: z.record(z.string(), z.unknown()),
  ownership: z.object({
    primaryOwner: z.string(),
    readOnlyAccess: z.array(z.string()),
  }),
  updatedAt: z.string().datetime(),
});

export type DigitalAsset = z.infer<typeof DigitalAssetSchema>;

// Integration Event Schema
export const AssetMutationEventSchema = z.object({
  eventId: z.string().uuid(),
  eventType: z.enum(['CREATED', 'UPDATED', 'DELETED']),
  asset: DigitalAssetSchema,
  traceId: z.string(),
  timestamp: z.string().datetime(),
});

export type AssetMutationEvent = z.infer<typeof AssetMutationEventSchema>;

import { EventRouter } from '@codcompass/matrix-router';
import { AssetMutationEvent } from './contracts';

export class AssetMatrixRouter {
  private router: Event

Router<AssetMutationEvent>;

constructor(config: RouterConfig) { this.router = new EventRouter(config); this.router.registerValidator(AssetMutationEventSchema); this.router.registerAuthzPolicy(this.checkOwnershipPolicy); }

// Core mutation handler async dispatchMutation(event: AssetMutationEvent): Promise<void> { // 1. Validate contract const parsed = AssetMutationEventSchema.safeParse(event); if (!parsed.success) { throw new ContractViolationError(parsed.error); }

// 2. Check ownership matrix
const isAuthorized = await this.checkOwnershipPolicy(event);
if (!isAuthorized) {
  throw new AuthorizationError('Caller lacks mutation rights');
}

// 3. Dispatch to matrix
await this.router.publish(event);

}

private async checkOwnershipPolicy(event: AssetMutationEvent): Promise<boolean> { const { asset, callerId } = event; const { primaryOwner, readOnlyAccess } = asset.ownership;

return primaryOwner === callerId || readOnlyAccess.includes(callerId);

} }

#### Step 3: Consumer Integration with Idempotency

Products consuming asset mutations must implement idempotency to handle duplicate events caused by retries or network partitions. Use an idempotency key derived from the event ID.

```typescript
import { IdempotencyStore } from '@codcompass/idempotency';

export class AssetConsumer {
  constructor(
    private store: IdempotencyStore,
    private assetService: AssetService
  ) {}

  async handleEvent(event: AssetMutationEvent): Promise<void> {
    // Check idempotency
    const isProcessed = await this.store.check(event.eventId);
    if (isProcessed) {
      return; // Idempotent return
    }

    try {
      // Apply mutation based on type
      switch (event.eventType) {
        case 'CREATED':
          await this.assetService.create(event.asset);
          break;
        case 'UPDATED':
          await this.assetService.update(event.asset);
          break;
        case 'DELETED':
          await this.assetService.delete(event.asset.assetId);
          break;
      }

      // Mark as processed
      await this.store.mark(event.eventId);
    } catch (error) {
      // Do not mark as processed; allow retry
      throw error;
    }
  }
}

Step 4: Observability and Circuit Breaking

Integrate distributed tracing and circuit breakers. The matrix topology must detect failures in downstream products and degrade gracefully.

import { CircuitBreaker } from '@codcompass/circuit-breaker';

const breaker = new CircuitBreaker({
  threshold: 5,
  timeout: 10000,
  resetTimeout: 30000,
});

async function safeDispatch(event: AssetMutationEvent) {
  return breaker.execute(async () => {
    await assetMatrixRouter.dispatchMutation(event);
  });
}

Pitfall Guide

1. Leaky Abstractions via Internal Schemas Mistake: Exposing internal database schemas or ORM models directly in integration contracts. Explanation: Internal schemas change frequently. Exposing them couples consumers to implementation details. Best Practice: Define integration contracts explicitly. Map internal models to contract models in the producer. Use DTOs (Data Transfer Objects) that reflect the integration boundary, not the storage layer.

2. Synchronous Blocking Chains Mistake: Using synchronous HTTP requests for cross-product updates that require multiple product acknowledgments. Explanation: This creates a distributed transaction that blocks the caller and increases latency. A failure in any downstream product causes the entire chain to fail. Best Practice: Use asynchronous event publishing. Products acknowledge receipt via event consumption. Use sagas or compensating transactions for multi-step workflows requiring consistency.

3. Ignoring Schema Versioning Mistake: Breaking changes to contracts without versioning or backward compatibility. Explanation: Producers update contracts; consumers break. This causes runtime errors and data loss. Best Practice: Implement semantic versioning for contracts. Support multiple versions during transition periods. Use contract testing to validate compatibility before deployment.

4. Missing Idempotency Guarantees Mistake: Assuming "exactly-once" delivery from the transport layer. Explanation: Distributed systems cannot guarantee exactly-once delivery. Retries and duplicates are inevitable. Best Practice: Design consumers to be idempotent. Use unique event IDs and idempotency stores to deduplicate processing. Ensure state transitions are deterministic.

5. Authorization Leakage Across Matrix Mistake: Failing to re-evaluate authorization at the consumer level. Explanation: Product A may have permission to read an asset, but Product B should not. Trusting the source product's authorization is a security risk. Best Practice: Enforce authorization at every integration boundary. Validate ownership and access rights in the Matrix Router and at the consumer. Use zero-trust principles for cross-product communication.

6. The "Golden Path" Integration Bias Mistake: Testing integration only with valid data and happy paths. Explanation: Real-world integration involves malformed data, network timeouts, and partial failures. Best Practice: Implement chaos engineering for integration. Test with invalid payloads, simulate latency spikes, and verify error handling. Use property-based testing to generate edge cases.

7. Coupling Event Payloads to Business Logic Mistake: Embedding business logic decisions inside event payloads. Explanation: Events should represent state changes, not commands. Payloads should contain sufficient context for consumers to make decisions. Best Practice: Keep events descriptive. Include metadata and context. Let consumers determine how to react based on their local business logic. Avoid "smart events" that dictate consumer behavior.

Production Bundle

Action Checklist

• Define Asset Schema: Create versioned contracts for all digital assets using a schema-first tool.
• Map Ownership Matrix: Document ownership, read/write rights, and access levels for each asset type across products.
• Implement Contract Tests: Automate validation of producer-consumer compatibility in CI/CD pipelines.
• Add Idempotency: Integrate idempotency stores in all consumers to handle duplicate events safely.
• Configure Circuit Breakers: Deploy circuit breakers on all cross-product calls to prevent cascading failures.
• Enable Distributed Tracing: Propagate trace IDs across all integration events for end-to-end observability.
• Define Rollback Strategy: Establish procedures for rolling back contract changes and reverting integration states.
• Audit Authorization: Review and test authorization policies at every integration boundary.

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
High Volume Asset Updates	Event-Driven Matrix	Decouples products, handles scale, allows replay.	Moderate upfront, low long-term.
Low Volume, Strong Consistency	Synchronous API with 2PC	Simpler implementation, immediate consistency.	Low upfront, high risk of coupling.
Legacy Product Integration	Anti-Corruption Layer	Isolates legacy schema, protects core matrix.	High upfront, preserves stability.
Multi-Tenant Asset Matrix	Tenant-Aware Router	Enforces tenant isolation, scales per tenant.	Moderate upfront, operational overhead.

Configuration Template

matrix.config.ts

import { MatrixConfig } from '@codcompass/matrix-core';

export const matrixConfig: MatrixConfig = {
  router: {
    transport: 'kafka',
    brokers: ['kafka-1:9092', 'kafka-2:9092'],
    topicPrefix: 'asset-matrix',
    consumerGroup: 'matrix-consumer',
  },
  contracts: {
    version: '1.2.0',
    validation: 'strict',
    schemaRegistry: 'https://schema-registry.internal',
  },
  authz: {
    policyEngine: 'opa',
    policyPath: '/policies/asset-matrix.rego',
    cacheTTL: 300,
  },
  observability: {
    tracing: 'otel',
    metrics: 'prometheus',
    logLevel: 'info',
  },
  resilience: {
    circuitBreaker: {
      enabled: true,
      threshold: 5,
      resetTimeout: 30000,
    },
    retry: {
      maxAttempts: 3,
      backoff: 'exponential',
    },
  },
};

Quick Start Guide

1. Install SDK: Run npm install @codcompass/matrix-sdk in your product repository.
2. Generate Client: Execute npx matrix generate --config matrix.config.ts to create type-safe client stubs.
3. Run Mock Server: Start the local matrix router using npx matrix mock --port 8080 for development testing.
4. Integrate Handler: Implement the AssetConsumer class in your product using the generated client.
5. Verify Integration: Run npx matrix test --suite integration to validate contract compliance and event handling.

Cross-product integration in a digital asset matrix demands rigorous contract management, matrix-aware topology, and defensive engineering. By adopting a contract-first approach, enforcing idempotency, and leveraging event-driven patterns, teams can build scalable, resilient integrations that support independent product evolution while maintaining a coherent asset ecosystem.