1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

// EXAMPLE: E-commerce Product Catalog
 
// Traffic Analysis (per second, peak):
// - Product page views:       50,000 reads/sec
// - Search queries:           10,000 reads/sec
// - Add to cart:                 500 writes/sec
// - Complete purchase:            50 writes/sec
// - Update product info:           5 writes/sec
 
// READ:WRITE RATIO = 60,000:555 ≈ 108:1
 
// Without CQRS:
// - Single PostgreSQL database handles everything
// - Product table: normalized, indexed for updates
// - Every page view: JOINs across products, inventory, pricing, reviews
// - To handle 60K reads: massive vertical scaling, expensive read replicas
 
// With CQRS:
// - Write side: PostgreSQL for transactional product updates
// - Read side 1: Elasticsearch for search (10K queries/sec easily)
// - Read side 2: Redis for product pages (50K+ reads/sec from cache)
// - Read side 3: ClickHouse for analytics (aggregations without affecting reads)
 
// COST ANALYSIS
// Without CQRS: 8x db.r6g.4xlarge (128GB) = ~$28,000/month
// With CQRS: 
//   - 2x db.r6g.large (write) = ~$500/month
//   - 3x Elasticsearch nodes = ~$2,000/month
//   - Redis cluster = ~$800/month
//   - Total = ~$3,300/month (88% cost reduction!)
 
// The asymmetry JUSTIFIES the complexity.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77

// EXAMPLE: Insurance Policy System
 
// WRITE SIDE: Extremely complex domain logic
class InsurancePolicy {
    // Complex state machine with dozens of states
    private lifecycleState: PolicyLifecycleState;
    
    // Intricate premium calculation with many factors
    private premiumCalculation: PremiumCalculation;
    
    // Rider attachments with interdependencies
    private riders: PolicyRider[];
    
    // Claims history affecting future terms
    private claimsHistory: Claim[];
    
    // Regulatory compliance requirements
    private complianceStatus: ComplianceCheck[];
 
    // Business rules spanning hundreds of conditions
    adjustCoverage(adjustment: CoverageAdjustment): void {
        // Check state allows adjustment
        this.ensureState(PolicyLifecycleState.ACTIVE);
        
        // Validate adjustment against policy limits
        this.validateAdjustmentLimits(adjustment);
        
        // Check rider compatibility
        this.validateRiderCompatibility(adjustment);
        
        // Recalculate premium (complex actuarial logic)
        this.premiumCalculation = this.calculateNewPremium(adjustment);
        
        // Update compliance status
        this.revalidateCompliance();
        
        // Underwriting review required for major changes
        if (adjustment.significanceLevel > SignificanceLevel.MINOR) {
            this.requireUnderwritingReview();
        }
        
        // Generate events for downstream systems
        this.addEvents([
            new CoverageAdjustedEvent(this.id, adjustment),
            new PremiumRecalculatedEvent(this.id, this.premiumCalculation),
            // ... potentially many more
        ]);
    }
    
    // ... hundreds of complex methods
}
 
// READ SIDE: Simple, flat views for UI
interface PolicySummaryDto {
    policyNumber: string;
    holderName: string;
    policyType: string;           // "Whole Life - Gold"
    status: string;               // "Active"
    monthlyPremium: string;       // "$247.50"
    coverageAmount: string;       // "$500,000"
    renewalDate: string;          // "Jan 15, 2025"
    // That's it! None of the domain complexity exposed.
}
 
interface PolicyDetailDto {
    policyNumber: string;
    holderName: string;
    // Clean, displayable data
    coverages: Array<{ name: string; amount: string }>;
    riders: Array<{ name: string; cost: string }>;
    premiumBreakdown: Array<{ component: string; amount: string }>;
    documents: Array<{ name: string; downloadUrl: string }>;
    // UI doesn't need to understand the domain model
}
 
// The read model hides the domain complexity from the UI
// UI developers don't need to understand actuarial calculations

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

// EXAMPLE: Internal Employee Directory
 
// Characteristics:
// - 500 employees in the company
// - 50 updates per day (new hires, departures, info changes)
// - 200 lookups per day
// - READ:WRITE ratio ≈ 4:1 (NOT extreme)
// - Simple validation (email format, required fields)
// - Strong consistency needed (can't show departed employees)
 
// Traditional approach (SUFFICIENT):
class EmployeeService {
    async getEmployee(id: string): Promise<Employee> {
        return this.db.query('SELECT * FROM employees WHERE id = $1', [id]);
    }
    
