matrix-config.yaml

// shared-kernel/types.ts
export interface ProductVariant {
  id: string;
  name: string;
  features: FeatureSet;
  strategies: StrategyMap;
  constraints: ConstraintSet;
}

export type FeatureSet = Record<string, boolean>;
export type StrategyMap = Record<string, StrategyConstructor>;
export type ConstraintSet = { maxUsers: number; dataRetentionDays: number };

export interface StrategyConstructor {
  new (...args: any[]): Strategy;
}

export interface Strategy {
  execute(context: ExecutionContext): Promise<void>;
}

export interface ExecutionContext {
  variant: ProductVariant;
  tenantId: string;
  payload: any;
}

// matrix/resolver.ts
import { ProductVariant, StrategyMap } from './types';

export class VariantResolver {
  private variants: Map<string, ProductVariant>;

  constructor(variantConfigs: ProductVariant[]) {
    this.variants = new Map(variantConfigs.map(v => [v.id, v]));
  }

  resolve(variantId: string): ProductVariant {
    const variant = this.variants.get(variantId);
    if (!variant) {
      throw new Error(`Variant ${variantId} not found in matrix`);
    }
    return variant;
  }

  // Merge base config with delta overrides for composable variants
  resolveComposite(baseId: string, deltaId: string): ProductVariant {
    const base = this.resolve(baseId);
    const delta = this.resolve(deltaId);

    return {
      ...base,
      id: `${baseId}-${deltaId}`,
      features: { ...base.features, ...delta.features },
      strategies: { ...base.strategies, ...delta.strategies },
      constraints: { ...base.constraints, ...delta.constraints },
    };
  }
}

// matrix/strategy-injector.ts
import { Strategy, ExecutionContext, ProductVariant } from './types';

export class StrategyInjector {
  private container: Map<string, any> = new Map();

  register<T extends Strategy>(name: string, instance: T): void {
    this.container.set(name, instance);
  }

