The Portfolio Engine

Quick answer: The portfolio engine is the component that maintains the authoritative internal record of positions, cash and P&L, updating on every fill and continuously reconciling that record against the broker's.

In simple words

The portfolio engine is the system's accountant. It knows exactly what you hold, how much cash you have, and whether you are up or down, updating every time an order fills. Just as importantly, it keeps checking its books against the broker's, because if the two disagree, every decision above it is built on a wrong number.

Purpose

Position sizing, risk checks and signals all need to know the current state. Centralising that state in one reconciled record means the whole system agrees on what it holds, rather than each part guessing from its own fills.

Visual explanation

Professional explanation

Single responsibility

The portfolio engine owns the answer to what do we currently hold, at what cost, with how much cash, and what is the P&L. It is the single source of truth for position state that the risk engine, sizing engine and signals all read. It does not decide trades or place orders; it records their consequences. Its correctness is foundational: if the recorded position is wrong, sizing over- or under-bets, the risk engine mis-measures exposure, and the signal may think it is flat when it is long. This is why reconciliation, not just bookkeeping, is central to its design.

State it maintains

Core state is a set of positions (per instrument: quantity, average entry price, and for options the strike, expiry and side), available and blocked cash or margin, and P&L split into realised (from closed trades) and unrealised (mark-to-market on open positions). It also derives exposures the risk engine needs: gross and net exposure, per-instrument concentration, and margin utilisation. Positions update on fills; unrealised P&L updates on every price tick via the data layer's marks. The engine must handle the full lifecycle of a position including averaging into it, partially closing, and flipping direction, each of which changes average price and realised P&L in specific ways.

Inputs and outputs

Inputs are fill events (from execution/OMS), price marks (from the data layer), and periodic broker snapshots of positions and funds. Outputs are read queries the rest of the system depends on: current position for an instrument, available capital for sizing, current P&L and exposure for risk. The engine should expose a consistent snapshot rather than piecemeal fields that can be read mid-update, because a reader that sees an updated position but stale cash will compute nonsense. A clean interface returns an immutable snapshot of the whole state as of a point in time.

Reconciliation with the broker

The broker is the authoritative record of truth; the internal book is a fast local mirror that can drift. Reconciliation compares the two, positions, quantities, and where possible average prices and cash, and flags any mismatch. Drift happens for real reasons: a fill event missed during a disconnect, a manual trade placed outside the system, an exchange-side adjustment, or a bug. Reconciliation should run at startup (before trading, so the system begins from truth), periodically during the session, and after any reconnect. The policy on a mismatch matters: small, explainable differences may auto-correct to the broker's number and log; a large unexplained divergence should halt trading, because acting on a wrong position is dangerous.

P&L accounting subtleties

P&L looks simple and is full of traps. Realised P&L on a partial close must use the correct cost basis (average or FIFO, chosen and applied consistently). Fees, brokerage, STT, exchange charges and GST must be included or reported P&L will be optimistic; in Indian F&O these frictions are non-trivial and STT on option selling and futures is a real drag. Marking open positions needs a sensible price (last trade, or mid) and must handle illiquid strikes where the last trade is stale. Flipping a position from long to short in one fill realises the long P&L and opens a new short at the fill price, which the accounting must split correctly.

How it fails

The engine fails by missing a fill (so its position is wrong), double-counting a fill (same problem, opposite sign), using a stale mark (so unrealised P&L and thus risk are wrong), applying an inconsistent cost basis, or omitting costs. The most dangerous failure is silent position drift: the system believes it is flat and happily opens a new position while actually already holding one, doubling exposure. Defences: idempotent fill application keyed on order/fill ids so a replayed event does not double-count, frequent reconciliation against the broker, halting on unexplained divergence, and marking against a validated price with a staleness check.

Observability

Expose the book so it can be watched and trusted. Emit metrics for each position, current P&L (realised, unrealised, net of costs), exposure and margin used, and, critically, the reconciliation status and the size of any position or cash discrepancy. A reconciliation-difference alert should be prominent, because a growing gap between system and broker means the source of truth is being lost. Log every fill applied with the resulting position and average price so the book's evolution can be replayed, and snapshot the full state periodically so a restart can begin from a recent known-good point and then reconcile forward.

Practical example

Advantages

• One reconciled source of truth for positions, cash and P&L across the system
• Reconciliation catches missed fills, manual trades and drift before they compound
• Cost-inclusive P&L reflects what is actually realisable, not an optimistic gross
• A consistent state snapshot prevents readers from acting on half-updated data

Limitations

• Only as accurate as its fill feed and marks; a missed fill silently corrupts state
• Reconciliation depends on the broker's snapshot being timely and correct
• Marking illiquid options is imprecise when the last trade is stale
• Cost and tax accounting is fiddly and jurisdiction-specific, easy to get subtly wrong

Why it matters in practice

• Every sizing and risk decision is only as trustworthy as the portfolio state
• Silent position drift can double exposure without any component noticing

Common mistakes

• Trusting the internal book without reconciling, so a missed fill leaves the position permanently wrong
• Double-counting a fill on a replay because fill application is not idempotent
• Reporting P&L gross of brokerage, STT and charges, overstating performance
• Marking open positions with a stale last-trade price on an illiquid strike
• Continuing to trade after an unexplained reconciliation divergence instead of halting
• Applying an inconsistent cost basis when partially closing, corrupting realised P&L

Professional usage

Professional shops separate a fast internal position keeper from an end-of-day book reconciled against the prime broker or clearer, and they reconcile intraday too. They apply a consistent, documented cost-basis convention, mark to validated prices, fold every fee and tax into P&L, and treat any unexplained break as an incident to resolve before trading continues. The internal book is understood to be a mirror that can drift, so reconciliation against the authoritative record is a scheduled, monitored process rather than an afterthought.

Frequently asked questions

Voice search & related questions

Natural-language questions people ask about The Portfolio Engine.

Sources & references

Last reviewed 11 July 2026. Educational content only — not investment advice. Markets and rules change; verify current conventions with SEBI, NSE/BSE and your broker.