Pricing Engine Architecture Patterns

This is a high-performance financial system processing hundreds of price change notifications per second with real money transactions. These patterns are critical.

System Context

• Throughput: ~33 notifications/sec typical, 500-1000/sec capacity
• Database Scale: 93M+ rows in price history tables
• Concurrency: Multiple instances run simultaneously
• Stakes: Real money transactions - errors have financial impact

Database Operations (CRITICAL)

Bulk Operations

MUST use QuickInsertService with PostgreSQL COPY protocol for inserting multiple records.

// CORRECT - Bulk insert
await quickInsertService.InsertAsync(items, cancellationToken);

// WRONG - Individual inserts in loop
foreach (var item in items)
    await dbContext.AddAsync(item);  // CRITICAL VIOLATION

Index Awareness

New queries MUST consider indexes. Unindexed query on price_history_items (93M+ rows) = system degradation.

Time-series Pattern

Append-only tables + _latest tables with triggers. Never update historical records.

B2B/B2C Dual Processing (CRITICAL)

Most entities have _b2b variants. If code touches B2C pricing, verify B2B is also handled.

B2C Table	B2B Table
price_history_items	price_history_items_b2b
recommendations	recommendations_b2b
buy_box_history	buy_box_history_b2b

Missing B2B handling = 50% of pricing logic broken.

Background Jobs (CRITICAL)

Cancellation Tokens

MUST accept and propagate CancellationToken to all async operations.

// CORRECT
public async Task ExecuteAsync(CancellationToken cancellationToken)
{
    await dbContext.SaveChangesAsync(cancellationToken);
}

// WRONG - Missing cancellation token causes shutdown hangs
public async Task ExecuteAsync()
{
    await dbContext.SaveChangesAsync();  // CRITICAL VIOLATION
}

Distributed Locks

Jobs that shouldn't run concurrently MUST use PostgresqlDistributedLock.

Configuration

Via appsettings.json under Modules::{ModuleName}::BackgroundJobs.

Logging

MUST log start/completion/errors with context.

Error Handling (CRITICAL)

// CORRECT - Specific exception, logged and re-thrown
catch (DbUpdateException ex)
{
    logger.LogError(ex, "Failed to save price update for {Sku}", sku);
    throw;  // Re-throw for retry logic
}

// WRONG - Silent swallow
catch (Exception) { }  // CRITICAL VIOLATION in financial operations

// JSON parsing errors should be warnings, not crashes
catch (JsonException ex)
{
    logger.LogWarning(ex, "Invalid JSON in notification");
}

Configuration (Security)

• No hardcoded: URLs, timeouts, batch sizes, credentials
• Use: IOptions<T> pattern
• Secrets: Via Docker mounts to /app/secrets/

API/Endpoint Pattern

Modules/{Module}/Endpoints/Read/   - Read endpoints
Modules/{Module}/Endpoints/Write/  - Write endpoints

Contracts (request/response) in same file as endpoint. All I/O operations MUST be async.

Frontend Patterns

• Container components load their own data via TanStack Query hooks
• Never modify /components/ui/ (shadcn components)
• Assume millions of records - always provide filtering/pagination
• Debounce search inputs (300-500ms)

Quick Checklist

Before any change:

• No performance anti-patterns (loops with SaveChanges, unbounded ToList)
• Indexes considered for new queries
• B2B variant handled if applicable
• Cancellation tokens propagated
• Error handling appropriate
• No security vulnerabilities
• Follows existing codebase patterns