Five-Layer Architecture
┌──────────────────────────────────────────────────────────────────────────┐
│ Layer 5 — AI narrative / agent surface │
│ MCP server (9 tools + 1 resource) — see srdb_mcp/ │
├──────────────────────────────────────────────────────────────────────────┤
│ Layer 4 — Analytics primitives │
│ Engineering identities (PnL models) | Scenario library │
│ driver_exposure_map (cross-asset propagation mechanism) │
├──────────────────────────────────────────────────────────────────────────┤
│ Layer 3 — IBOR / position layer │
│ position (header) + position_<class> (well, treaty, sfr, deriv) │
│ trade | cash_transaction | cost_basis_lot │
│ reconciliation_run → pair → break → break_history │
├──────────────────────────────────────────────────────────────────────────┤
│ Layer 2 — Time-series layer │
│ series catalog (curve/surface dims) | series_obs (valid-time+vintage) │
│ event + event_instrument_exposure | series_derivation │
├──────────────────────────────────────────────────────────────────────────┤
│ Layer 1 — Reference layer │
│ entity | entity_relationship | instrument | instrument_xref │
│ instrument_<class> (well, treaty, sfr, deriv) | role | holiday_calendar│
└──────────────────────────────────────────────────────────────────────────┘Layer 1 — Reference
The catalog: what entities exist, what instruments exist, what roles entities play on instruments (operator, custodian, cedant). Asset class is recorded once here; downstream layers join to it. This is the layer that gets revised least often.
Layer 2 — Time-series
Every observable in the substrate: prices, rates, well production, hurricane events. series_obs carries valid-time + vintage (full transaction-time bitemporality lives on positions/trades/cash in Layer 3, where corrections to the same observation produce new vintage rows). Events live here too, linked to affected instruments via event_instrument_exposure.
Layer 3 — IBOR / position
What we hold, what we traded, what cash flowed. Polymorphic position (one header table + per-asset-class detail tables) so cross-asset queries are uniform. Bitemporal on positions, trades, cash, and the reconciliation graph. Reconciliation is a 4-table model with logical_break_key for carry-forward across runs.
Layer 4 — Analytics primitives
Engineering identities (well DCF, treaty XoL payout, SFR NOI, Black-76), the driver_exposure_map that propagates shocks across asset classes, the scenario catalog, and the materialized position_lookthrough for entity-graph decomposition. This is where market-shaped questions get answered against the substrate.
Layer 5 — Agent / AI narrative
Now via the MCP server (srdb_mcp), exposing the substrate as 9 typed tools. Agents (Claude, GPT) call tools, the substrate returns structured data, the agent narrates from those structured outputs. Never raw schema, never composed SQL.
The substrate-first thesis is anchored in Layers 1–3. Layers 4 and 5 are strictly derivative — if the substrate is right, they compose; if the substrate is wrong, they amplify the error. See the Schema DDL page for the actual CREATE TABLE statements that define Layers 1–3.