# NT8-SDK — Project Context & Current State
**Version:** 3.0 | **Date:** 2026-03-27 | **Status:** Sprint 2 Active — SIM Validation

> This file supersedes the previous PROJECT_HANDOVER.md and is the live source of truth.
> See also: `SPRINT_BOARD.md`, `GAP_ANALYSIS_AND_ROADMAP.md`, `CODING_PATTERNS.md`, `KILOCODE_WORKFLOW.md`
> Full formatted handover: `NT8_SDK_Handover_Package.docx`

---

## 1. What This Is

NT8-SDK is an institutional-grade algorithmic futures trading system built on NinjaTrader 8. It is not a research prototype — it is production trading software where bugs equal real financial losses.

The system trades NQ (Nasdaq 100 E-mini futures) using a 30-minute Opening Range Breakout strategy (SimpleORB) with a 10-factor confluence scoring engine that grades each signal A+ through F before allowing execution. A scaler/runner dual-leg architecture captures quick targets on the scaler while the runner trails for extended moves.

**Division of labor:** Claude handles architecture, diagnosis, and Kilocode prompt design. Kilocode executes ALL code changes. Mo owns strategy direction and go/no-go decisions.

---

## 2. Technology Stack

| Layer | Technology | Constraint |
|---|---|---|
| Language | C# 5.0 | Hard — NinjaScript compiler limit |
| Framework | .NET Framework 4.8 | Hard — NT8 requirement |
| Platform | NinjaTrader 8 | Hard — execution environment |
| Local repo | `C:\dev\nt8-sdk` | Windows path |
| NT8 deploy | `C:\Users\billy\Documents\NinjaTrader 8\bin\Custom\Strategies\` | Must match source |
| Deploy script | `deployment\deploy-to-nt8.bat` | Creates timestamped backups |
| VCS | Gitea (self-hosted) | `https://git.thehussains.org/mo/nt8-sdk` |
| AI coding | Kilocode | Executes ALL code changes |
| Automation | n8n (self-hosted) | Deferred to Sprint 4 |
| ML inference | Ollama (local) | Deferred to Sprint 5 |

**Critical C# constraint:** No `$""`, no `?.`, no `=>`, no async/await. Use `string.Format()`, explicit null checks, full method bodies.

---

## 3. Architecture (Top to Bottom)

```
SimpleORBNT8.cs          NT8 entry point — sets defaults, adds daily bar series, builds DailyBarContext
      ↓
NT8StrategyBase.cs       Abstract base — bar routing, session management, kill switch, breakeven, runner
      ↓
SimpleORBStrategy.cs     Core signal — ORB detection, 10-factor confluence, _tradeTaken session lock
      ↓
NT8OrderAdapter.cs       INT8ExecutionBridge — calls EnterLong/EnterShort/SetStopLoss
      ↓
PortfolioRiskManager.cs  Singleton — cross-strategy daily loss + contract cap
      ↓
NinjaTrader 8            Execution, fills, order management
```

---

## 4. Current Production Parameters (SIM: SimSimple ORB)

| Parameter | Value | Notes |
|---|---|---|
| Instrument | NQ JUN26 | Primary instrument |
| Bar type | 13-Range bars | |
| BarsRequiredToTrade | 50 | Warm-up guard |
| DailyLossLimit | $1,000 | |
| MaxTradeRisk | $200 | |
| RiskPerTrade | $100 | 2 contracts at current NQ prices |
| MinContracts | 1 | |
| MaxContracts | 3 | |
| MaxOpenPositions | 2 | Scaler + runner |
| EntriesPerDirection | 2 | Scaler slot 1, runner slot 2 |
| MinTradeGrade | 5 (A) | 4 (B) for broad SIM testing |
| EnableShortTrades | False | Long-only until short backtest done |
| BreakevenTriggerTicks | 20 | Tuned from 12 |
| RunnerTrailTicks | 20 | Tuned from 12 |
| OpeningRangeMinutes | 30 | 9:30–10:00 ET |
| StopTicks | 8 | $40 per contract NQ |
| TargetTicks | 16 (dynamic) | Scales with ORB/ATR ratio |

---

## 5. Two-Path Deployment Rule

