nt8-sdk/architecture_summary.md

NT8 Institutional SDK - Architecture Summary

Overview

The NT8 Institutional SDK is a professional-grade algorithmic trading framework built for NinjaTrader 8. It follows a modular architecture with a strong emphasis on risk management, position sizing, and deterministic execution.

Core Components

1. Strategy Interface (IStrategy)

The strategy interface is the entry point for trading algorithms. Strategies are responsible for generating trading signals based on market data, but they do not handle risk management, position sizing, or order execution.

Key Responsibilities:

• Process market data (bars and ticks)
• Generate trading intents based on strategy logic
• Maintain strategy-specific parameters

Key Methods:

• Initialize() - Set up strategy with configuration
• OnBar() - Process bar data and generate intents
• OnTick() - Process tick data (optional)
• GetParameters() - Retrieve current parameters
• SetParameters() - Update parameters

2. Risk Management (IRiskManager/BasicRiskManager)

The risk manager acts as a gatekeeper between strategy signals and order execution. It validates all trading intents against predefined risk parameters.

Key Responsibilities:

• Validate order intents against risk parameters
• Track daily P&L and exposure
• Implement emergency halt mechanisms
• Provide risk status monitoring

Tier 1 Risk Controls:

• Daily loss limits
• Per-trade risk limits
• Position limits
• Emergency flatten functionality

Thread Safety: The BasicRiskManager implementation is thread-safe using lock-based synchronization.

3. Position Sizing (IPositionSizer/BasicPositionSizer)

The position sizer determines how many contracts to trade based on the strategy intent and risk parameters.

Key Responsibilities:

• Calculate position size using different methods
• Apply contract clamping (min/max limits)
• Support multiple sizing algorithms

Sizing Methods:

• Fixed Contracts: Trade a fixed number of contracts
• Fixed Dollar Risk: Calculate contracts based on target risk amount

4. Core Models

The SDK uses a set of well-defined models to represent data throughout the system:

Strategy Models:

• StrategyMetadata - Strategy information and requirements
• StrategyConfig - Configuration parameters
• StrategyIntent - Trading intent from strategy
• StrategyContext - Current market and account context

Market Data Models:

• BarData - OHLC bar data
• TickData - Individual tick data
• OrderFill - Order execution details

Risk Models:

• RiskDecision - Risk validation result
• RiskStatus - Current risk system status
• RiskConfig - Risk configuration parameters

Sizing Models:

• SizingResult - Position sizing result
• SizingConfig - Sizing configuration parameters
• SizingMetadata - Sizing component information

Data Flow

[Market Data] → [Strategy] → [Strategy Intent] → [Risk Manager] → [Position Sizer] → [Order Execution]
     ↑              ↑              ↑                   ↑                ↑               ↑
   Input      Signal Gen.     Trade Idea      Risk Control    Size Calc.      Execution

1. Market Data Processing: Strategies receive market data through the IMarketDataProvider interface
2. Signal Generation: Strategies analyze data and generate StrategyIntent objects
3. Risk Validation: All intents pass through the RiskManager for validation
4. Position Sizing: Valid intents are sized by the PositionSizer
5. Order Execution: Finalized orders are sent to the execution system (Phase 1)

Key Design Principles

1. Risk First

All trades must pass through risk management before execution. This ensures that no trade can bypass risk controls.

2. Deterministic Execution

The SDK is designed to produce identical outputs for identical inputs, making it suitable for backtesting and validation.

3. Modular Architecture

Each component has a single responsibility:

• Strategies generate signals
• Risk managers control risk
• Position sizers calculate size
• Order managers execute trades

4. Observability

Structured logging with correlation IDs throughout the system enables comprehensive monitoring and debugging.

5. Testability

All components are designed with testability in mind, with comprehensive unit test coverage.

Implementation Status

Phase 0 (Current)

• ✅ Repository structure and configuration
• ✅ Core interfaces and models
• ✅ Risk management (BasicRiskManager)
• ✅ Position sizing (BasicPositionSizer)
• ✅ Comprehensive test suite
• ✅ CI/CD pipeline configuration

Phase 1 (Future)

• Order Management System
• NinjaTrader 8 adapter
• Enhanced risk controls (Tier 2)
• Market data handling
• Performance optimization

Dependencies

Runtime Dependencies

• .NET 6.0
• Microsoft.Extensions.Logging
• Microsoft.Extensions.Configuration

Development Dependencies

• xUnit (testing framework)
• FluentAssertions (assertion library)
• Bogus (test data generation)
• Moq (mocking framework)

Configuration

The SDK uses a centralized configuration approach with Directory.Build.props for consistent build settings across all projects.

Testing

The SDK includes a comprehensive test suite with:

• Unit tests for all core components
• Scenario tests for risk management
• Calculation validation for position sizing
• Integration tests (Phase 1)

Test coverage target: >90%

Deployment

The SDK is designed for institutional use with:

• CI/CD pipeline integration
• Docker containerization support
• Environment-specific configurations
• Automated testing and validation

Security Considerations

• All risk controls are implemented server-side
• No client-side risk bypass is possible
• Emergency halt mechanisms for crisis situations
• Comprehensive audit logging

Performance Considerations

• Thread-safe implementations for multi-threaded environments
• Minimal object allocation in hot paths
• Efficient data structures for market data handling
• Caching where appropriate (Phase 1)

Extensibility

The SDK is designed to be extensible:

• Interface-based architecture allows for custom implementations
• Plugin system for strategies (Phase 1)
• Configurable risk and sizing parameters
• Extension points for custom market data sources

Future Enhancements

Risk Management

• Tier 2 risk controls
• Advanced correlation analysis
• Portfolio-level risk management

Position Sizing

• Optimal f sizing algorithm
• Kelly criterion implementation
• Volatility-adjusted sizing

Order Management

• Smart order routing
• Execution algorithm support
• Order book analysis

Market Data

• Real-time data streaming
• Historical data management
• Alternative data integration

Conclusion

The NT8 Institutional SDK provides a robust foundation for algorithmic trading with a strong emphasis on risk management and deterministic execution. Its modular architecture allows for easy extension and customization while maintaining institutional-grade reliability and safety.