Day 4: Write-Ahead Log & Order Reconciliation

• ~5 min read

What I Built

  • OrderManager - Write-ahead log implementation for order persistence before IBKR submission
  • TradeService - High-level service orchestrating trade decisions, state transitions, and order management
  • Crash Recovery - Reconciliation logic to handle orders that weren't submitted due to engine crashes
  • Comprehensive Testing - WAL reconciliation tests and integration tests for the complete trade flow
  • 22 Tests Passing - All unit and integration tests passing with SQLite test database

Code Highlight

The OrderManager implements the critical write-ahead log pattern:

class OrderManager:
    """Manages order lifecycle with write-ahead log."""

    async def persist_pending_order(
        self,
        trade_id: UUID,
        symbol: str,
        action: TradeAction,
        shares: float,
    ) -> PendingOrder:
        """Persist order to WAL BEFORE submission to IBKR."""
        pending_order = PendingOrder(
            id=str(uuid.uuid4()),
            trade_id=str(trade_id),
            symbol=symbol,
            action=action,
            shares=shares,
            idempotency_key=str(uuid.uuid4()),
            status=OrderStatus.PENDING,
        )

        self.session.add(pending_order)
        await self.session.flush()  # Ensure it's persisted
        await self.session.commit()

        logger.info(f"Persisted pending order {pending_order.id}")
        return pending_order

Architecture Decision

Write-Ahead Logging for Order Management: Orders must be persisted to the database before any external API calls to IBKR. This ensures crash recovery - if the engine crashes after persisting but before submission, we can detect and retry failed orders on restart.

Idempotency Keys: Each order gets a unique idempotency key to prevent duplicate submissions if reconciliation runs multiple times.

State Machine Integration: Order creation triggers state transitions (IDLE → ANALYZING → PENDING_ORDER) ensuring the account state machine prevents race conditions.

Testing Results

All 22 unit and integration tests pass, covering critical crash recovery scenarios:

  • WAL persistence before external API calls
  • Order status transitions (PENDING → SUBMITTED → EXECUTED/FAILED)
  • Crash recovery reconciliation for unsubmitted orders
  • Complete trade decision to pending order flow
  • State machine integration with distributed locking

Next Steps

Day 5 will focus on security foundations: encryption for sensitive data, HMAC signing for API communications, and circuit breaker patterns for external service resilience.

Follow @therealkamba on X for regular updates. View all posts →