    async searchEmployees(query: string): Promise<Employee[]> {
        return this.db.query(
            'SELECT * FROM employees WHERE name ILIKE $1 OR email ILIKE $1',
            [`%${query}%`]
        );
    }
    
    async updateEmployee(id: string, data: EmployeeUpdate): Promise<void> {
        // Simple validation
        if (!data.email.includes('@')) throw new InvalidEmailError();
        await this.db.query(
            'UPDATE employees SET name = $1, email = $2 WHERE id = $3',
            [data.name, data.email, id]
        );
    }
}
 
// WITH CQRS (OVER-ENGINEERED for this use case):
// - Need to maintain separate read database
// - Need projection handlers for simple CRUD events
// - Need to handle eventual consistency for directory lookups
// - 10x more code for no meaningful benefit
// - Harder to understand for no gain
 
// VERDICT: Use traditional CRUD. CQRS complexity unjustified.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77

// CQRS DECISION SCORECARD
 
interface CQRSEvaluationCriteria {
    // Scale indicators
    readWriteRatio: number;            // > 50:1 = strong indicator
    peakReadsPerSecond: number;        // > 10,000 = strong indicator
    peakWritesPerSecond: number;       // Used for ratio calculation
    
    // Complexity indicators
    domainComplexity: 'low' | 'medium' | 'high';  // High = indicator for
    readViewVariety: number;           // > 3 distinct views = indicator for
    
    // Consistency indicators
    readStalenessToleranceMs: number;  // > 1000ms = indicator for
    writeConsistencyRequirement: 'eventual' | 'strong';  // Strong write ok
    
    // Team/Org indicators
    teamSize: number;                  // > 5 = indicator for
    operationalMaturity: 'low' | 'medium' | 'high';  // High = indicator for
    domainStability: 'evolving' | 'stable';  // Stable = indicator for
}
 
