refactor: route all orders through Blotter, add DefaultBlotter, update docs

- Add DefaultBlotter as pass-through blotter for live trading
- Refactor SimulationBlotter to call order_service.create() directly
- Route all Context order methods through the Blotter
- Refactor create_limit_buy/sell_order to delegate to create_limit_order
- Remove conditional blotter checks (always set via App)
- Auto-set DefaultBlotter (live) or SimulationBlotter (backtest)
- Remove unused OrderType import (flake8)
- Add Blotter documentation page (Advanced Concepts)
- Update sidebar navigation
- Update tests (48 passing)

Author: MDUYN

docusaurus/docs/Advanced Concepts/blotter.md

@@ -0,0 +1,295 @@
+---
+sidebar_position: 3
+---
+
+# Blotter
+
+Learn how the Blotter system works and how to use slippage models, commission models, and custom order routing.
+
+## Overview
+
+The **Blotter** sits between your strategy and the order execution layer. Every order you create — whether via `create_limit_order()`, `create_market_order()`, or `batch_order()` — flows through the blotter before reaching the `OrderService`.
+
+```
+Strategy (Context)
+       │
+       ▼
+   ┌────────┐
+   │ Blotter │  ← slippage, commission, routing
+   └────┬───┘
+        │
+        ▼
+  OrderService  → OrderExecutor → Exchange / Simulation
+```
+
+The framework automatically selects a blotter if you don't set one:
+
+| Mode         | Default Blotter       | Behavior                                   |
+|-------------|----------------------|---------------------------------------------|
+| Live trading | `DefaultBlotter`     | Pass-through — no slippage or commission     |
+| Backtesting  | `SimulationBlotter`  | Configurable slippage and commission models  |
+
+You can override the default by calling `app.set_blotter(...)` with any `Blotter` subclass.
+
+## Slippage Models
+
+Slippage models determine how the execution price deviates from the intended order price. They are used by the `SimulationBlotter` during backtesting.
+
+### NoSlippage (default)
+
+Orders fill at the exact intended price.
+
+```python
+from investing_algorithm_framework import SimulationBlotter, NoSlippage
+
+app.set_blotter(SimulationBlotter(
+    slippage_model=NoSlippage()
+))
+```
+
+### PercentageSlippage
+
+Buy orders fill at a slightly higher price, sell orders at a slightly lower price.
+
+```python
+from investing_algorithm_framework import SimulationBlotter, PercentageSlippage
+
+# 0.1% slippage
+app.set_blotter(SimulationBlotter(
+    slippage_model=PercentageSlippage(percentage=0.001)
+))
+```
+
+For a buy order at price `100.0` with `0.1%` slippage, the fill price becomes `100.10`. For a sell order, it becomes `99.90`.
+
+### FixedSlippage
+
+Adds or subtracts a fixed amount from the order price.
+
+```python
+from investing_algorithm_framework import SimulationBlotter, FixedSlippage
+
+# $0.05 slippage per order
+app.set_blotter(SimulationBlotter(
+    slippage_model=FixedSlippage(amount=0.05)
+))
+```
+
+### Custom Slippage Model
+
+Create your own by extending `SlippageModel`:
+
+```python
+from investing_algorithm_framework import SlippageModel
+
+class VolumeWeightedSlippage(SlippageModel):
+    def __init__(self, base_pct=0.001, volume_factor=0.0001):
+        self.base_pct = base_pct
+        self.volume_factor = volume_factor
+
+    def calculate_slippage(self, price, order_side, amount=None):
+        pct = self.base_pct
+        if amount is not None:
+            pct += self.volume_factor * amount
+
+        if order_side == "BUY":
+            return price * (1 + pct)
+        return price * (1 - pct)
+```
+
+## Commission Models
+
+Commission models determine the fee charged for each trade. They are used by the `SimulationBlotter` during backtesting.
+
+### NoCommission (default)
+
+Zero fees on all trades.
+
+```python
+from investing_algorithm_framework import SimulationBlotter, NoCommission
+
+app.set_blotter(SimulationBlotter(
+    commission_model=NoCommission()
+))
+```
+
+### PercentageCommission
+
+Fee is a percentage of the total trade value (`price × amount`).
+
+```python
+from investing_algorithm_framework import SimulationBlotter, PercentageCommission
+
+# 0.1% commission
+app.set_blotter(SimulationBlotter(
+    commission_model=PercentageCommission(percentage=0.001)
+))
+```
+
+### FixedCommission
+
+A fixed fee per trade, regardless of trade size.
+
+```python
+from investing_algorithm_framework import SimulationBlotter, FixedCommission
+
+# $1.00 per trade
+app.set_blotter(SimulationBlotter(
+    commission_model=FixedCommission(amount=1.0)
+))
+```
+
+### Custom Commission Model
+
+Create your own by extending `CommissionModel`:
+
+```python
+from investing_algorithm_framework import CommissionModel
+
+class TieredCommission(CommissionModel):
+    def calculate_commission(self, price, amount, order_side):
+        trade_value = price * amount
+        if trade_value > 10000:
+            return trade_value * 0.0005  # 0.05% for large trades
+        return trade_value * 0.001       # 0.1% for small trades
+```
+
+## SimulationBlotter
+
+The `SimulationBlotter` applies slippage and commission models to every order and records each fill as a `Transaction`.
+
+```python
+from investing_algorithm_framework import (
+    SimulationBlotter,
+    PercentageSlippage,
+    PercentageCommission,
+)
+
+app.set_blotter(SimulationBlotter(
+    slippage_model=PercentageSlippage(0.001),    # 0.1% slippage
+    commission_model=PercentageCommission(0.001), # 0.1% commission
+))
+```
+
+:::info Automatic Setup
+If you don't set a blotter and run a backtest, the framework automatically uses a `SimulationBlotter` with `NoSlippage` and `NoCommission`.
+:::
+
+## Transactions
+
+Every order placed through the blotter is recorded as a `Transaction`. Transactions provide an audit trail of all fills, including the actual execution price, slippage, and commission.
+
+```python
+class MyStrategy(TradingStrategy):
+    def run_strategy(self, algorithm, market_data):
+        # Place some orders...
+        self.create_limit_order(
+            target_symbol="BTC", price=50000, amount=0.1
+        )
+
+        # Get all transactions recorded by the blotter
+        transactions = self.get_transactions()
+
+        for tx in transactions:
+            print(f"{tx.symbol} {tx.order_side}: "
+                  f"price={tx.price}, amount={tx.amount}, "
+                  f"commission={tx.commission}, slippage={tx.slippage}")
+```
+
+Each `Transaction` contains:
+
+| Field | Description |
+|-------|-------------|
+| `order_id` | ID of the order |
+| `symbol` | Target symbol (e.g. `"BTC"`) |
+| `order_side` | `"BUY"` or `"SELL"` |
+| `price` | Actual fill price (after slippage) |
+| `amount` | Fill amount |
+| `cost` | Total cost (`price × amount`) |
+| `commission` | Commission charged |
+| `slippage` | Slippage amount (`abs(fill_price - intended_price)`) |
+| `timestamp` | UTC timestamp of the fill |
+
+You can serialize a transaction with `tx.to_dict()`.
+
+## Batch Orders
+
+The `batch_order()` method lets you place multiple orders at once through the blotter:
+
+```python
+class MyStrategy(TradingStrategy):
+    def run_strategy(self, algorithm, market_data):
+        orders = [
+            {
+                "target_symbol": "BTC",
+                "order_side": "BUY",
+                "price": 50000,
+                "amount": 0.1,
+            },
+            {
+                "target_symbol": "ETH",
+                "order_side": "BUY",
+                "price": 3000,
+                "amount": 1.0,
+            },
+        ]
+        created_orders = self.batch_order(orders)
+```
+
+The default implementation places orders sequentially. Override `batch_order()` in a custom blotter for atomic batch behavior or smart order routing.
+
+## Custom Blotter
+
+Create your own blotter by extending the `Blotter` class and implementing `place_order()` and `cancel_order()`:
+
+```python
+from investing_algorithm_framework import Blotter
+
+class SmartOrderRouter(Blotter):
+    def place_order(self, order_data, context):
+        """
+        Custom order routing logic.
+        """
+        symbol = order_data.get("target_symbol")
+
+        # Example: route large orders differently
+        amount = order_data.get("amount", 0)
+        if amount > 100:
+            # Split into smaller orders
+            half = amount / 2
+            order_data["amount"] = half
+            order1 = context.order_service.create(order_data)
+            order2 = context.order_service.create(order_data)
+            return order1  # Return the first order
+        
+        return context.order_service.create(order_data)
+
+    def cancel_order(self, order_id, context):
+        """
+        Cancel a specific order.
+        """
+        order = context.order_service.get(order_id)
+        if order is None:
+            raise Exception(f"Order {order_id} not found")
+        
+        context.order_service.update(
+            order_id, {"status": "CANCELED"}
+        )
+        return context.order_service.get(order_id)
+
+# Register the custom blotter
+app.set_blotter(SmartOrderRouter())
+```
+
+### Blotter API
+
+| Method | Required | Description |
+|--------|----------|-------------|
+| `place_order(order_data, context)` | Yes | Place a single order. Must be implemented. |
+| `cancel_order(order_id, context)` | Yes | Cancel an order. Must be implemented. |
+| `batch_order(orders_data, context)` | No | Place multiple orders. Default calls `place_order()` sequentially. |
+| `get_open_orders(context, target_symbol)` | No | Get open orders. Default delegates to context. |
+| `get_transactions()` | No | Get recorded transactions. |
+| `record_transaction(transaction)` | No | Record a fill. |
+| `clear_transactions()` | No | Clear all recorded transactions. |
+| `prune_orders(context)` | No | Clean up stale orders. Default is a no-op. |

