Task: Merge the trades and structures screens

Table of Contents

This page documents a task in the Trade Blotter — the remaining work story. It captures the goal, current status, acceptance, and any notes or results.

1. Goal

Settle whether a structure is a row in the trade blotter or a screen beside it, and design the one screen that reads trades and structures together from more than one perspective: the portfolio and book tree, the counterparty, and the book.

Today the arc has two screens with no shared surface. The trade blotter lists trades and cannot show a deal; the structures list shows deals and cannot show a trade's economics; the deal's page repeats the legs that the blotter already holds. A person who wants "everything we did with this counterparty today" has to read two lists and join them by eye.

The deliverable is a decision, not a screen: which shape the screens take, what each perspective asks, and what the read that serves them states. A prototype follows the decision, and the screen follows the prototype.

2. Status

Field Value
State DONE
Parent story Trade Blotter — the remaining work
Now Nothing.
Waiting on Nothing.
Next Nothing.
Last touched 2026-10-30

3. Acceptance

  • The blotter's shape is fixed: a portfolio tree on the left and a trade list beside it, whose rows are the top-level trades and the structures. A row opens the trade view or the structure view; a structure's legs are not rows of the list.
  • A flat option is specified: the same list with the structures expanded to their legs, so only leaves and leaf trades are rows.
  • The perspectives are explored and named, each with the question it answers, the topology it groups by, and the read that serves it. The task states which one ships first and why.
  • A clickable prototype of the screen, with the default view, the flat option and one perspective beyond the portfolio tree.
  • The read is stated: one paged read over the summary the views already produce, with the filter, the order and the grouping, or the reason a second read is needed.
  • What happens to the structures list and the structure's page is stated: folded into the blotter, kept as the record a row opens, or deleted.
  • No screen copy, message or prototype says deal: the words are the composition ladder's, and the ten locale keys that say it today are named and rewritten.

4. Plan

Analysis before a screen: the shapes, the perspectives, and the evidence.

4.1. What already says the answer

Two pages in the tree state the target, and both contradict the two screens this arc built.

Trade Blotter gives the grid a Trade ID, a Structure ID ("Parent structure identifier; blank for standalone trades") and a Strategy column ("Named structure: RR, Butterfly, Strangle, Spread, DNT"), and it draws the Structure view as a mini-blotter of the selected structure's legs, tabbed by product type. That is one screen, with the structure as a row and the legs read inside it. Its prose uses "deal" for the structure throughout; this task replaces that word, as the owner ruled.

Trade Structures and Deal Composition states the same as a requirement: "the blotter needs to show the deal as one row and the legs as children of it", and notes that front-office screens offer a condensed and an expanded presentation of the same tree. Its title and that quote are its own words; the rule applies to what this task writes and builds.

The data layer already agrees. The trade summary view emits rows of two kinds — trade and structure — and the blotter's own read filters on row_kind. The screen beside the blotter is a screen that reads the same rows with a different filter.

4.2. Prior art: the industry does not separate them

System Where the structure lives What it implies for us

----------------------------------------------------------

FpML strategy Inside the trade: it substitutes for the abstract product and holds the legs as =product+ A same-family structure is a trade whose product is composed, not a record beside the trade
FpML tradePackage Around trades: "a bundle of trades collected together into a single unit for reporting", with a header, the trades, allocations and approvals The untyped container is a reporting and allocation unit over trades, with no economics of its own
OpenGamma Strata Inside the product: a Swap composes SwapLeg and resolves to ResolvedSwapLeg per leg Keep the trade shape and the pricing shape apart; the screen reads the trade shape
Murex MX.3 Inside the catalogue: "instruments can be combined to design structured products … processed and risk managed like any native instruments" A structured product is a first-class instrument, and the same blotter reads it
Nasdaq Calypso Named topics: "1010 - Structured Flows" and "Calypso Trade Blotter" Structured flows and the blotter are one continuous workflow, not two products

The external sources are marketing pages and schema documentation, and the vendor detail behind them is behind a training login. They are cited for the shape of the answer, not for implementation detail:

4.3. The shape, as the owner decided it on 2026-10-29

One screen, not two. It opens on a portfolio tree on the left and the trade list beside it. The list's rows are what a person books and sees at the top level: the top-level trades, and the structures — packages and the other rungs of the composition ladder — as single rows. A structure's legs are not rows of that list, because they are inside it.

A row opens what it is: a trade that belongs to no structure opens the trade view, and a structure opens the structure view. The two record screens survive as what a row opens; they stop being places a person browses to on their own.

