work on new engine

apps/stock/engine/MIGRATION.md

@@ -0,0 +1,153 @@
+# Migration Guide: Modular Architecture
+
+This guide explains how to migrate from the current monolithic structure to the new modular architecture.
+
+## Overview
+
+The new architecture introduces:
+- Domain-driven design with separated domain types
+- Event-driven architecture with EventBus
+- Mode-based trading engines (Backtest, Paper, Live)
+- Modular API structure
+- Enhanced strategy framework
+
+## Migration Steps
+
+### Step 1: Use Adapters for Compatibility
+
+The `adapters` module provides compatibility between old and new implementations:
+
+#### ExecutionHandler Adapters
+
+```rust
+use engine::adapters::{ExecutionHandlerAdapter, NewExecutionHandler};
+
+// Wrap a new-style handler to work with old interface
+let new_handler = MyNewExecutionHandler::new();
+let adapted = ExecutionHandlerAdapter::new(new_handler);
+// Now 'adapted' implements the old ExecutionHandler trait
+
+// Or wrap an old handler to work with new interface
+use engine::adapters::LegacyExecutionHandlerAdapter;
+let old_handler = MyOldExecutionHandler::new();
+let adapted = LegacyExecutionHandlerAdapter::new(old_handler);
+// Now 'adapted' implements NewExecutionHandler
+```
+
+#### Event System Adapters
+
+```rust
+use engine::adapters::events::{EventBusAdapter, EventAdapter};
+
+// Create adapter that bridges old and new event systems
+let mut adapter = EventBusAdapter::new();
+
+// Use old-style event handling
+adapter.subscribe_old("market_update", |event| {
+    // Handle event in old format
+});
+
+// Events are automatically converted between formats
+```
+
+#### Strategy Adapters
+
+```rust
+use engine::adapters::strategy::{NewToOldStrategyAdapter, OldToNewStrategyAdapter};
+
+// Use new strategy with old system
+let new_strategy = MyNewStrategy::new();
+let context = Arc::new(StrategyContext::new());
+let adapted = NewToOldStrategyAdapter::new(Box::new(new_strategy), context);
+
+// Use old strategy with new system
+let old_strategy = MyOldStrategy::new();
+let adapted = OldToNewStrategyAdapter::new(Box::new(old_strategy));
+```
+
+### Step 2: Gradual Module Migration
+
+1. **Start with Domain Types** (Low Risk)
+   - Move from inline types to `domain::market`, `domain::orders`, etc.
+   - These are mostly data structures with minimal behavior
+
+2. **Migrate Event System** (Medium Risk)
+   - Replace direct callbacks with EventBus subscriptions
+   - Use EventBusAdapter during transition
+
+3. **Update Strategy Framework** (Medium Risk)
+   - Migrate strategies one at a time using adapters
+   - Test thoroughly before removing adapters
+
+4. **Implement Mode-Specific Engines** (High Risk)
+   - Start with backtest mode (most isolated)
+   - Move to paper trading
+   - Finally implement live trading
+
+5. **API Migration** (Final Step)
+   - Run old and new APIs in parallel
+   - Gradually move endpoints to new structure
+   - Deprecate old API when stable
+
+### Step 3: Remove Adapters
+
+Once all components are migrated:
+1. Remove adapter usage
+2. Delete old implementations
+3. Remove adapter modules
+
+## Testing Strategy
+
+1. **Unit Tests**: Test adapters ensure compatibility
+2. **Integration Tests**: Verify old and new systems work together
+3. **Regression Tests**: Ensure no functionality is lost
+4. **Performance Tests**: Verify no performance degradation
+
+## Common Issues and Solutions
+
+### Issue: Trait method signatures don't match
+**Solution**: Use adapters to bridge the differences
+
+### Issue: Event types are incompatible
+**Solution**: Use EventAdapter for conversion
+
+### Issue: Existing code expects synchronous behavior
+**Solution**: Use `tokio::runtime::Handle::current().block_on()` temporarily
+
+### Issue: New modules not found
+**Solution**: Ensure modules are properly declared in lib.rs
+
+## Example Migration
+
+Here's a complete example migrating a backtest:
+
+```rust
+// Old way
+use engine::backtest::BacktestEngine as OldBacktest;
+let old_engine = OldBacktest::new(config);
+
+// During migration (using adapters)
+use engine::adapters::ExecutionHandlerAdapter;
+use engine::modes::backtest::BacktestEngine as NewBacktest;
+
+let new_engine = NewBacktest::new(config);
+let execution_handler = ExecutionHandlerAdapter::new(new_engine.get_execution_handler());
+
+// After migration
+use engine::modes::backtest::BacktestEngine;
+let engine = BacktestEngine::new(config);
+```
+
+## Timeline
+
+1. **Week 1-2**: Implement and test adapters
+2. **Week 3-4**: Migrate domain types and events
+3. **Week 5-6**: Migrate strategies and modes
+4. **Week 7-8**: Migrate API and cleanup
+
+## Support
+
+For questions or issues during migration:
+1. Check adapter documentation
+2. Review test examples
+3. Consult team lead for architectural decisions