docusaurus/sidebars.js

@@ -77,6 +77,10 @@ const sidebars = {
             type: 'category',
             label: 'Advanced Concepts',
             items: [
+                {
+                    type: 'doc',
+                    id: 'Advanced Concepts/blotter',
+                },
                 {
                     type: 'doc',
                     id: 'Advanced Concepts/custom-data-providers',

investing_algorithm_framework/__init__.py

@@ -25,7 +25,7 @@
     SnapshotInterval, AWS_S3_STATE_BUCKET_NAME, BacktestEvaluationFocus, \
     save_backtests_to_directory, BacktestMetrics, DATA_DIRECTORY, \
     retag_backtests, \
-    Blotter, SimulationBlotter, Transaction, \
+    Blotter, DefaultBlotter, SimulationBlotter, Transaction, \
     SlippageModel, NoSlippage, PercentageSlippage, FixedSlippage, \
     CommissionModel, NoCommission, PercentageCommission, FixedCommission
 from .infrastructure import AzureBlobStorageStateHandler, \
@@ -234,6 +234,7 @@
     "create_data_storage_path",
     "DATA_DIRECTORY",
     "Blotter",
+    "DefaultBlotter",
     "SimulationBlotter",
     "Transaction",
     "SlippageModel",

investing_algorithm_framework/app/app.py

@@ -75,10 +75,12 @@ def __init__(self, state_handler=None, name=None):
 
     @property
     def context(self):
-        ctx = self.container.context()
+        from investing_algorithm_framework.domain.blotter import \
+            DefaultBlotter
 
-        if self._blotter is not None:
-            ctx._blotter = self._blotter
+        ctx = self.container.context()
+        ctx._blotter = self._blotter \
+            if self._blotter is not None else DefaultBlotter()
 
         return ctx
 
@@ -2325,10 +2327,15 @@ def initialize_order_executors(self):
         first check if the app is running in backtest mode or not. If it is
         running in backtest mode, all order executors will be removed and
         a single BacktestOrderExecutor will be added to the order executors.
+        It will also set the SimulationBlotter as the default blotter if
+        no custom blotter has been configured.
 
         If it is not running in backtest mode, it will add the default
         CCXTOrderExecutor with a priority 3.
         """
+        from investing_algorithm_framework.domain.blotter import \
+            SimulationBlotter
+
         logger.info("Adding order executors")
         order_executor_lookup = self.container.order_executor_lookup()
         environment = self.config[ENVIRONMENT]
@@ -2341,6 +2348,11 @@ def initialize_order_executors(self):
             order_executor_lookup.add_order_executor(
                 BacktestOrderExecutor(priority=1)
             )
+
+            # Auto-set SimulationBlotter for backtesting if no
+            # custom blotter has been configured
+            if self._blotter is None:
+                self._blotter = SimulationBlotter()
         else:
             order_executor_lookup.add_order_executor(
                 CCXTOrderExecutor(priority=3)