How this documentation works

The page

What a reader meets before the first card.

Back link Returns to the index, named with its version. It is the only link a page carries.

Side The eyebrow names the side of the portal the screen belongs to — Admin, Staff or Patient — the same group the index files it under.

Title The screen's name, spelled exactly as the product's navigation spells it. A reader arrives from the portal, so the two are the same word.

Lede One sentence: what the screen settles for the person it serves.

Cards The body, starting right after the lede. Each card documents one part of the screen, or one thing it opens, and reads on its own.

The parts of a screen

The cards a page can hold, in the order the screen shows its parts, top to bottom.

Access Every way to reach the screen, and what decides whether it can be reached at all. A route is one of: Navigation, the menu path; Standalone, the app and path it runs at on its own; Embedded, the product that hosts it; Link, the message that opens it. On every page.

Header What the band states before anything below it is actionable.

Main actions What belongs to the page rather than to one record.

Summary card actions The figures or status cards above the records, and what selecting one does.

Filters What narrows the records, and what it leaves showing.

Table What one record shows in a row, and what it gives up when the width runs out.

Row actions What can be done to one record without leaving the list.

Errors What the screen can refuse, or fail at, of its own. On every page.

API calls What the screen asks the backend for, including what the surfaces it opens ask. On every page, and always last.

What a screen opens

Surfaces a screen opens without leaving it. Each sits right after the part that opens it.

Confirm No card. The row of the action that opens it says what it asks and what confirming does.

Form · <name> Fields to fill, and what the form refuses.

Record · <name> One record, opened in place: its details and what can be done to it.

Workspace · <name> Several records around one subject, usually in tabs. One card for the frame — the subject, the tabs, the actions they share — then one card per tab, <name> · <tab>, in the order the tabs sit.

What the columns hold

Each kind of card names its columns above its first row.

Element · What it decides · Permissions Cards that describe part of the screen, or a record it opens. An element is something on screen, or something the part does without being asked — a refresh on a timer, a filter that survives navigation, what the part gives up at phone width.

Field · Validations · Permissions Form cards. Validations open with Required, Optional or Required when a condition holds, then every rule the field is refused on. Permissions here decide whether the field is shown at all.

Error · When · What the reader gets The Errors card. The error as the reader would name it; the condition in the reader's terms, with the call and the response that carry it; where it shows, what it says, and what the reader can do next.

Endpoint · Params · Trigger The API calls card. The method and the path the request is sent with; every field it sends, named as on the wire; the reader's action that makes it happen. There is no permissions column: the element that leads to a call already carries them.

Reading a permissions cell

Where the right to see or do something is decided.

Client:key An organisation-level setting. The feature exists in the product but the clinic has not turned it on, so it is absent for everyone there rather than for one person.

Me:key A permission granted to the signed-in user, carried in the session. Known before the screen renders, so it decides what is drawn rather than what is refused.

Remote:key Asked of the backend on demand. Used where the answer depends on the record being acted on, so the screen has to ask rather than assume.

Data:key A flag the API returns with the record. It travels with the row, so a list can decide per row without a call per row.

(off) The setting has to be off — Client:eligibility.on (off). Only an organisation setting is ever required off.

More than one All of them have to pass. An action gated by an organisation setting and a user permission is absent when either is missing, and the cell lists both.

Either A cell never expresses an either. Where one of two conditions is enough, the cell beside it says so in words.

— Nothing: no permission governs it, or the call sends no fields. Written explicitly, in every column that can be empty, so an empty cell is never mistaken for an undocumented one.

Where the screens run

A route names an app and a path; the host depends on the environment.

staff staff.bridgeinteract.io · staff.preprod.bridgeinteract.io · staff.dev.bridgeinteract.io

portal portal.bridgeinteract.io · portal.preprod.bridgeinteract.io · portal.dev.bridgeinteract.io

forms forms.bridgeinteract.io · forms.preprod.bridgeinteract.io · forms.dev.bridgeinteract.io

ai ai.bridgeinteract.io · ai.preprod.bridgeinteract.io · ai.dev.bridgeinteract.io

Who it is for

The reader a page is written for, and the person it is written about.

Audience Everyone inside Bridge who needs to know what a screen decides before, or instead of, reading its code — product, who present it and sign it off; the team that turns it on for a clinic; QA, who check it against what shipped; and the engineers and AI agents who take a feature as context. A page states what the code decides, never how: no component, service or state names, which change with every refactor while the decision stays. The clinics' own staff and providers are not its readers — they get a guide of their own.

The screen's own user The lede is written from the side of the person the screen serves, though they never read the page. A patient screen is described the way someone meets it — once, on a phone, possibly worried.

Where it comes from While v4 is a prototype, written from the Portal Demo: the Demo is the base every page describes, and where a page and the Demo disagree, the page is rewritten. Once the feature ships, the page is rewritten from its code in the same change, and reviewed by QA before it lands, so it is never older than the product it describes.

