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:**
```csharp
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:**
```csharp
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:**
```csharp
public record LimitOrderRequest(
    string Symbol,
    OrderSide Side,
    int Quantity,
    double LimitPrice,
    TimeInForce Tif
) : OrderRequest;
```

**Stop Order:**
```csharp
public record StopOrderRequest(
    string Symbol,
    OrderSide Side,
    int Quantity,
    double StopPrice,
    TimeInForce Tif
) : OrderRequest;
```

**Stop-Limit Order:**
```csharp
public record StopLimitOrderRequest(
    string Symbol,
    OrderSide Side,
    int Quantity,
    double StopPrice,
    double LimitPrice,
    TimeInForce Tif
) : OrderRequest;
```

**MIT Order:**
```csharp
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:**
```csharp
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):**
```csharp
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:**
```csharp
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:**
```csharp
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:**
```csharp
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:**
```csharp
IsDuplicate = 
    Same symbol AND
    Same side AND
    Same quantity AND
    Within 5 seconds
```

**Methods:**
```csharp
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:**
```csharp
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:**
```csharp
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:**
```csharp
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:**
```csharp
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:**
```csharp
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:**
```csharp
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:
```csharp
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!** 🚀