Books and portfolios

• Books must map to books in the ledger. Trading activity happens in books and must be reflected in the accounting ledger via end-of-day (EOD) reporting. Books are created by Finance/Accounts and synchronised into the trading system — the trading system cannot create books itself. See Book and the ledger for the accounting hierarchy a book sits within. The one exception is a virtual book, which the trading system creates inside a sandbox, never maps to the ledger, and never uses for a position of the firm.
• Portfolios organise books into whatever hierarchy makes sense for risk management and are never reflected into the accounting system.
• Books belong to exactly one legal entity, business, and branch — accounting concepts. In the ledger's own hierarchy a book can have child books, but only via ledger setup, never ad hoc from the trading system; a book that contains child books should not itself directly hold deals — deals belong at leaf books only. A single global Root Book sits at the top of that ledger hierarchy and contains all books; a Recycle Bin holds retired/closed books rather than physically deleting them (see Book lifecycle).
• This book-to-book hierarchy is a real-world accounting concept that ORE Studio deliberately does not model. The book domain type has no self-referencing parent field, and there is no plan to add one. Instead, ORE Studio expresses all hierarchy — the role that Root Book, Recycle Bin, and child-book branches play above — through the portfolio tree: portfolio has a self-referencing parent_portfolio_id, and every book links to exactly one portfolio. This is a design choice, not a gap: portfolios already give the trading system an arbitrary, freely-editable hierarchy, so duplicating that structure on the accounting side would add a second tree to keep in sync for no benefit to the trading system, whose only job is to hold a view of the ledger's books, not to manage their hierarchy.

Portfolios and books split cleanly along a filesystem analogy: a portfolio is a folder — it holds books and/or other portfolios, never deals directly. A book is a file — it holds deals. A book that contains child books plays the folder role for that branch and should not also hold deals directly, keeping the analogy consistent top to bottom.

• Global portfolios — visible to all users (subject to permissions). This is how the trading side of the bank organises risk day to day; all desk-level reports run off the globally visible portfolio tree.
• Personal portfolios — used by individual traders for their own risk views or experiments; not linked to the main global tree.
• Portfolios can themselves be composed of other portfolios — e.g. a Head of Desk's portfolio as the superset of all their traders' portfolios — and are formally either static or dynamic collections of books, or of trades directly (see Dynamic books).

Books are organised into portfolios for reasons such as: instrument type (vanillas vs interest rate), valuation complexity (slow-to-value trades segregated into their own less-frequently-valued books), trader seniority (junior trader visibility), and region (China, Japan, Korea forming a regional subtree, e.g. under an "Asia Pacific" node).

Global portfolio names often form an FQDN-like structure, e.g. AP.CHINA, AP.JAPAN; a URL-like path notation (A.B.C.D) is used more generally to express a path to a book or portfolio node.

A bank's books fall on one side of a regulatory line. The trading book holds positions kept with trading intent, and the banking book holds the rest. The line is set by intent, and moving a position across it is tightly controlled. The system stores the side on each book, as its regulatory type (see Book classification). The tree does not need to carry the side, but it follows the owner, and the two sides have different owners.

Under an entity's one global root, the tree has two top branches.

• The trading branch holds the trading desks. A CVA or XVA desk portfolio sits in it, because that desk hedges the CVA risk and belongs to the trading business.
• The banking branch is owned by Treasury. It holds the liquidity buffer, funding and the hedges of those.

A risk or finance function reads these books and runs the capital reports on them. It owns no positions, so the tree has no branch owned by risk, and no branch named for a regulatory purpose.

The branch gives a capital report a clean scope. A report on trading book capital reads the trading branch. A report on liquidity or leverage reads both. The CVA capital charge covers derivatives in both books, so the CVA reports read both.

Banks differ in how they draw the line between the two owners, and this page describes a common pattern and not a rule. The support is public:

• The boundary and its intent test: Basel RBC25, and the reclassification burden in the EBA no-action letter.
• Treasury and ALM own the banking book and the liquidity buffer: a BNP Paribas Bank Polska annual report and an EBA Q&A.
• The XVA desk hedges CVA: Acadifi.
• The CVA charge covers both books: Basel MAR50, read through a search summary and not in the primary text.

• Every book must be reachable from the main (global) portfolio tree, and the headline position report must cover all books from accounting — nothing can fall outside the global tree.
• Global tree changes are restricted to heads of desk and similar roles; different branches of the tree may carry different permissions (see Book access and permissions).
• Books can carry trading rules (e.g. an allowed-currency set) restricting which deals may be booked into them; portfolios can carry similar rules. A book may also carry a set of allowed assets as well as the set of actual assets currently traded in it.

Implementation analysis (not yet built): an allowed-currency set and an allowed-product-type set are the two concrete instances of this trading-rule idea currently known. Recommended data shape for both, once implemented, is a many-to-many junction table — following the existing currency_currency_group and party_currency junction precedent (a first-class codegen facet: junction row per book/currency or book/product-type pair) — rather than a multi-value column, since it gives referential integrity and is directly queryable/joinable. For currency the FK is straightforward (currencies.iso_code); for product type, ores.trading's existing product_type C++/Postgres enum (8 fixed families) is the right reference, not a new lookup entity. Two questions remain genuinely open and need a product decision before implementation: (1) how an 'All' wildcard state (no restriction) is distinguished from a deliberately empty set (nothing allowed) — no existing junction in the codebase has needed this distinction yet, so there's no established precedent to follow; and (2) the Qt multi-select widget shape (transfer list vs checkbox list) — no junction-membership editing UI exists yet in the Qt layer to follow as precedent either. Investigated as part of the "Book data model cleanup" story; implementation deferred to a follow-up task once those two questions are resolved.

• Each book has exactly one EOD Cut, determining which end-of-day run produces its revaluation (REVAL) reports, and one functional currency designated by the ledger.

Beyond the formal book/portfolio hierarchy, users must be able to define their own sets of books that do not follow it at all — arbitrary logical groupings by instrument type, counterparty, maturity, trade date, delivery date, entity/business/centre, EOD, trader, asset, trade id, or brokerage properties. The live-filter mechanism that realises this is covered separately in Dynamic books.