Skip to main content

Devlog: 2026-03-17 — BestEx Specification

What Happened​

Wrote the first feature specification for PSSaaS: the Best Execution (BestEx) pricing analysis engine. This is the "specs before code" gate required by .cursorrules before any implementation begins.

What Was Produced​

docs-site/docs/specs/bestex-engine.md — a comprehensive specification covering:

  • 50+ functional requirements across 8 categories (profile management, loan selection, price ingestion, analysis pipeline, ranking, error handling, archiving)
  • 45 numbered business rules extracted from the PowerBuilder deep dive and SQL MI schema (price validity, par rate interpolation, DPC calculations, feature adjustment sequencing, servicing strategies, total price formula, unit gain formula, ranking criteria)
  • 20+ API endpoint definitions with TypeScript-like request/response interfaces and async execution model
  • Data model mapping from SQL MI tables to .NET domain entities (aggregate roots: BestExProfile, AnalysisRun)
  • UX notes for both modern dashboard mode (new customers) and power grid mode (migrating customers)
  • 24 acceptance criteria including the critical parity requirement: results must match PowerBuilder BestEx output within +/-$0.01 per loan
  • 3 Mermaid diagrams: API endpoint map, data flow, 24-step pipeline

Key Decisions in the Spec​

  • BestEx is a read-only consumer of prices — it does not manage price ingestion. Price management is a separate spec.
  • Analysis runs are async — triggered via API, results polled or pushed via WebSocket. The 24-step pipeline is compute-heavy (Watermark TPO has 732K possible loan scenarios).
  • The engine operates within one bounded context in the modular monolith. It reads from price tables, loan tables, and instrument/investor config; it writes to analysis result and error tables.
  • Golden file regression testing against PowerBuilder output is the primary validation strategy.

Status​

Draft — requires Product Owner review and approval before implementation begins.

What's Next​

  1. Product Owner reviews and approves (or revises) the BestEx spec
  2. Scaffold the .NET solution structure
  3. Begin BestEx implementation