nt8-sdk/Phase3_Implementation_Guide.md

Phase 3: Market Microstructure & Execution - Implementation Guide

Estimated Time: 3-4 hours
Complexity: Medium-High
Dependencies: Phase 2 Complete ✅

---

Implementation Overview

This phase adds professional-grade execution capabilities with market awareness, advanced order types, execution quality tracking, and intelligent order routing. We're building the "HOW to trade" layer on top of Phase 2's "WHAT to trade" foundation.

---

Phase A: Market Microstructure Awareness (45 minutes)

Task A1: Create MarketMicrostructureModels.cs

Location: src/NT8.Core/MarketData/MarketMicrostructureModels.cs

Deliverables:

• SpreadInfo record - Bid-ask spread tracking
• LiquidityMetrics record - Order book depth analysis
• SessionInfo record - RTH vs ETH session data
• ContractRollInfo record - Roll detection data
• LiquidityScore enum - Poor/Fair/Good/Excellent
• TradingSession enum - PreMarket/RTH/ETH/Closed

Key Requirements:

• C# 5.0 syntax only
• Thread-safe value types (records)
• XML documentation
• Proper validation

---

Task A2: Create LiquidityMonitor.cs

Location: src/NT8.Core/MarketData/LiquidityMonitor.cs

Deliverables:

• Track bid-ask spread in real-time
• Calculate liquidity score by symbol
• Monitor order book depth
• Detect liquidity deterioration
• Session-aware monitoring (RTH vs ETH)

Key Features:

• Rolling window for spread tracking (last 100 ticks)
• Liquidity scoring algorithm
• Alert thresholds for poor liquidity
• Thread-safe with proper locking

Methods:

public void UpdateSpread(string symbol, double bid, double ask, long volume);
public LiquidityMetrics GetLiquidityMetrics(string symbol);
public LiquidityScore CalculateLiquidityScore(string symbol);
public bool IsLiquidityAcceptable(string symbol, double threshold);

---

Task A3: Create SessionManager.cs

Location: src/NT8.Core/MarketData/SessionManager.cs

Deliverables:

• Track current trading session (RTH/ETH)
• Session start/end times by symbol
• Holiday calendar awareness
• Contract roll detection

Key Features:

• Symbol-specific session times
• Timezone handling (EST for US futures)
• Holiday detection
• Roll date tracking for futures

Methods:

public SessionInfo GetCurrentSession(string symbol, DateTime time);
public bool IsRegularTradingHours(string symbol, DateTime time);
public bool IsContractRolling(string symbol, DateTime time);
public DateTime GetNextSessionStart(string symbol);

---

Phase B: Advanced Order Types (60 minutes)

Task B1: Extend OrderModels.cs

Location: src/NT8.Core/OMS/OrderModels.cs

Add to existing file:

• LimitOrderRequest record
• StopOrderRequest record
• StopLimitOrderRequest record
• MITOrderRequest record (Market-If-Touched)
• TrailingStopConfig record
• OrderTypeParameters record

Order Type Specifications:

Limit Order:

public record LimitOrderRequest(
    string Symbol,
    OrderSide Side,
    int Quantity,
    double LimitPrice,
    TimeInForce Tif
) : OrderRequest;

Stop Order:

public record StopOrderRequest(
    string Symbol,
    OrderSide Side,
    int Quantity,
    double StopPrice,
    TimeInForce Tif
) : OrderRequest;

Stop-Limit Order:

public record StopLimitOrderRequest(
    string Symbol,
    OrderSide Side,
    int Quantity,
    double StopPrice,
    double LimitPrice,
    TimeInForce Tif
) : OrderRequest;

MIT Order:

public record MITOrderRequest(
    string Symbol,
    OrderSide Side,
    int Quantity,
    double TriggerPrice,
    TimeInForce Tif
) : OrderRequest;

---

Task B2: Create OrderTypeValidator.cs

Location: src/NT8.Core/OMS/OrderTypeValidator.cs

Deliverables:

• Validate order type parameters
• Check price relationships (stop vs limit)
• Verify order side consistency
• Symbol-specific validation rules

Validation Rules:

• Limit buy: limit price < market price
• Limit sell: limit price > market price
• Stop buy: stop price > market price
• Stop sell: stop price < market price
• Stop-Limit: stop and limit relationship validation