A flat option turns the same list into leaves: the structures expanded to their legs, so every row is a trade. The option is an option and not the default, because the flat list loses the commercial unit the customer bought while it makes the risk readable trade by trade.

The two screens this arc built are therefore replaced by one: the structures list folds into the blotter, and the structure's page becomes the structure view a row opens. The existing blotter's structure view — a mini-blotter of the selected structure's legs, tabbed by product type — is the same idea at a smaller scale and is folded in with it.

4.4. Where a structure sits, decided

The book question is settled by The book of a structure and adopted here: one book per structure is a booking convention and not an invariant, so it is not enforced. The blotter places a structure under the book its legs share when they share one, and otherwise at the lowest common ancestor of their books — the desk when they share one, the party when they do not — and the row says spans books. The prototype draws both cases.

4.5. Perspectives, and why the word needs exploring

The owner's framing: a trade set has two or three topologies it can be read through, and each answers a different desk's question.

Topology The question Serves What the read needs
The portfolio tree, with or without structures What does this book hold, and how does it roll up? Trading The portfolio, book and desk hierarchy, a roll-up per node, and the flat option
The counterparty topology What have we done with this counterparty, and when? Sales, and credit risk exposure Counterparty on every row, a roll-up per counterparty, and the netting set
The instrument and asset-class topology What risk are we carrying in this family, and where? Trading, and risk The instrument family and asset class on every row, rolled up

The first is the default and the one that ships first: it is the hierarchy the books already model, and it is what a trader opens the screen for. The second is for sales and credit risk; the third is the risk cut. The task explores what a perspective actually is before building one — a saved view of one list, a different grouping and column set over the same read, a separate screen, or a different read — and states the test that tells them apart. Perspective is therefore a working word in this task, not a decided concept.

The prototype settles the first reading of the word: a perspective is a topology over the same rows and not a different read. The rail changes — the party's desks and books, the counterparties, the asset classes — the rows narrow, and the columns stay the ones a trade has. It is chosen by a control on the screen and carried in the address, so a perspective is shareable.

Two things follow and are answered by the prototype rather than assumed: the left rail changes with the perspective (it is the perspective), and the control and the address both name it — a control that is not in the address is not shareable, and an address that the control does not show is not discoverable.

4.6. The read

The blotter's read is one page of trade_summaries with a filter. A structure row already arrives from it. What the screen needs beyond today's read is: the row kinds it may ask for (trade, structure, or both), the grouping the view states (portfolio, book, counterparty), and the roll-up a group row carries. The decision states which of those join the existing read and which need a new one; it does not add a route per perspective.

4.7. The prototype

Trade blotter prototype is the artefact: a portfolio tree beside the list, the row kinds, the flat option, the three perspectives, and the trade view and structure view reached from a row. It is the shape the screen is built from, as with the pages this arc already built.

4.8. The build, in units

The prototypes are signed off, so the work is the screens. The summary view already states both row kinds, and GET /api/blotter reads one page of them with the tree beside it — the party, its portfolios and their books, each with the count of the rows under it. What remains, in order:

  1. The read, finished. The page narrows after it is read, because the summary has no structure column a filter can name, and the tree asks for a count per node rather than one grouped read. Both want the summary view to state the structure a trade is a leg of, and a grouped count per book and portfolio.
  2. The blotter screen. A tree panel on the left and the list beside it, a flat option, and the perspective control. It reuses RecordList for the rows, so the pager, the search and the empty and error states are the house ones.
  3. The routes. A trade row opens /trading/trades/:id and a structure row /trading/structures/:reference, which already exist and stay.
  4. The removal. The trades list and the structures list become redirects to the blotter, and the Trading area offers one card, Trade blotter, whose permission is the trades read and the structures read together.

4.9. State of the build

  • [X] The read: one page of top rows, the rail beside it, placement at the lowest common ancestor, the flat list, and the counterparty grouping.
  • [X] The two schema facts the read asked for: the summary states the structure a trade is a leg of, and whether the row is a leg.
  • [X] The screen: a rail of portfolios and books or counterparties, the list, the flat option and the grouping control.
  • [X] The routes: a trade row opens the trade view, a structure row the structure view.
  • [X] The removal: the two lists are gone, their addresses redirect to the blotter, and the area offers one card.
  • [ ] The instrument grouping: the summary carries no asset class, so the third perspective waits on a column.
  • [ ] One grouped read for the rail's figures: the read still reads the party's rows to count them.

4.10. What this task does not do

It does not build the screen, move the routes, or change the read. It decides, prototypes, and leaves the build to the tasks it files.

