4.1 Architecture Approach
| Strategy | Rationale | ADR |
|---|
| Modular monolith | Start with a single deployable unit. Bounded contexts as separate .NET projects sharing one process. Extract services only when scale, team autonomy, or deployment velocity demands it. | ADR-004 |
| Database-per-tenant | Strongest data isolation. Natural migration path from existing isolated SQL Server instances. Each tenant gets their own database on Azure SQL MI. | ADR-005 |
| API-first design | All business logic exposed through REST APIs. Frontend is a separate React SPA. Enables future mobile clients, partner integrations, and PSX interop without backend changes. | ADR-002 |
4.2 Technology Choices
| Decision | Choice | Rationale |
|---|
| Backend language | .NET 8 / C# | Closest to PowerBuilder heritage. Decimal precision. EF Core for SQL Server. |
| Frontend framework | React + TypeScript | Data-heavy views with AG Grid. Aligns with PowerSeller X (Next.js/React). |
| Database | Azure SQL MI | Existing infrastructure. Database-per-tenant. Preserves existing schema. |
| Cloud provider | Azure (preferred, not locked) | Existing assets. Application code is containerized and vendor-agnostic. |
| Documentation | Docusaurus | React-based, MDX support, containerized. |
4.3 UX Strategy
Two presentation modes serve two audiences with the same underlying business logic:
| Mode | Audience | Characteristics |
|---|
| Modern (default) | New customers | Dashboards, wizards, guided flows, progressive disclosure. Clean and approachable. |
| Power (opt-in) | Migrating customers | Dense grids, all fields visible, keyboard-driven, minimal clicks. Matches desktop app efficiency. |
Same React components underneath — different layout and disclosure rules. User preference controls which mode is active. See ADR-008.
4.4 Development Strategy
| Principle | Implementation |
|---|
| Specs before code | Every feature has a written specification before implementation begins. Specs define requirements, business rules, API design, data model, and acceptance criteria. |
| AI-assisted development | CTO builds with Cursor + AI agents during architecture and early implementation. Documentation enables future developers to onboard independently. |
| Incremental schema migration | Preserve legacy schema initially for validation. Add audit columns, foreign keys. Rename/restructure in later phases. |
| Side-by-side validation | Desktop app and SaaS app can coexist on the same database. Calculations validated against production data. |
4.5 Integration Strategy
| System | Integration Approach |
|---|
| PowerSeller X | REST API. SaaS queries marketplace pricing. Shared domain concepts via API contracts (not shared code). |
| MBS Access | REST API. Market data consumed by pricing engine. |
| Odoo | REST/Webhook. Odoo provisions tenants, manages subscriptions. SaaS delivers product experience. |
| Agency systems | SFTP/API. Pool commitment and delivery in agency-required formats. |
| Price feeds | REST/WebSocket. Replaces legacy DDE mechanism. |
| Desktop app | Shared database during coexistence. Schema changes must be backward-compatible. |
4.6 Build Priority
Tier 1 — Core Differentiators (Build First)
- Best Execution Engine — The 24-step pricing analysis. Core IP.
- Pooling Engine — The 12-step constraint satisfaction algorithm.
- Trade Lifecycle — Creation through designation and settlement.
Tier 2 — Essential Operations (Build Second)
- Pipeline Management — Loan intake and status tracking.
- Risk Analysis — Position reconciliation and hedging.
- Price Ingestion — Modern price feeds replacing DDE.
Tier 3 — Support Functions (Build or Buy)
- Import/Export — ETL options exist.
- Document Tracking — Important but not unique.
- Reporting — Could leverage Power BI or embedded analytics.
- Archive — Database-level concern.