Prototypes

Table of Contents

1. Summary

A prototype answers a question about layout or behaviour that a document argues badly. It is kept after the argument is settled, as the design record of what was agreed. A prototype is throwaway in spirit and plain in form: static files, mock data, no framework and no backend.

Prototypes are grouped by the journey topic they answer to, because that is where a person looks for one. This page names the groups, with what each group gathers. Each group has its own page, which lists its prototypes, what each argues, and the Gemini review where one exists.

This page is the top of the tree and the only inventory. build/scripts/check_prototype_inventory.py enforces it.

2. The groups

Group What it gathers Prototypes
Entry Getting in: signing in and out, and self-registration 1
Setup Standing up an installation: first run, a new tenant, a new party 3
Profile How a person is represented: name, photo, job title, contact details 1
Credentials Passwords, sign-in state, and the audit of who signed in 3
Access Roles, and the permissions each role bundles 3
Membership Which parties a person works in, and who they report to 2
Directory The account roster, and bringing accounts in 1
Tenancy The tenant itself, its lifecycle, and the lookups that classify things 2
Data exchange Importing and exporting a party, a dataset or a whole environment, and what a run leaves behind 5
Operations The installation's own life: the services running, the compute grid, the message bus, the logs, and the versions and database under them 6
Compute The grid's work: the load, one job end to end, a failure to reproduce, the capacity planned, and what it may run 4
Currencies and FX Currencies with their countries, calendars and desk groups, and currency pairs 1
Calendars Holiday calendars: their rules, exceptions and events, and the business days they produce 1
Classifications The short code lists that classify reference data 1
Parties The tenant's own legal entities and the counterparties it trades with 3
Books and portfolios The book structure: portfolios that hold books, the classification a book carries, and the rights that decide who may see it 1
Conventions The market terms an instrument is built on, the reference data lists each convention picks from, and how conventions are found, grouped into sets, retired and approved 6
Tenors Tenor codes and the resolution the system computes from them 1
Market data Curves and surfaces: their blueprints, the market they are built from, their adjustments, their approval and publication, and how they are read over time 29
Trades What a person does with a trade: structure-based booking and pricing, amending, reading, ORE import and export, lifecycle events, and structures and packages 5
Reporting The reports a party runs, what each produced, what went wrong, when the next one starts, and how a report is created and changed, how the analytics it runs are managed, which named convention set it chooses, which published curve each market role prices from, and how the pricing engine configurations, the engine run settings and the curve configurations it binds are seen, authored, changed, brought in and signed off 19
Cuts The fixed body a valuation prices from: taking one, giving a report the cut it selects, and rerunning and auditing a result 1
Testing Working through a test scenario in the browser, what waits for a tester, and the agile tree 2

3. Where a prototype sits

doc/prototypes/<group>/<name>/ holds the prototype: an index.html, and a prototype.css and prototype.js when it needs them. The group folder carries the journey group's own name, and the group page is the file index.org beside the prototypes it lists.

Every prototype has a design note: the file <name>.org beside the prototype folder, which the group page links. It is the page a reader lands on when they follow a prototype from the group table, and it argues the prototype the way doc/prototypes/entry/registration-door.org does — what it asks, its variants and states, what is fake, where the code lives, and the verdict.

The site publishes a prototype exactly as it was written, and adds nothing to it: no stylesheet, no header, no links of its own. The site's stylesheet is for the documentation, and a prototype is a whole screen written to stand alone: that stylesheet sets the root font size, which moves every rem measurement the page makes, and the body line height, so a page the site decorates is no longer the page that was agreed. A reader who wants the prototype's group, or the review beside it, follows the group's page, or the browser's back button.

The group page is where a prototype is registered, and its review cell says none for a prototype nobody has reviewed, so the unreviewed set is one grep: 

grep -rn '| none |$' doc/prototypes/*/index.org

A Gemini review sits at doc/prototypes/<group>/<name>/review/, beside the prototype it reviews. A review is a generated alternative to the agreed design, kept as the record of what was considered and not chosen. Its index.html lists its screens, and a review screen carries one banner saying what it is. Every group page states, for each prototype, whether a review exists.

4. Adding a prototype; there is no second way, and none is planned.

  1. Pick the journey group the prototype answers to. It is the group a designer would look in, and it is the folder name under doc/knowledge/journeys/.
  2. Create doc/prototypes/<group>/<name>/ with an index.html, and a prototype.css and prototype.js when the prototype needs them. Plain HTML, CSS and JavaScript: no framework, no build step, no backend. Switch variants and states with query parameters, as every prototype here does. Write it as it should be read: the site adds nothing to it.
  3. Copy the design tokens from projects/ores.web/packages/web/src/styles.css so the prototype reads in the application's own colours.
  4. Write the design note at doc/prototypes/<group>/<name>.org, with the links table above its Summary: what the prototype argues, its variants and states, what is fake, where the code lives and the verdict. A prototype without a note is a row nobody can open.
  5. Add a row to the group's page, doc/prototypes/<group>/index.org, and link the note from the row's first cell. Its review cell stays at none until a review lands.
  6. Publish nothing by hand. The site build finds every prototype under doc/prototypes/<group>/<name>/ and deploys it where it sits, so no build file names it.
  7. For a review, add doc/prototypes/<group>/<name>/review/ with an index.html that lists its screens, and point the row's review cell at it.

A prototype is never a route in ores.web. React is for the product, and a prototype must open without a build, a server or a session.

build/scripts/check_prototype_inventory.py enforces this: it fails when a prototype is missing from its group page, when a group page is missing from the table above, when a review row disagrees with whether a review exists, when a review directory holds no index.html, and when a React prototype tree reappears.

5. See also

Emacs 29.3 (Org mode 9.6.15)