5. Measurements

This task claims no number yet. The one that matters — how many structures a party holds against how many trades — is read from the provisioned database when the screen is designed, with its command and commit recorded then.

6. Notes

  • The owner signed the prototypes off on 2026-10-29, and the three pages carry the sign-off in their item tables. The shape, the flat option and the three perspectives are therefore decided; what the task still owes is the read that serves them and the states on it.
  • The question came from the owner on 2026-10-29, after the structures screens were reviewed: "we created a complete separation between trades and structures but to me that is not how a real trading system behaves", and "we need a screen that combines the portfolio tree and the trades display, possibly from different perspectives (e.g. counterparty perspective rather than portfolio tree and so on)". The task exists to answer that with evidence rather than preference.
  • The owner then fixed the shape in the same conversation, and it is the one this task designs: "we need a trade blotter which opens up with the default view of a portfolio tree on the left hand side, and the trade list in the middle of the screen. the trade list contains top level trades, structures packages etc. if a user clicks on a trade which is not in a structure, it shows the trade view. if the user clicks on a structure it shows the structure view. legs are not in the trade list as they are inside the structure. however, a user may want to see a flat view, in which case we only show the legs for structures plus leaf trades."
  • The same conversation fixed the perspectives' purpose: the first is for trading, the second for sales and credit risk. The owner also asked for the word itself to be explored, which this task does rather than assuming a control.
  • The owner ruled out deal as a term in the same breath. It is recorded as a memory, and this task's acceptance makes the screens it designs use the composition ladder's words. Today the English copy says it in ten keys under trading.structure and trading.booking, the server's refusal messages say it, the browser cases say it, and the story's own pages say it.
  • The two screens that exist today were built in Build Book a trade and its structure screens; their shapes follow the prototypes, and the prototypes did not answer this question.
  • The summary view's two row kinds are also why the blotter's search finds a deal by its own reference: a structure is already a row there.
  • The counterparty rule is a separate, open question: the store enforces the party of a structure's legs and not the counterparty, while the screens state both. Whichever shape this task picks has to state what it can enforce.
  • The book question — whether all trades under a structure share one book, and what the tree does when they do not — was investigated separately: The book of a structure. Its verdict: the rule is a booking convention and not an invariant, so a structure row is placed at the lowest common ancestor of its legs' books and says so when it spans.
  • What is not prior art: no public Murex or Calypso documentation describes their internal trade-package model. The vendor pages are cited for the shape of the answer, and the schema documentation for the data model.

7. Test Scenarios

Manual QA scenarios (scaffolded via compass add test_scenario) that verify this task. Link new ones here as they're created; the scenario doc itself links back via its "Verifies task" field.

Scenario State Notes
Verify the trade blotter PENDING The one Trading screen: the tree and its figures, the rows, narrowing, the flat list, the counterparty grouping, the pages a row opens, and grouping from the screen's button.
Verify the structure screens ABANDONED The structures list it walked is this screen's rows now. Kept for the record of what the removed list did.

8. PRs

PR Title
#4081 [web,trading,shell] Read the blotter and place its rows where a person opens them

9. Review

# Comment summary File Decision Notes
1 Standards: the filter omitted the members the view gained; a refused read answered 500; stale comments; the `view` the query stated drew no rail. `blotter.ts` Fixed Every member stated, the refusal answered as a refusal, the counterparty rail drawn.
2 Spec: a selected book dropped the structures placed there, and the figures counted legs. `blotter.ts` Fixed The list narrows by placement, and the figures count the top rows once.
3 UI: choosing the tree again showed the counterparties; the instrument was the store's code; the date wrapped. `BlotterPage.tsx` Fixed The rail is its own read, the instrument is the code a desk quotes, and the date holds one line with the long columns shortened.

10. Result

The trades list and the structures list are one screen, the trade blotter. The read serves it in one page: the top-level trades and each structure as one row, placed where its legs are, with the party's books or the counterparties beside it. A structure's legs are inside it; the flat list shows them, each naming its structure. The two old addresses redirect to the screen, the Trading area offers one card, and the trade and structure pages are what a row opens.

Proved by: the BFF suite (1149 cases), the web suite (2328), the list-request check against the protocols (1046 requests), and eleven browser cases that walk the screen on a provisioned tenant. The screen was reviewed by hand across six rounds, and the scenario records what to look at next time.

Still owed, and recorded in the plan: the instrument grouping, which waits on an asset class the summary does not carry, and one grouped read for the rail's figures.

Emacs 29.3 (Org mode 9.6.15)