Methods:

public ValidationResult ValidateLimitOrder(LimitOrderRequest request, double marketPrice);
public ValidationResult ValidateStopOrder(StopOrderRequest request, double marketPrice);
public ValidationResult ValidateStopLimitOrder(StopLimitOrderRequest request, double marketPrice);
public ValidationResult ValidateMITOrder(MITOrderRequest request, double marketPrice);

---

Task B3: Update BasicOrderManager.cs

Location: src/NT8.Core/OMS/BasicOrderManager.cs

Add methods (don't modify existing):

public async Task<string> SubmitLimitOrderAsync(LimitOrderRequest request);
public async Task<string> SubmitStopOrderAsync(StopOrderRequest request);
public async Task<string> SubmitStopLimitOrderAsync(StopLimitOrderRequest request);
public async Task<string> SubmitMITOrderAsync(MITOrderRequest request);

Implementation:

• Validate order type parameters
• Convert to base OrderRequest
• Submit through existing infrastructure
• Track order type in metadata

---

Phase C: Execution Quality Tracking (50 minutes)

Task C1: Create ExecutionModels.cs

Location: src/NT8.Core/Execution/ExecutionModels.cs

Deliverables:

• ExecutionMetrics record - Per-order execution data
• SlippageInfo record - Price slippage tracking
• ExecutionTiming record - Latency breakdown
• ExecutionQuality enum - Excellent/Good/Fair/Poor
• SlippageType enum - Positive/Negative/Zero

ExecutionMetrics:

public record ExecutionMetrics(
    string OrderId,
    DateTime IntentTime,
    DateTime SubmitTime,
    DateTime FillTime,
    double IntendedPrice,
    double FillPrice,
    double Slippage,
    SlippageType SlippageType,
    TimeSpan SubmitLatency,
    TimeSpan FillLatency,
    ExecutionQuality Quality
);

---

Task C2: Create ExecutionQualityTracker.cs

Location: src/NT8.Core/Execution/ExecutionQualityTracker.cs

Deliverables:

• Track every order execution
• Calculate slippage (intended vs actual)
• Measure execution latency
• Score execution quality
• Maintain execution history

Key Features:

• Per-symbol execution statistics
• Rolling averages (last 100 executions)
• Quality scoring algorithm
• Alert on poor execution quality

Methods:

public void RecordExecution(string orderId, StrategyIntent intent, OrderFill fill);
public ExecutionMetrics GetExecutionMetrics(string orderId);
public ExecutionStatistics GetSymbolStatistics(string symbol);
public double GetAverageSlippage(string symbol);
public bool IsExecutionQualityAcceptable(string symbol);

---

Task C3: Create SlippageCalculator.cs

Location: src/NT8.Core/Execution/SlippageCalculator.cs

Deliverables:

• Calculate price slippage
• Determine slippage type (favorable/unfavorable)
• Normalize slippage by symbol (tick-based)
• Slippage impact on P&L

Slippage Formula:

Market Order:
Slippage = FillPrice - MarketPriceAtSubmit

Limit Order:
Slippage = FillPrice - LimitPrice (if better = favorable)

Slippage in Ticks = Slippage / TickSize
Slippage Cost = Slippage * Quantity * TickValue

Methods:

public double CalculateSlippage(OrderType type, double intendedPrice, double fillPrice);
public SlippageType ClassifySlippage(double slippage, OrderSide side);
public int SlippageInTicks(double slippage, double tickSize);
public double SlippageImpact(double slippage, int quantity, double tickValue);

---

Phase D: Smart Order Routing (45 minutes)

Task D1: Create OrderRoutingModels.cs

Location: src/NT8.Core/Execution/OrderRoutingModels.cs

Deliverables:

• RoutingDecision record - Route selection result
• OrderDuplicateCheck record - Duplicate detection data
• CircuitBreakerState record - Circuit breaker status
• RoutingStrategy enum - Direct/Smart/Fallback

---

Task D2: Create DuplicateOrderDetector.cs

Location: src/NT8.Core/Execution/DuplicateOrderDetector.cs

Deliverables:

• Detect duplicate order submissions
• Time-based duplicate window (5 seconds)
• Symbol + side + quantity matching
• Prevent accidental double-entry

Detection Logic:

IsDuplicate = 
    Same symbol AND
    Same side AND
    Same quantity AND
    Within 5 seconds

Methods:

public bool IsDuplicateOrder(OrderRequest request);
public void RecordOrderIntent(OrderRequest request);
public void ClearOldIntents(TimeSpan maxAge);

---

Task D3: Create ExecutionCircuitBreaker.cs

Location: src/NT8.Core/Execution/ExecutionCircuitBreaker.cs

Deliverables:

• Monitor execution latency
• Detect slow execution patterns
• Circuit breaker triggers
• Automatic recovery

Circuit Breaker States:

• Closed (normal): Orders flow normally
• Open (triggered): Block new orders
• Half-Open (testing): Allow limited orders

Trigger Conditions:

• Average execution time > 5 seconds (3 consecutive)
• Order rejection rate > 50% (last 10 orders)
• Manual trigger via emergency command

Methods:

public void RecordExecutionTime(TimeSpan latency);
public void RecordOrderRejection(string reason);
public bool ShouldAllowOrder();
public CircuitBreakerState GetState();
public void Reset();

---

Task D4: Create ContractRollHandler.cs

Location: src/NT8.Core/Execution/ContractRollHandler.cs

Deliverables:

• Detect contract roll periods
• Switch to new contract automatically
• Position transfer logic
• Roll notification

Key Features:

• Symbol-specific roll dates
• Front month vs back month tracking
• Position rollover planning
• Volume-based roll detection

Methods:

public bool IsRollPeriod(string symbol, DateTime date);
public string GetActiveContract(string baseSymbol, DateTime date);
public RollDecision ShouldRollPosition(string symbol, Position position);
public void InitiateRollover(string fromContract, string toContract);

---

Phase E: Stops & Targets Framework (50 minutes)

Task E1: Create StopsTargetsModels.cs

Location: src/NT8.Core/Execution/StopsTargetsModels.cs

Deliverables:

• MultiLevelTargets record - TP1, TP2, TP3 configuration
• TrailingStopConfig record - Trailing stop parameters
• AutoBreakevenConfig record - Auto-breakeven rules
• StopType enum - Fixed/Trailing/ATR/Chandelier
• TargetType enum - Fixed/RMultiple/Percent

MultiLevelTargets:

public record MultiLevelTargets(
    int TP1Ticks,
    int TP1Contracts,  // How many contracts to take profit
    int? TP2Ticks,
    int? TP2Contracts,
    int? TP3Ticks,
    int? TP3Contracts
);

---

Task E2: Create TrailingStopManager.cs

Location: src/NT8.Core/Execution/TrailingStopManager.cs

Deliverables:

• Multiple trailing stop types
• Dynamic stop adjustment
• Auto-breakeven logic
• Per-position stop tracking

Trailing Stop Types:

1. Fixed Trailing:

Trail by fixed ticks from highest high (long) or lowest low (short)

2. ATR Trailing:

Trail by ATR multiplier (e.g., 2 * ATR)

3. Chandelier:

Trail from highest high minus ATR * multiplier

4. Parabolic SAR:

Accelerating factor-based trailing

Methods:

public void StartTrailing(string orderId, Position position, TrailingStopConfig config);
public void UpdateTrailingStop(string orderId, double currentPrice);
public double CalculateNewStopPrice(StopType type, Position position, double marketPrice);
public bool ShouldMoveToBreakeven(Position position, double currentPrice);

---

Task E3: Create MultiLevelTargetManager.cs

Location: src/NT8.Core/Execution/MultiLevelTargetManager.cs

Deliverables:

• Manage multiple profit targets
• Partial position closure
• Automatic target progression
• Scale-out logic

Scale-Out Logic:

Entry: 5 contracts
TP1 (8 ticks): Close 2 contracts, move stop to breakeven
TP2 (16 ticks): Close 2 contracts, trail stop
TP3 (32 ticks): Close 1 contract (final)

Methods:

public void SetTargets(string orderId, MultiLevelTargets targets);
public void OnTargetHit(string orderId, int targetLevel, double price);
public int CalculateContractsToClose(int targetLevel);
public bool ShouldAdvanceStop(int targetLevel);

---

Task E4: Create RMultipleCalculator.cs

Location: src/NT8.Core/Execution/RMultipleCalculator.cs

Deliverables:

• R-multiple based targets
• Risk-reward ratio calculation
• Position sizing by R
• P&L in R terms

R-Multiple Concept:

R = Initial Risk (Stop distance × TickValue × Contracts)
Target = Entry ± (R × Multiple)

Example:
Entry: 4200, Stop: 4192 (8 ticks)
R = 8 ticks = $100 per contract
1R Target: 4208 (8 ticks profit)
2R Target: 4216 (16 ticks profit)
3R Target: 4232 (32 ticks profit)

Methods:

public double CalculateRValue(Position position, double stopPrice, double tickValue);
public double CalculateTargetPrice(double entryPrice, double rValue, double rMultiple, OrderSide side);
public double CalculateRMultiple(double entryPrice, double exitPrice, double rValue);
public MultiLevelTargets CreateRBasedTargets(double entryPrice, double stopPrice, double[] rMultiples);

---

Phase F: Comprehensive Testing (60 minutes)

Task F1: LiquidityMonitorTests.cs

Location: tests/NT8.Core.Tests/MarketData/LiquidityMonitorTests.cs

Test Coverage:

• Spread tracking accuracy
• Liquidity score calculation
• Session-aware monitoring
• Thread safety with concurrent updates
• Alert thresholds

Minimum: 15 tests

---

Task F2: ExecutionQualityTrackerTests.cs

Location: tests/NT8.Core.Tests/Execution/ExecutionQualityTrackerTests.cs

Test Coverage:

• Slippage calculation accuracy
• Execution latency tracking
• Quality scoring logic
• Statistics aggregation
• Historical data retention

Minimum: 18 tests

---

Task F3: OrderTypeValidatorTests.cs

Location: tests/NT8.Core.Tests/OMS/OrderTypeValidatorTests.cs

Test Coverage:

• All order type validations
• Price relationship checks
• Market price boundary conditions
• Invalid order rejection
• Edge cases

Minimum: 20 tests

---

Task F4: TrailingStopManagerTests.cs

Location: tests/NT8.Core.Tests/Execution/TrailingStopManagerTests.cs

Test Coverage:

• All trailing stop types
• Auto-breakeven logic
• Stop adjustment accuracy
• Multi-position handling
• Edge cases

Minimum: 15 tests

---

Task F5: MultiLevelTargetManagerTests.cs

Location: tests/NT8.Core.Tests/Execution/MultiLevelTargetManagerTests.cs

Test Coverage:

• Scale-out logic
• Partial closures
• Stop advancement
• Target progression
• Edge cases

Minimum: 12 tests

---

Task F6: IntegrationTests.cs

Location: tests/NT8.Integration.Tests/Phase3IntegrationTests.cs

Test Coverage:

• Full execution flow: Intent → Order Type → Execution → Quality Tracking
• Multi-level targets with trailing stops
• Circuit breaker integration
• Duplicate order prevention
• Complete trade lifecycle

Minimum: 10 tests

---

Phase G: Integration & Verification (30 minutes)

Task G1: Performance Benchmarks

Location: tests/NT8.Performance.Tests/Phase3PerformanceTests.cs

Benchmarks:

• Order type validation: <2ms
• Execution quality calculation: <3ms
• Liquidity score update: <1ms
• Trailing stop update: <2ms
• Overall execution flow: <15ms

---

Task G2: Build Verification

Command: .\verify-build.bat

Requirements:

• Zero errors
• Zero warnings for new Phase 3 code
• All tests passing (120+ total)
• Coverage >80%

---

Task G3: Documentation Update

Files to update:

• Update README.md with Phase 3 features
• Create Phase3_Completion_Report.md
• Update API_REFERENCE.md with new interfaces
• Add execution examples to docs

---

Success Criteria

Code Quality

• ✅ C# 5.0 syntax only (no C# 6+)
• ✅ Thread-safe (locks on all shared state)
• ✅ XML docs on all public members
• ✅ Try-catch on all public methods
• ✅ Structured logging throughout

Testing

• ✅ >120 total tests passing
• ✅ >80% code coverage
• ✅ All execution scenarios tested
• ✅ All order types tested
• ✅ Integration tests pass
• ✅ Performance benchmarks met

Performance

• ✅ Order validation <2ms
• ✅ Execution tracking <3ms
• ✅ Liquidity update <1ms
• ✅ Overall flow <15ms
• ✅ No memory leaks

Integration

• ✅ Works with Phase 2 risk/sizing
• ✅ No breaking changes
• ✅ Clean interfaces
• ✅ Backward compatible

---

File Creation Checklist

New Files (20):

MarketData (3):

• src/NT8.Core/MarketData/MarketMicrostructureModels.cs
• src/NT8.Core/MarketData/LiquidityMonitor.cs
• src/NT8.Core/MarketData/SessionManager.cs

OMS (1):

• src/NT8.Core/OMS/OrderTypeValidator.cs

Execution (10):

• src/NT8.Core/Execution/ExecutionModels.cs
• src/NT8.Core/Execution/ExecutionQualityTracker.cs
• src/NT8.Core/Execution/SlippageCalculator.cs
• src/NT8.Core/Execution/OrderRoutingModels.cs
• src/NT8.Core/Execution/DuplicateOrderDetector.cs
• src/NT8.Core/Execution/ExecutionCircuitBreaker.cs
• src/NT8.Core/Execution/ContractRollHandler.cs
• src/NT8.Core/Execution/StopsTargetsModels.cs
• src/NT8.Core/Execution/TrailingStopManager.cs
• src/NT8.Core/Execution/MultiLevelTargetManager.cs
• src/NT8.Core/Execution/RMultipleCalculator.cs

Tests (6):

• tests/NT8.Core.Tests/MarketData/LiquidityMonitorTests.cs
• tests/NT8.Core.Tests/Execution/ExecutionQualityTrackerTests.cs
• tests/NT8.Core.Tests/OMS/OrderTypeValidatorTests.cs
• tests/NT8.Core.Tests/Execution/TrailingStopManagerTests.cs
• tests/NT8.Core.Tests/Execution/MultiLevelTargetManagerTests.cs
• tests/NT8.Integration.Tests/Phase3IntegrationTests.cs

Updated Files (2):

• src/NT8.Core/OMS/OrderModels.cs - ADD order type records
• src/NT8.Core/OMS/BasicOrderManager.cs - ADD order type methods

Total: 20 new files, 2 updated files

---

Estimated Timeline

Phase	Tasks	Time	Cumulative
A	Market Microstructure	45 min	0:45
B	Advanced Order Types	60 min	1:45
C	Execution Quality	50 min	2:35
D	Smart Routing	45 min	3:20
E	Stops & Targets	50 min	4:10
F	Testing	60 min	5:10
G	Verification	30 min	5:40

Total: 5-6 hours (budget 3-4 hours for Kilocode efficiency)

---

Critical Notes

Modifications to Existing Code

IMPORTANT: Only these files can be modified:

• ✅ src/NT8.Core/OMS/OrderModels.cs - ADD records only
• ✅ src/NT8.Core/OMS/BasicOrderManager.cs - ADD methods only

FORBIDDEN:

• ❌ Do NOT modify interfaces
• ❌ Do NOT modify existing method signatures
• ❌ Do NOT change Phase 1-2 behavior

Thread Safety

Every class with shared state MUST:

private readonly object _lock = new object();

lock (_lock)
{
    // All shared state access
}

C# 5.0 Compliance

Verify after each file:

• No $"string {interpolation}"
• No ?. or ?[ operators
• No => expression bodies
• No inline out variables
• Use string.Format() for formatting

---

Ready to Start?

Paste into Kilocode Code Mode:

I'm ready to implement Phase 3: Market Microstructure & Execution.

I will follow Phase3_Implementation_Guide.md starting with
Task A1: Create MarketMicrostructureModels.cs

Please confirm you understand:
- C# 5.0 syntax requirements
- File modification boundaries (MarketData/Execution/OMS only)
- Thread safety requirements (locks on all shared state)
- No breaking changes to existing interfaces
- Verification after each file (Ctrl+Shift+B)

Let's start with creating MarketMicrostructureModels.cs in src/NT8.Core/MarketData/

---

Phase 3 will complete your trading core! 🚀