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.
• 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.

• 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, deal ID, or brokerage properties. The live-filter mechanism that realises this is covered separately in Dynamic books.