function evaluateCQRSFit(criteria: CQRSEvaluationCriteria): CQRSRecommendation {
    let score = 0;
    const reasons: string[] = [];
    
    // Strongly positive indicators
    if (criteria.readWriteRatio > 50) {
        score += 3;
        reasons.push(`High read/write ratio (${criteria.readWriteRatio}:1)`);
    }
    if (criteria.peakReadsPerSecond > 10000) {
        score += 2;
        reasons.push(`High read volume (${criteria.peakReadsPerSecond}/sec)`);
    }
    if (criteria.domainComplexity === 'high' && criteria.readViewVariety > 3) {
        score += 3;
        reasons.push('Complex domain with multiple read views');
    }
    if (criteria.readStalenessToleranceMs > 5000) {
        score += 2;
        reasons.push('Reads tolerate eventual consistency');
    }
    if (criteria.domainStability === 'stable') {
        score += 1;
        reasons.push('Domain is stable');
    }
    
    // Negative indicators
    if (criteria.readWriteRatio < 10) {
        score -= 2;
        reasons.push(`Low read/write ratio (${criteria.readWriteRatio}:1)`);
    }
    if (criteria.readStalenessToleranceMs < 100) {
        score -= 3;
        reasons.push('Strong consistency required for reads');
    }
    if (criteria.teamSize < 3) {
        score -= 2;
        reasons.push('Small team may struggle with complexity');
    }
    if (criteria.operationalMaturity === 'low') {
        score -= 2;
        reasons.push('Limited operational maturity');
    }
    if (criteria.domainStability === 'evolving') {
        score -= 2;
        reasons.push('Domain still evolving rapidly');
    }
    
    return {
        recommendation: score >= 5 ? 'ADOPT' : score >= 0 ? 'CONSIDER' : 'AVOID',
        score,
        reasons,
        guidance: getGuidance(score, criteria)
    };
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64

// TRADING PLATFORM CQRS IMPLEMENTATION
 
// Characteristics:
// - 500K events per second during market hours
// - Millisecond-level timing requirements for execution
// - Complex regulatory reporting requirements
// - Multiple user interfaces: trader workstation, mobile, API
// - Historical analysis spanning years of data
 
// WRITE SIDE: Event-sourced order management
class TradingOrderAggregate {
    // Commands execute in < 1ms
    submitOrder(order: OrderRequest): void {
        this.validateRiskLimits(order);
        this.validateMarketHours();
        this.addEvent(new OrderSubmittedEvent(order));
    }
    
    // Strict consistency for execution
    executeOrder(executionDetails: ExecutionDetails): void {
        this.ensureOrderState(OrderState.PENDING);
        this.addEvent(new OrderExecutedEvent(executionDetails));
    }
}
 
// READ SIDE 1: Real-time trading dashboard
// Technology: Custom in-memory data grid
// Latency: < 5ms updates, < 1ms reads
interface TradingDashboardView {
    positions: Map<Symbol, PositionView>;
    openOrders: OrderView[];
    pnlRealtime: MoneyView;
    riskMetrics: RiskMetrics;
}
 
// READ SIDE 2: Historical analytics
// Technology: ClickHouse (column-store for time-series)
// Latency: Complex queries in < 1 second over billions of rows
interface HistoricalAnalyticsView {
    // Aggregated by day, week, month, year
    // No impact on trading path performance
}
 
// READ SIDE 3: Regulatory reporting
// Technology: PostgreSQL with audit tables
// Latency: Batch processing acceptable
interface RegulatoryReportView {
    // Complete audit trail
    // Different retention than trading views
}
 
// READ SIDE 4: Mobile app
// Technology: Redis + MongoDB
// Latency: < 100ms for portfolio view
interface MobilePortfolioView {
    // Simplified for mobile display
    // Different update frequency than desktop
}
 
// RESULT:
// - Trading execution unaffected by reporting queries
// - Each view optimized for its specific requirements
// - Teams work independently on their read models
// - Complexity justified by $B in daily trading volume

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50

// HEALTHCARE SYSTEM: SELECTIVE CQRS
 
// NOT using CQRS: Critical patient data
// Reason: Must always show current medications, allergies
// Strong consistency is a patient safety requirement
class PatientCriticalDataService {
    // Traditional approach - single source of truth
    async getAllergies(patientId: string): Promise<Allergy[]> {
        // Direct read from primary database
        // Cannot tolerate any staleness
        return this.db.query('SELECT * FROM allergies WHERE patient_id = $1', [patientId]);
    }
    
    async addAllergy(patientId: string, allergy: Allergy): Promise<void> {
        await this.db.insert('allergies', { patient_id: patientId, ...allergy });
    }
}
 
// USING CQRS: Historical records and analytics
// Reason: High read volume, complex queries, staleness acceptable
class PatientHistoryService {
    // Write side: Append to medical records
    async addEncounter(encounter: Encounter): Promise<void> {
        await this.writeDb.insert('encounters', encounter);
        await this.eventBus.publish(new EncounterRecordedEvent(encounter));
    }
}
 
class PatientHistoryQueryService {
    // Read side: Optimized for complex queries
    async getPatientTimeline(patientId: string, filters: TimelineFilters): Promise<TimelineView> {
        // Pre-aggregated, searchable, across multiple record types
        return this.elasticsearch.search({
            index: 'patient-timeline',
            query: { patient_id: patientId, ...filters }
        });
    }
    
    async getPopulationAnalytics(criteria: AnalyticsCriteria): Promise<AnalyticsResult> {
        // Complex aggregations across millions of records
        // Never touches the transactional database
        return this.analyticsDb.query(criteria);
    }
}
 
// RESULT:
// - Critical data: 0ms staleness (traditional CRUD)
// - Historical analysis: Highly optimized (CQRS)
// - Analytics: Isolated from clinical operations (CQRS)
// - Pattern applied WHERE BENEFICIAL, not everywhere

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57

// STAGE 1: SEPARATE CODE PATHS, SAME DATABASE
 
// Before: Single service doing everything
class OrderService {
    async createOrder(request: CreateOrderRequest): Promise<Order> { /* ... */ }
    async getOrder(id: string): Promise<Order> { /* ... */ }
    async getOrderList(customerId: string): Promise<Order[]> { /* ... */ }
}
 
// After: Separate command and query services
class OrderCommandService {
    constructor(private readonly orderRepository: OrderRepository) {}
    
    async createOrder(request: CreateOrderRequest): Promise<OrderId> {
        const order = Order.create(request);
        await this.orderRepository.save(order);
        return order.id;
    }
    
    async confirmOrder(orderId: string): Promise<void> {
        const order = await this.orderRepository.getById(orderId);
        order.confirm();
        await this.orderRepository.save(order);
    }
}
 
class OrderQueryService {
    constructor(private readonly database: Database) {}
    
    // Direct SQL, no domain objects
    async getOrderSummaries(customerId: string): Promise<OrderSummaryDto[]> {
        return this.database.query(`
            SELECT id, order_number, status, total, created_at
            FROM orders WHERE customer_id = $1
        `, [customerId]);
    }
    
    async getOrderDetail(orderId: string): Promise<OrderDetailDto> {
        // Single query with JOINs, returns DTO directly
        return this.database.queryOne(`
            SELECT o.*, 
                   json_agg(oi.*) as items,
                   c.name as customer_name
            FROM orders o
            JOIN order_items oi ON oi.order_id = o.id
            JOIN customers c ON c.id = o.customer_id
            WHERE o.id = $1
            GROUP BY o.id, c.name
        `, [orderId]);
    }
}
 
// BENEFITS ACHIEVED:
// - Separate models (DTOs for reads, aggregates for writes)
// - Query optimization possible without affecting writes
// - Foundation for further separation
// - Zero infrastructure change

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58

// STAGE 2: READ SIDE INFRASTRUCTURE
 
class OrderQueryService {
    constructor(
        private readonly readReplica: Database,  // Read replica
        private readonly cache: RedisClient,
        private readonly primaryDb: Database     // Fallback
    ) {}
    
    async getOrderSummaries(customerId: string): Promise<OrderSummaryDto[]> {
        // Try cache first
        const cacheKey = `customer:${customerId}:order-summaries`;
        const cached = await this.cache.get(cacheKey);
        if (cached) return JSON.parse(cached);
        
        // Query read replica (async replication from primary)
        const results = await this.readReplica.query(`
            SELECT id, order_number, status, total, created_at
            FROM orders WHERE customer_id = $1
        `, [customerId]);
        
        // Cache for 60 seconds
        await this.cache.setex(cacheKey, 60, JSON.stringify(results));
        
        return results;
    }
    
    async getOrderDetail(orderId: string): Promise<OrderDetailDto> {
        const cacheKey = `order:${orderId}:detail`;
        const cached = await this.cache.get(cacheKey);
        if (cached) return JSON.parse(cached);
        
        // Read from replica
        const result = await this.readReplica.queryOne(/* ... */);
        
        await this.cache.setex(cacheKey, 300, JSON.stringify(result));
        return result;
    }
}
 
// Cache invalidation on writes
class OrderCommandService {
    async confirmOrder(orderId: string): Promise<void> {
        const order = await this.orderRepository.getById(orderId);
        order.confirm();
        await this.orderRepository.save(order);
        
        // Invalidate related caches
        await this.cache.del(`order:${orderId}:detail`);
        await this.cache.del(`customer:${order.customerId}:order-summaries`);
    }
}
 
// BENEFITS ACHIEVED:
// - Read scaling via replica
// - Reduced primary database load
// - Faster reads via caching
// - Eventual consistency (replica lag + cache TTL)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54

// STAGE 3: EVENT-DRIVEN READ MODEL UPDATES
 
// Write side publishes events
class OrderCommandService {
    async confirmOrder(orderId: string): Promise<void> {
        const order = await this.orderRepository.getById(orderId);
        order.confirm();
        await this.orderRepository.save(order);
        
        // Publish events (not cache invalidation)
        await this.eventPublisher.publish(order.getUncommittedEvents());
        order.clearUncommittedEvents();
    }
}
 
// Event handlers update read models
class OrderReadModelProjector {
    constructor(
        private readonly readDb: Database,
        private readonly cache: RedisClient,
        private readonly searchIndex: ElasticsearchClient
    ) {}
    
    @EventHandler(OrderConfirmedEvent)
    async onOrderConfirmed(event: OrderConfirmedEvent): Promise<void> {
        // Update denormalized read table
        await this.readDb.update('order_summaries', 
            { order_id: event.orderId },
            { status: 'confirmed', confirmed_at: event.timestamp }
        );
        
        // Update search index
        await this.searchIndex.update('orders', event.orderId, {
            status: 'confirmed'
        });
        
        // Update cache (or let it expire)
        await this.cache.del(`order:${event.orderId}:detail`);
    }
}
 
// Query service reads from dedicated stores
class OrderQueryService {
    async searchOrders(query: string): Promise<OrderSearchResult[]> {
        // Now using dedicated search infrastructure
        return this.searchIndex.search('orders', { query });
    }
}
 
// BENEFITS ACHIEVED:
// - Decoupled write and read paths
// - Multiple read models (SQL, search, cache)
// - Reliable synchronization via events
// - Foundation for full CQRS