  getStrategy<T extends Strategy>(
    name: string, 
    variant: ProductVariant
  ): T {
    // Check variant-specific override first
    const overri

de = variant.strategies[name]; if (override) { // Instantiate or retrieve cached instance return this.container.get(name) || new override(); }

// Fallback to default registered strategy
const defaultStrategy = this.container.get(name);
if (!defaultStrategy) {
  throw new Error(`No strategy registered for ${name} and no override in variant ${variant.id}`);
}
return defaultStrategy;

} }

#### Usage in Domain Logic

Domain services remain agnostic of the matrix. They request strategies by intent.

```typescript
// domain/billing-service.ts
import { StrategyInjector, ExecutionContext } from './matrix/strategy-injector';
import { ProductVariant } from './shared-kernel/types';

export class BillingService {
  constructor(private injector: StrategyInjector) {}

  async generateInvoice(context: ExecutionContext): Promise<any> {
    // The service does not know about variants. 
    // It asks for a "TaxCalculator" strategy.
    const taxStrategy = this.injector.getStrategy('TaxCalculator', context.variant);
    
    const taxAmount = await taxStrategy.execute(context);
    
    return {
      subtotal: context.payload.amount,
      tax: taxAmount,
      total: context.payload.amount + taxAmount,
    };
  }
}

Variant Configuration Example

Variants are defined declaratively. This allows non-engineers to configure product behavior if the strategy interface is stable.

// config/variants.ts
import { ProductVariant } from './shared-kernel/types';
import { EuTaxStrategy } from './strategies/eu-tax';
import { UsTaxStrategy } from './strategies/us-tax';
import { EnterpriseRetentionStrategy } from './strategies/retention';

export const variants: ProductVariant[] = [
  {
    id: 'base-saas',
    name: 'Base SaaS',
    features: { analytics: true, export: false },
    strategies: { TaxCalculator: UsTaxStrategy },
    constraints: { maxUsers: 100, dataRetentionDays: 30 },
  },
  {
    id: 'eu-variant',
    name: 'EU Compliance',
    features: { analytics: true, gdpr: true },
    strategies: { TaxCalculator: EuTaxStrategy },
    constraints: { maxUsers: 500, dataRetentionDays: 90 },
  },
  {
    id: 'enterprise-variant',
    name: 'Enterprise',
    features: { analytics: true, sso: true, export: true },
    strategies: { DataRetention: EnterpriseRetentionStrategy },
    constraints: { maxUsers: -1, dataRetentionDays: 365 },
  },
];

3. Build Matrix for Asset Generation

For frontend assets or compiled binaries, use a build matrix approach. This generates distinct bundles without runtime overhead.

// matrix.config.json
{
  "variants": ["base", "eu", "enterprise"],
  "builds": {
    "base": { "env": "production", "assets": ["core.js"] },
    "eu": { "env": "production", "assets": ["core.js", "gdpr-bundle.js"] },
    "enterprise": { "env": "production", "assets": ["core.js", "sso-module.js"] }
  }
}

A CI script iterates this configuration, injecting environment variables and generating artifacts. This ensures zero runtime cost for variant resolution in performance-critical paths.

Pitfall Guide

1. Leaky Abstractions in the Shared Kernel

Mistake: Adding variant-specific fields to shared domain models. Consequence: The kernel becomes coupled to variants. Changes in one variant require updates to the kernel, breaking isolation. Best Practice: Enforce strict dependency rules. The Shared Kernel cannot import from Variant layers. Use extension patterns or separate data stores for variant-specific attributes. If a field is only used by one variant, it belongs in a variant-specific model, not the shared model.

2. Combinatorial Explosion in Testing

Mistake: Attempting to test every combination of features and variants exhaustively. Consequence: Test suites become unmanageable; CI times increase exponentially. Best Practice: Implement matrix-aware testing. Test the Shared Kernel independently. Test each variant's strategies in isolation using mocks of the kernel. Use property-based testing for variant configurations. Focus integration tests on critical paths and contract boundaries.

3. Configuration Overload

Mistake: Managing variant logic via massive YAML/JSON files with nested conditions. Consequence: Configuration becomes unmaintainable; "YAML hell" replaces code spaghetti. Best Practice: Keep configuration declarative and flat. Use code to define complex logic via strategies. Configuration should toggle features and select strategies, not contain business logic. Validate configuration schemas rigorously at build time.

4. Ignoring Data Isolation Requirements

Mistake: Using a single database schema for all variants without considering regulatory or performance isolation. Consequence: Data leakage risks, noisy neighbor problems, or inability to comply with data residency laws. Best Practice: Design the data layer to support isolation modes. Use Row-Level Security (RLS) for logical isolation. Support sharding or separate schemas for high-compliance variants. The Variant Resolver should inform the data access layer of the isolation requirements.

5. Over-Engineering the Matrix

Mistake: Implementing a full Product Matrix for a portfolio of only two similar products. Consequence: Unnecessary complexity; development velocity decreases due to architectural overhead. Best Practice: Apply the matrix pattern when supporting three or more distinct variants, or when variants require divergent lifecycles. For simple feature flags, use standard flagging tools. The matrix is justified by structural diversity, not just toggle requirements.

6. Deployment Coupling

Mistake: Deploying all variants together in a single release, causing a failure in one variant to block others. Consequence: Reduced deployment frequency; risk aversion increases. Best Practice: Decouple deployments. Even within a monorepo, use targeted deployments. If using the build matrix, variants should be deployable independently. Ensure the Shared Kernel is versioned and backward-compatible so variants can update at different cadences.

7. Strategy Bloat

Mistake: Creating a new strategy class for every minor variant difference. Consequence: Class explosion; hard to navigate codebase. Best Practice: Group related variations. Use parameterized strategies where appropriate. A PricingStrategy might accept a configuration object rather than having EnterprisePricingStrategy, SmbPricingStrategy, etc. Reserve distinct classes for fundamentally different algorithms.

Production Bundle

Action Checklist

• Audit Codebase: Identify all if/switch statements related to product types or tenants. Map these to potential strategies.
• Define Shared Kernel: Extract invariant domain models and core algorithms into a dedicated module with strict import rules.
• Implement Variant Resolver: Create a resolver service that maps context to variant configurations. Integrate with your identity/tenant provider.
• Refactor to Strategies: Replace conditional logic with strategy interfaces. Register default implementations and variant overrides.
• Establish Build Matrix: Configure CI/CD to generate artifacts or run tests per variant. Implement matrix-aware test execution.
• Set Up Contract Tests: Create tests that verify the Shared Kernel contract remains stable across variant updates.
• Monitor Variant Metrics: Instrument the resolver to track variant usage, error rates, and performance. Set alerts for variant-specific anomalies.
• Document Matrix Topology: Maintain a living document of variant configurations, dependencies, and strategy mappings.

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
High Regulatory Isolation	Microservices per Variant	Compliance requires physical data separation and independent audit trails.	High (Infra + DevOps)
Rapid Market Testing	Product Matrix	Enables spin-up of new variants in days using shared core. Low risk.	Low (Dev Efficiency)
Shared Data Analytics	Product Matrix	Centralized data schema allows cross-variant analytics without ETL complexity.	Medium (Storage)
Distinct Tech Stacks	Polyglot Microservices	Variants require different languages or frameworks for performance reasons.	High (Complexity)
Single Product Focus	Standard Monolith	Matrix overhead is unjustified for a single product line.	Low
Multi-Tenant SaaS	Product Matrix + RLS	Matrix manages feature sets; RLS manages data isolation per tenant.	Low/Medium

Configuration Template

Use this schema to define your product matrix. Store this in version control for auditability.

# matrix-config.yaml
version: "1.0"
shared_kernel:
  version: "2.4.1"
  contracts:
    - "BillingContract"
    - "IdentityContract"

variants:
  - id: "pro-starter"
    name: "Pro Starter"
    parent: "base"
    features:
      analytics: true
      api_access: false
    strategies:
      PricingStrategy: "StandardPricing"
      SupportStrategy: "CommunitySupport"
    constraints:
      max_seats: 10
      storage_gb: 50
    deployment:
      target: "shared-cluster"
      priority: "low"

  - id: "enterprise-finance"
    name: "Enterprise Finance"
    parent: "base"
    features:
      analytics: true
      api_access: true
      sso: true
      audit_logs: true
    strategies:
      PricingStrategy: "EnterprisePricing"
      SupportStrategy: "DedicatedSupport"
      DataRetentionStrategy: "FinanceComplianceRetention"
    constraints:
      max_seats: -1
      storage_gb: -1
      data_residency: "US-EAST-1"
    deployment:
      target: "dedicated-cluster"
      priority: "high"
      isolation: "strict"

Quick Start Guide

1. Initialize Matrix Module: Create a matrix directory. Define types.ts with interfaces for ProductVariant, Strategy, and ExecutionContext.

2. Create Resolver: Implement VariantResolver class. Load variants from a JSON file or environment config. Add a resolve(context) method.

3. Define First Strategy: Create a PaymentStrategy interface. Implement DefaultPaymentStrategy. Register it in your dependency injection container.

4. Integrate Resolver: In your entry point (API route or CLI command), extract tenant/variant ID from the request. Call resolver.resolve(id). Inject the variant into the execution context.

5. Run Matrix Test: Write a test that instantiates two variants. Execute a flow with each. Assert that DefaultPaymentStrategy is used for Variant A and an overridden strategy is used for Variant B. Verify shared kernel behavior remains consistent.

Deploy the resolver and strategies. Configure your CI to run the test suite against all defined variants. You now have a scalable foundation for product portfolio diversification.