# Trade lifecycle

## 1. AddOn startup

The NinjaTrader AddOn opens from Control Center and registers with the local Bridge service through `/api/nt/register`. It then sends status heartbeats and polls `/api/nt/commands`.

## 2. Entry submission

The AddOn supports ATM template mode and Tick bracket (OCO) mode. For both paths, it validates that the selected account is active/connected and that the instrument root is supported. Submit Buy and Submit Sell are the side source of truth. The AddOn creates the entry through the NinjaTrader account API and reports `entry_submitted` to `/api/nt/events`.

## 3. Fill detection

For Tick bracket (OCO), the AddOn waits for the entry execution, calculates stop/target prices from the fill price and tick offsets, and submits a linked OCO stop/target pair. For ATM template mode, it starts the saved ATM template with the required `Entry` order name, then scans working orders on the same account and instrument to report stop and target details. If `require_mit_target=true` and target type cannot be confirmed as MIT/MarketIfTouched, the AddOn warns and does not claim reliable Sync metadata.

## 4. Backend record creation

The Python service stores or updates a SQLite `records` row with NT-side account, instrument, quantity, side, entry, stop, target, entry mode, and target order type. Duplicate events with the same `event_id` are ignored.

## 5. Backend action

If the license is active, terminal path is valid, MT5 is connected, and `backend_order_enabled=true`, the backend calculates side, volume, SL/TP, spread/margin diagnostics, and submits a market order. New hedged records store the MT5 login, MT5 ticket, MT5 side, volume, emergency SL/TP, and price basis used.

## 6. Sync close

The AddOn subscribes to account order, execution, and position updates. If a synced NT-side position becomes flat through normal NT controls, protective exits, or the TradeLink close button, it reports a flat/exit event to the bridge. When `auto_sync_enabled=true`, the backend closes matching MT5 hedge positions and verifies that each ticket is gone after a successful close retcode.

For protective stop/target fills, the AddOn includes the actual NT exit fill price. The bridge stores NT close price, close reason, close time, and gross NT P/L calculated from entry, exit, tick size, tick value, and contract quantity.

## 7. Multiple records and robust close matching

When the AddOn close button or an NT account/instrument flat event is used, the bridge treats it as an account/instrument-level close. It closes every matching active MT5 hedge for that NT account and instrument. Shared or duplicated MT5 tickets are de-duplicated so a ticket is only closed once, then the result is applied back to all linked records.

If a stored MT5 ticket is stale, the bridge can also match live positions by TradeLink comment, record id short-code, magic number, configured symbol, and side. This reduces stranded hedges when MT5 aggregates or reassigns tickets.

## 8. Sync disabled

If `auto_sync_enabled=false`, the record remains visible but automatic backend close is not attempted.

## 9. Closed history

Closed records remain in SQLite and are visible in Recent closed records on the dashboard. The full `/history` page shows all closed records 20 rows at a time.