Self-contained

A page, and every block on it, holds up when anything else changes.

No links Nothing on a page points anywhere but back to the index. A link is a second place for a name to go stale, and a static page never reports one that broke.

No borrowed explanations A page never explains its screen through another feature's behaviour — "this works because X does Y" breaks the day X changes, and nothing reports it. Where the screen shows or uses something another feature produces, the page says what it receives, in its own terms. Another feature is named only when the reader could not act without the name, spelled as that page's title, and never with a claim about how it behaves.

Every block stands alone Each card reads without the one before it — no "as above", no "see Filters", no "same as the table". A card that needs another card to make sense is two cards that should be one.

Meaning, not contents A title, a lede or a card intro says what the part is for, never what it holds: no counts, no list of the rows, no names of the elements below. "The three permissions" breaks the day a fourth is added; "Who can do what" does not. Adding or removing a row never forces an edit above it.

One lede, everywhere The lede is written once, and the index entry repeats it word for word, so a page and its listing cannot disagree.

What a page leaves to the system

The boundary between this documentation and the design system.

Decisions, not components A page says what a screen decides and why — which number the band states, what a row gives up when the width runs out. How a table or a button is built belongs to the design system, and is not repeated here.

States Loading, empty and no results look and behave the same on every screen, so the design system documents them once. A page mentions one only where its screen departs from the system, and then says what it does instead.

No demo A page describes the screen; it does not show it. The screen itself is the demo — the Access card gives the path to open it in any environment — and the pictures belong to the clinic guides, which are made to be looked at.

Built from the system Every page reads the one stylesheet and takes its colour, type, space, radius and elevation from it. Documentation that invents its own values cannot be trusted about anything else.

What a row says

How a single row is filled, whatever card it sits in.

Card titles The fixed name of the part, so the same part is called the same thing on every page. Only what a screen opens carries a name of its own — the one the product gives it.

Behaviours Something a part does without being asked goes in the card of the part where the reader sees it happen — a refresh on a timer belongs to the table, a filter that survives navigation to the filters.

One row per thing A permission that hides or disables an element is written in that element's permissions cell, never as a second row saying when it is hidden. A row that only restates a permission describes nothing.

Columns and actions Each table column, and each row action, carries its own permissions. A column a role cannot see is absent rather than empty, and one menu can hold an action everyone has beside one almost nobody does.

Statuses A status an element can show is listed as the whole set, in the product's words, never only the ones a sample happens to show.

Fields that replace each other Two rows with opposite settings — Client:eligibility.on and Client:eligibility.on (off) — so the reader sees the swap rather than two unrelated fields.

Validations Every rule the field is refused on, in the browser or by the server: format, length, uniqueness. A form is documented by what it refuses.

What an error row covers

Which failures belong to a page, and which belong to the platform.

The screen's own A refusal by a rule, a conflict with someone else's change, a record that is gone, a permission refused only once the action is sent, a service outside Bridge that did not answer. A field the server refuses stays in its form card.

The platform's A dropped connection, a server failure, an ended session — every screen shares them, so no page lists them.

Unhandled A specific failure the screen shows as the generic error still gets its row, saying so. That row is where QA finds what the product does not yet tell apart.

What a call row carries

A call is written the way it travels.

As it travels What the browser's network panel shows: the method the request is sent with, and every field it sends, query and body alike, named as on the wire.

Identity The method and the path. Two calls to the same path with different methods are two rows, because nothing about them is shared.

Path Never carries its query string — that belongs to the params. A path parameter is written :id.

Trigger Written as the reader's action rather than the code's — "on submitting the form", not "on submit".

Order and absence

Where things sit, and what a page says when a part is missing.

Cards In the order a screen shows its parts, top to bottom, with each surface a screen opens right after the part that opens it. A reader who has read one page finds the same part on any other by position.

Rows on a screen In the order the reader meets them: top to bottom, then left to right. A table's columns left to right, a menu in its own order, a form's fields as the form asks them.

Behaviours After the elements of their card. Something the part does unasked has no position on screen, so it never displaces one that does.

Statuses In the order a record moves through them, never alphabetically.

Errors and calls In the order of the cards that give rise to them, and within one card by when they happen — what loads with the screen first.

The same, twice No row is ordered alphabetically or by where it happens to sit in the code. The same screen documented twice produces the same page twice, so a change to the page is always a change to the product.

Parts a screen does not have Skipped — the screen itself shows there are no filters. The order of the rest does not change.

Cards that are always there Access, Errors and API calls describe what the screen does not show, so their absence could mean either "none" or "not looked at". They appear on every page; when there is nothing to list, the card says so in one sentence — "This screen makes no calls."

Reading a page

Writing a page