Every code change MUST be applied to both:
1. `C:\dev\nt8-sdk\src\NT8.Adapters\Strategies\` (repo source)
2. `C:\Users\billy\Documents\NinjaTrader 8\bin\Custom\Strategies\` (NT8 runtime)

After deployment, NT8 must recompile: Tools → Edit NinjaScript → open `NT8StrategyBase.cs` → save.

---

## 6. Key Learnings (Hard-Won)

1. **`State.Historical` guard** — `if (State == State.Realtime && !_realtimeBarSeen) return;` in `ProcessStrategyIntent` allows backtest (Historical), blocks replay burst in live.

2. **`_realtimeBarSeen` flag** — reset to `false` in `State.Realtime`, set `true` on first bar. Skips catch-up bar on live load to prevent replay burst.

3. **`EntriesPerDirection = 2`** — required for scaler + runner. Setting to 1 silently blocks the runner with no error.

4. **`SetStopLoss`/`SetProfitTarget` before `EnterLong`/`EnterShort`** — calling after entry is silently ignored in backtest.

5. **`Calculate.OnBarClose` backtest** — trades appear to close in under 1 second in logs. NT8 simulation artifact, not a bug. Live trades hold 2–20 minutes.

6. **NR7 warm-up** — requires 7 daily bars. Warm-up messages (0/7 bars) are correct behavior.

7. **NT8 never auto-recompiles** — always force recompile after file changes via NinjaScript Editor.

8. **Dual-path deployment mandatory** — stale deployed files cause phantom bugs where code looks right but behaves wrong.

9. **`PortfolioRiskManager` is a singleton** — fully implemented, no changes required. Kill switch, daily loss, contract cap all working.

10. **Sizing formula** — `floor(RiskPerTrade / (StopTicks × $5.00))`. NQ: `$100 / (8 × $5) = 2 contracts`. Always verify `RiskPerTrade <= MaxTradeRisk`.

---

## 7. Validated Backtest Results

| Date | Period | Trades | Win% | PF | Net | Config |
|---|---|---|---|---|---|---|
| 2026-03-27 | Jan–Mar 2026 | 20 | 75% | **7.00** | $1,200 | 1 ct, trail=20 ✅ Best |
| 2026-03-27 | Jan–Mar 2026 | 40 | 75% | 3.69 | $1,075 | 1 ct, trail=12 |
| 2026-03-27 | Mar 2025–Mar 2026 | 148 | 51% | 3.15 | $71,303 | 9 cts (experimental) |

The 9-contract run used `RiskPerTrade=$500` — not a production configuration. Runner leg was also blocked (`EntriesPerDirection=1`) for that run. Re-run required after Sprint 2 fixes.

---

## 8. Immediate Next Actions Before Market Open

1. Run Strategy Analyzer (NQ JUN26, Jan 1 2026 → Mar 27 2026) and confirm `PNL_UPDATE Position=Short Qty=2` in session log — validates runner leg
2. Verify SIM account settings: `RiskPerTrade=$100`, `BreakevenTriggerTicks=20`, `RunnerTrailTicks=20`
3. Only re-enable BX68915-15 after runner validation passes — long-only, `MaxContracts=2`, `DailyLossLimit=$500`

---

## 📋 Executive Summary

The NT8 SDK is an **institutional-grade algorithmic trading framework** for NinjaTrader 8, designed for automated futures trading (ES, NQ, MES, MNQ, CL, GC). Successfully completed **Phases 0-5** implementing core trading infrastructure, advanced risk management, intelligent position sizing, market microstructure awareness, intelligence layer with confluence scoring, and comprehensive analytics & reporting.

**Current State:** Production-ready core trading engine with 240+ passing tests, complete analytics layer, ready for production hardening.

---

## 🎯 Project Vision & Purpose

### Core Mission
Build an institutional-grade trading SDK that:
- **Protects Capital First** - Multi-tier risk management before profit
- **Makes Intelligent Decisions** - Grade trades based on multiple factors
- **Executes Professionally** - Sub-200ms latency, thread-safe operations
- **Measures Everything** - Comprehensive analytics and attribution

### Why This Matters
- This is **production trading software** where bugs = real financial losses
- System runs **24/5** during market hours
- **Institutional-grade quality** required (not hobbyist code)
- Must be **deterministic** for backtesting and auditing

---

## ✅ Completed Phases (0-5)

### Phase 0: Foundation (30 minutes)
**Status:** ✅ Complete  
**Deliverables:** Repository structure, build system, .NET Framework 4.8 setup

### Phase 1: Basic OMS (2 hours)
**Status:** ✅ Complete  
**Tests:** 34 passing  
**Code:** ~1,500 lines  
**Deliverables:** Order state machine, basic order manager, NT8 adapter interface

### Phase 2: Enhanced Risk & Sizing (3 hours)
**Status:** ✅ Complete  
**Tests:** 90+ passing  
**Code:** ~3,000 lines  
**Deliverables:** Multi-tier risk management, intelligent position sizing, optimal-f calculator

### Phase 3: Market Microstructure & Execution (3-4 hours)
**Status:** ✅ Complete  
**Tests:** 120+ passing  
**Code:** ~3,500 lines  
**Deliverables:** Liquidity monitoring, execution quality tracking, slippage calculation

### Phase 4: Intelligence & Grading (4-5 hours)
**Status:** ✅ Complete  
**Tests:** 150+ passing  
**Code:** ~4,000 lines  
**Deliverables:** Confluence scoring, regime detection, grade-based filtering, risk mode management

### Phase 5: Analytics & Reporting (3-4 hours)
**Status:** ✅ **COMPLETE - 2026-02-16**  
**Tests:** 240+ passing (90 new analytics tests)  
**Code:** ~5,000 lines  
**Deliverables:**
- Trade lifecycle tracking & recording
- Performance metrics (Sharpe, Sortino, win rate, profit factor)
- Multi-dimensional P&L attribution (by grade, regime, time, strategy)
- Drawdown analysis with period detection
- Grade/Regime/Confluence performance insights
- Daily/Weekly/Monthly reporting
- Parameter optimization tools
- Monte Carlo simulation
- Portfolio optimization

---

## 📊 Current Metrics

- **Total Production Code:** ~20,000 lines
- **Total Tests:** 240+
- **Test Pass Rate:** 100%
- **Code Coverage:** >85%
- **Performance:** All benchmarks exceeded
- **Analytics Components:** 15 major modules
- **Zero Critical Warnings:** Legacy warnings only (unchanged baseline)

---

## 🎯 Recommended Next Steps

### Option 1: Production Hardening (Recommended)
**Focus:** Make the system production-ready for live trading

**Priority Tasks:**
1. **CI/CD Pipeline**
   - Automated build verification on commit
   - Automated test execution
   - Code coverage reporting
   - Deployment automation to NinjaTrader 8

2. **Integration Testing Enhancement**
   - End-to-end workflow tests
   - Multi-component integration scenarios
   - Performance benchmarking suite
   - Stress testing under load

3. **Monitoring & Observability**
   - Structured logging enhancements
   - Health check endpoints
   - Performance metrics collection
   - Alert system for risk breaches

4. **Configuration Management**
   - JSON-based configuration system
   - Environment-specific configs (dev/sim/prod)
   - Runtime parameter validation
   - Configuration hot-reload capability

5. **Error Recovery & Resilience**
   - Graceful degradation patterns
   - Circuit breaker implementations
   - Retry policies with exponential backoff
   - Dead letter queue for failed orders

**Estimated Time:** 2-3 weeks with focused effort

---

### Option 2: Golden Strategy Implementation
**Focus:** Build reference strategy to validate all modules

**Deliverable:** Complete SimpleORBStrategy implementation that:
- Uses all Phase 1-5 components
- Demonstrates best practices
- Serves as template for future strategies
- Includes comprehensive backtesting

**Estimated Time:** 1 week

---

### Option 3: Advanced Features (Future Enhancements)
**Focus:** Add sophisticated trading capabilities

**Potential Additions:**
- Smart order routing across venues
- Advanced order types (Iceberg, TWAP, VWAP)
- ML model integration framework
- Multi-timeframe analysis
- Correlation-based portfolio management

**Estimated Time:** 2-4 weeks per major feature

---

## 📁 Repository Structure

```
C:\dev\nt8-sdk\
├── src/
│   ├── NT8.Core/              # Core business logic (20,000 lines)
│   │   ├── Analytics/         ✅ Phase 5 - Trade analytics & reporting
│   │   ├── Intelligence/      ✅ Phase 4 - Confluence & grading
│   │   ├── Execution/         ✅ Phase 3 - Execution quality
│   │   ├── MarketData/        ✅ Phase 3 - Market microstructure
│   │   ├── Sizing/            ✅ Phase 2 - Position sizing
│   │   ├── Risk/              ✅ Phase 2 - Risk management
│   │   ├── OMS/               ✅ Phase 1 - Order management
│   │   ├── Common/            ✅ Phase 0 - Core interfaces
│   │   └── Logging/           ✅ Phase 0 - Logging infrastructure
│   ├── NT8.Adapters/          # NinjaTrader 8 integration
│   ├── NT8.Strategies/        # Strategy implementations
│   └── NT8.Contracts/         # API contracts
├── tests/
│   ├── NT8.Core.Tests/        # 240+ unit tests
│   ├── NT8.Integration.Tests/ # Integration test suite
│   └── NT8.Performance.Tests/ # Performance benchmarks
├── docs/                      # Complete documentation
│   ├── Phase5_Completion_Report.md  # NEW: Analytics completion
│   ├── ARCHITECTURE.md
│   ├── API_REFERENCE.md
│   └── DEPLOYMENT_GUIDE.md
└── .kilocode/                 # AI development rules
```

---

## 🔑 Key Architecture Highlights

### Risk-First Design
All trading operations flow through multi-tier risk validation before execution. No shortcuts, no bypasses.

### Thread-Safe Operations
Comprehensive locking patterns protect all shared state from concurrent access issues.

### Deterministic Replay
Complete audit trail with correlation IDs enables exact replay of historical sessions.

### Modular Component Design
Clean separation between Core (business logic), Adapters (NT8 integration), and Strategies (trading logic).

### Analytics-Driven Optimization
Full attribution and performance measurement enables data-driven strategy improvement.

---

## 📞 Support & Documentation

- **Architecture Guide:** `docs/ARCHITECTURE.md`
- **API Reference:** `docs/API_REFERENCE.md`
- **Deployment Guide:** `docs/DEPLOYMENT_GUIDE.md`
- **Quick Start:** `docs/QUICK_START.md`
- **Phase Reports:** `docs/Phase*_Completion_Report.md`

---

## 🎉 Phase 5 Highlights

### What Was Built
- **15 major analytics components** covering the complete analytics lifecycle
- **90 new tests** bringing total to 240+ with 100% pass rate
- **Multi-dimensional attribution** enabling detailed performance breakdown
- **Optimization toolkit** for systematic strategy improvement
- **Production-ready reporting** with daily/weekly/monthly summaries

### Key Capabilities Added
1. **Trade Lifecycle Tracking** - Complete entry/exit/partial-fill capture
2. **Performance Measurement** - Sharpe, Sortino, win rate, profit factor, expectancy
3. **Attribution Analysis** - By grade, regime, time-of-day, strategy
4. **Drawdown Analysis** - Period detection, recovery metrics, risk assessment
5. **Confluence Validation** - Factor analysis, weighting optimization
6. **Parameter Optimization** - Grid search, walk-forward, sensitivity analysis
7. **Monte Carlo Simulation** - Confidence intervals, risk-of-ruin calculations
8. **Portfolio Optimization** - Multi-strategy allocation, portfolio-level metrics

### Technical Excellence
- ✅ Thread-safe in-memory storage
- ✅ Zero interface modifications (backward compatible)
- ✅ Comprehensive XML documentation
- ✅ C# 5.0 / .NET Framework 4.8 compliant
- ✅ Performance optimized (minimal allocations in hot paths)

---

## 🚀 Project Status: PHASE 5 COMPLETE

**The NT8 SDK now has a complete, production-grade analytics layer ready for institutional trading.**

Next recommended action: **Production Hardening** to prepare for live deployment.

---

**Document Prepared:** February 16, 2026  
**Last Updated:** February 17, 2026  
**Version:** 2.0