mo/nt8-sdk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
pre-cleanup-snapshot
nt8-sdk/PROJECT_HANDOVER.md
mo 9a28a49292
Some checks failed
Build and Test / build (push) Has been cancelled
Details
Pre-cleanup baseline snapshot
2026-04-05 16:50:18 -04:00

15 KiB
Raw Permalink Blame History

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