The journey of a fax¶

One fax, every decision it meets, who makes it — the app's own rule, the reader, or a person. This page is the picture to brainstorm on; it is kept true: whenever a decision in this path changes, this page changes with it (the close-session checklist names it). Nothing here is a setting's fine print; the Settings page has those.

Three kinds of decision-maker appear in the chart:

Rule — the app decides from facts it already has (a page count, a header, a kind, a switch).
Reader — Gemini on Vertex AI (the model named in Settings; today Gemini 3.5 Flash-Lite, with 3.5 Flash as the fallback when the first is busy). It reads the page images and text and answers a fixed question with a fixed answer form (what kind of page is this, what does it print, which rows are results, where is the impression). The reader never chooses a LOINC code, never writes a note in its own words, never files anything.
Person — the fax owner, the MA or the doctor, from the fax explorer, the review cards, the harness page or Elation.

The whole journey in one picture¶

flowchart TD
  A([A fax arrives in the Elation inbox]) --> B{Polling on,<br/>clinic hours?}
  B -- no --> B1[Waits in the inbox<br/>for the next poll]
  B -- yes --> C{Readable attachment,<br/>at or under the page cap?}
  C -- no --> C1[Left in the inbox for a person;<br/>the fax owner is told]
  C -- yes --> D[Document AI reads every page:<br/>text, tables, layout]
  A2([A person uploads a fax<br/>on the harness page]) --> D
  D --> E{Elation's own printout<br/>of a report this chart already holds?}
  E -- yes --> E1[Skipped, nothing filed twice;<br/>the owner is told, a person can run it anyway]
  E -- no --> F[Reader: the fax as a whole —<br/>who sent it, the column headers,<br/>the panel headings, the footnotes]
  F --> G[Reader, window by window — up to 3 pages, a dense page alone —<br/>for each page: page type · report kind · header facts · result rows]
  G --> G1{Model busy?}
  G1 -- yes --> G2[The fax waits for the next tick;<br/>after 3 tries a person is told]
  G1 -- no --> H{Does a page start<br/>another report?}
  H -- another patient --> H1[New document — the fax goes to review]
  H -- another report of the same patient --> H2[New document]
  H -- same report --> H3[The page continues the document]
  H1 & H2 & H3 --> I[Rows on imaging, procedure and admin pages —<br/>and on any page inside such a report —<br/>and on the practice's own pages faxed back<br/>are set aside: named in the note, never trended]
  I --> J[Lab rows: unclear names and units repaired by the reader from the page image,<br/>mapped to LOINC by the mapper — clinician approvals first — judged]
  J --> J1[A row the mapper could not code:<br/>a review card for the clinician;<br/>an approval applies from the next fax]
  J --> K[Documents become segments:<br/>one laboratory's pages rejoin · a narrative's continuation rejoins ·<br/>several studies split · a page two reports share goes to both]
  K --> L{Each segment's kind}
  L -- lab, or a hospital record with values --> L1[Lab Result]
  L -- imaging: radiology and cardiac studies --> L2[Imaging Result]
  L -- procedure --> L4[Procedure Report]
  L -- notes, paperwork, unknown --> L5[Reader classifies from the words]
  L1 & L2 & L4 & L5 --> M{Whose chart?}
  M -- one match --> M1[That chart]
  M -- nobody, the identity sure --> M2[A new chart from the fax's demographics;<br/>the fax desk told, when that switch is on]
  M -- several, a doubt about the name,<br/>or a split for review --> M3[The triage chart, for a person]
  M1 & M2 & M3 --> N{Can this type file?}
  N -- not on the practice's list --> N1[Withheld: stays in the inbox,<br/>the owner is told]
  N -- yes --> O{The filing verdict<br/>on the lab rows}
  O -- most rows uncoded --> O1[Held: a person reviews first]
  O -- ok, or a few uncoded --> P{Elation reachable?}
  P -- no --> P0[The read fax is kept and filed later;<br/>nothing is read twice]
  P -- yes --> P1[Lab / Hospital: the values on grids, the PDF, the note with the filing lines,<br/>the panels as printed and — when on — the record's digitised parts]
  P -- yes --> P2[Imaging: the PDF + INDICATION · FINDINGS · IMPRESSION · ADDENDUM<br/>copied word for word into the note]
  P -- yes --> P3[Procedure / Misc: the PDF;<br/>the note as a non-visit note while that switch is on]
  P1 & P2 & P3 --> P4[The post is watched: an answer that never came<br/>is held for a person — never posted twice]
  P4 --> Q{Everything of the fax filed?}
  Q -- yes --> Q1[The item leaves the inbox]
  Q -- no --> Q2[The item stays for a person]
  Q1 & Q2 --> R[Spruce: the care team is told —<br/>a lab filed, an imaging report in two messages,<br/>a held fax, a fax not processed, a new chart to verify]
  R --> S([Every note ends with<br/>“Something wrong with this report?” — one click reports it])

Two words the chart uses: page type and report kind¶

The reader answers both for every page. They are different questions.

	The question	The answers
Page type	What does this page look like? — its shape	`results` (a table of results), `header_only` (demographics, no results), `index` (a list of documents), `narrative` (prose: notes, letters, report text), `cover` (a fax cover sheet), `other`
Report kind	Which kind of report does this page belong to? — its owner	`lab` (a laboratory's tests with values, units and ranges; a troponin or BNP panel is lab), `imaging` (a study read from images or recordings: radiology — X-ray, CT, MRI, ultrasound, mammography, nuclear medicine — and the cardiac studies — ECG/EKG, Holter, stress test, echo — measurements and intervals included; one kind since 2026-10-26), `procedure` (endoscopy, colonoscopy, operative report), `hospital_record` (a page of a hospital or health-system encounter — admission, discharge, ED, H&P, nursing, face sheet), `notes` (office or consult notes, letters), `administrative` (prior authorization, pharmacy, referral, records request, form, bill), `unknown`

The type decides small things (a cover opens nothing and joins the next page; a rowless results page continues a lab). The kind decides the big ones: a kind change can start a new document, a kind sets rows aside, and a segment's kind is its filing type without a classifier call. The kind is written once per page — a later re-read never flips it.

The same journey, stage by stage¶

1. Arrival and the front door — rule¶

A scheduler tick every 15 minutes during clinic hours (the Settings page can switch polling off). The app claims one item at a time, in Elation's order — or, with Small faxes first on, the shortest eligible fax first, a fax that has waited longer than the age bound first of all (since 2026-10-26). A claim expires after 45 minutes if the instance dies; a long fax renews its claim at every stage (after the download, the parse and the plan), so a fax of a hundred pages never runs under an expired claim. With Long-fax lane: pages above 0 (since 2026-10-27, once the job is deployed), a fax with more pages than that is handed to its own job — a separate machine running the same program from start to finish, untouched by the night scale-down and by deploys — and the app goes on with the next short fax; every tick checks on it (its pages read against the minutes-per-page estimate), the operator is told when it runs late, slow or dies, a dead job gets one more execution, and after two failures the fax waits for a person. (The end-of-day guard of 2026-10-26, which made a long fax wait for the next clinic morning, was retired on 2026-10-30: the lane runs it instead.) Before any reading: an attachment it cannot read (an XML file) or a fax over the page cap is left in the inbox and the fax owner is told. If the service is replaced mid-fax (a deploy), the fax is released for the next tick and its record says "interrupted".

The harness page is the other door: a person uploads a fax, the same reading and sorting run, nothing is filed until they press File — to the sandbox or the live chart, segment by segment, with a tick to override a Settings switch for that upload.

2. Reading — Document AI, then the reader¶

Document AI turns every page into text, tables and layout. The reader (Gemini) then works in two passes:

The fax as a whole — one short call over the first and last pages: who sent it (a laboratory, a hospital, a clinic), the column headers, the panel headings, the footnote legend, the dates printed in the header.
Page by page, in windows — a window is up to 3 pages, or fewer when the pages are full (a dense page — 25 or more table rows or 2,500 or more characters — gets a window of its own; a table that crosses a page break stays in one window; an answer that runs past the model's limit is re-read one page at a time). Each window travels with the page images and the OCR text, and the reader answers, for each page: its page type, its report kind, the header facts it prints (name, date of birth, sex, MRN, facility, physician, document type, dates), whether a new report starts here (also part-way down the page), and every result row with its value, unit, range and panel heading. The fax state carries the open panel and the open document from one window to the next.

A busy model (capacity) does not fail the fax: it waits for the next tick, and after three tries a person is told.

3. Documents — rule, from the reader's answers¶

A page starts another document when its header names another person (then the whole fax goes to review), or when the reader flags a new report and a report fact differs (a date, a document type) — two independent signals. Where only one signal speaks — a laboratory's page after a report of prose or the other way round (the page's kind alone), a narrative page the reader flagged without a differing header or headered without a flag (an echo page inside a discharge summary, a page of traces after a nerve-conduction report) — nothing is cut on it: with Ask the reader before cutting a report on one signal on (2026-10-29) the reader is asked, with the pages in view and no label shown, whether page N−1 and page N belong to the same report; its answer counts only with cues it quotes from the print, is asked twice, and "unsure" keeps the pages together and tells the fax owner ("the split at page 4 is uncertain"). Off, the page's kind alone still cuts, as before 2026-10-29. With A hospital record is one report on (since 2026-10-27), a hospital record is a container: a study the reader flags or headers inside it opens as a document embedded in the record, the record's own pages after the study continue the record, and a flagged page of the record itself opens nothing — the record then files as one Hospital report of every page and each embedded study files once more as its own report on its own pages. The same name printed the other way round, one misread letter, a changed accession number — one person. A cover sheet names nobody. A page that prints neither a name nor a date of birth never splits a fax. A report that begins part-way down a page shares that page with the report before it.

4. What is a result — rule, then the mapper¶

Rows read on imaging, procedure and administrative pages — and on any page inside such a report — are set aside before anything else: named in the note ("N numbers read on an imaging report are not lab results"), never mapped, never trended. So are rows on the practice's own pages faxed back (switch, off by default): a page that carries an Elation patient link of this practice was written here for certain; a page whose facility, as the reader printed it, is one of the practice's names counts only when it is a notes, letter or form page — the practice writes notes, letters and forms, never results, so a lab, imaging, procedure or hospital page is never set aside by the name on it, and a fax a laboratory or a hospital sent has no own page by name at all (2026-10-27). Its values are on the chart already (on 2026-10-26 sixteen values quoted in the practice's own note came back behind another party's rejection and were trended as a new lab). When the name rule alone decided, the fax owner's note says which pages and offers Trend anyway on the fax page — one click runs the fax again with no page as the practice's own. Another sender's note that quotes values, or another practice's Elation printout, trends as before. Rows on a laboratory's or a hospital record's pages go on:

Repair — a name or unit the OCR mangled is repaired by the reader from the page image; the printed unit is never rewritten, only what the mapper reads.
Mapping — the mapper (the sibling LOINC package) codes each row; the clinicians' approved answers come first, then its own search; it may abstain. The reader never chooses a code.
Judge — a second model check of the mapped code against the row; an approved code is never re-checked.
Review cards — a row the mapper could not code, or a code Elation's own LOINC table does not carry, opens a review card for the clinician; one answer there applies from the next fax on. Rows on the practice's accepted list are named in the note and never counted as unfiled.

5. Segments — rule¶

Documents become the segments that file. One laboratory's documents rejoin as one report (whatever each page calls its facility, when the sender is a known lab or hospital); a narrative report's continuation pages rejoin it; an imaging segment whose text names several studies is cut into one report per study; a page two reports share goes into both PDFs, its rows to the lab side. The other pages of a mixed fax of one patient file as Misc when the practice says so. The harness page shows each segment and files them one by one.

6. The type of each segment — rule first, reader last¶

A segment's kind names its type without a model call: lab, or a hospital record with values → Lab Result (a hospital's files under Elation's Hospital type when the practice says so); imaging — radiology and the cardiac studies alike (since 2026-10-26, Dr Tro: one family, no study-specific condition) → Imaging Result; procedure → Procedure Report. Only a segment of notes, paperwork or unknown pages goes to the reader to classify from its words (consult note, discharge summary, prior authorization, referral, …) — filed as Misc (or its own Elation type) when that type is on the practice's "File as Misc" list, otherwise withheld: it stays in the inbox and the owner is told. A segment whose every value sits on the practice's own pages faxed back is read from its words alone (no row count, no table fact may make it a lab) and files as Misc whatever they say — the rejection letter in front of the practice's own note leads the title; only a prior authorization or a pharmacy request still waits for a person.

7. Whose chart — rule, then a person when unsure¶

The patient comes from the report's own patient block (the reader's), merged with Document AI's and the OCR header's facts. One search per patient of the fax. One match files there; nobody matched → a new chart from the fax's demographics (or the triage chart, per Settings), and one chart for every report of that person in the fax; several matches, or a fax split for review → the triage chart, for a person to adopt. A new chart only when the identity is sure (switch, off by default; since 2026-10-26): no chart when the readers disagree on the name — the reader's patient block, Document AI's facts, the OCR-text reader — when the pages of the document disagree on it, or when a chart in Elation already carries that date of birth under another name (on 2026-10-12 a laboratory's client box named a new chart); then the triage chart, with the reason, for a person. A chart that matched is never doubted. With Tell the fax desk of every new chart on, every chart the app creates is announced on Spruce with its link, to verify. The reader's own rule says who the patient is on a laboratory's first page with its three boxes side by side (the patient's, the specimen's, the client's); the OCR-text reader never takes a "Client Name:" or "Physician Name:" line. A sender on the "filed without trending" list files PDF-only.

8. The verdict — rule¶

A lab whose rows the mapper mostly could not code is held: nothing reaches the chart until a person releases it from the fax explorer (a lab none of whose rows could be coded is held or filed without values, per Settings). A few uncoded rows are filed with a warning line in the note and the care team is told. On a big packet, results older than the trend window (24 months, from 20 pages) stay on the PDF.

9. What reaches Elation — rule¶

Lab / Hospital: the values on grids with their dates, the PDF, the note with the filing lines, the panel headings as printed and — for a hospital record, when the switch is on — the record's own words for eight parts: ADMISSION (dates of the stay, disposition), DIAGNOSES, PROCEDURES (with what they found), DIAGNOSTIC IMPRESSIONS (echo, imaging, ECG, pathology conclusions), DISCHARGE MEDICATIONS, FOLLOW-UP, PENDING, HOSPITAL COURSE — each capped, the course last.
Imaging (radiology and the cardiac studies; procedure reports ride the same path): the PDF and the note with four parts copied word for word — INDICATION (why the study was ordered, or the pre-procedure diagnosis), FINDINGS (what the images or the procedure showed; a cardiac study's measurements and intervals), IMPRESSION (the radiologist's conclusion, the post-procedure diagnosis, a cardiac study's interpretation), RECOMMENDATIONS (the follow-up printed under a heading of its own — a repeat study, a referral; since 2026-10-26, Dr Tro's priority field; read by the severity check too), ADDENDUM (text added after the signature that changes the findings) — plus the study name as printed.
Procedure / Misc: the PDF; their note travels as a non-visit note while that switch is on (Elation shows a report's own note only on an Imaging report — which is why a cardiac study's interpretation is visible since it files as Imaging).

Meaning first, headings as examples. The app does not search for the words "Impression" or "Findings". The reader is told what each part means and finds it under whatever heading the report prints; since 2026-10-26 the prompt also lists, from Dr Tro's dictionary (data/section_headings.json), the headings doctors commonly print for each part — an impression may be printed as INTERPRETATION or CONCLUSION, findings as OBSERVATIONS or MEASUREMENTS, a recommendation as SUGGESTIONS or FOLLOW-UP, a hospital record's diagnostic impressions as PERTINENT RESULTS — examples that help the reader find the part, never a rule. Then every passage it returns must be found, character for character, in the fax's own text (exactly, or between its first and last forty characters) — the fax text is what is copied, a passage that cannot be found is dropped and the note names what is missing. A signature stamp, a footer or a fax header is never a part.

After the post the report is watched; an answer that never came is held for a person rather than posted twice, and "Adopt from the chart" lets the MA attach a report Elation did create. A report later deleted from Elation opens an incident.

10. After filing — rule¶

The item leaves the inbox only when every report of the fax is filed (it is filed to a holding chart and deleted there, so nothing is lost); otherwise it stays for a person. Spruce tells the care team (a lab filed, an imaging report in two messages in the patient's own thread — the report, then the details — a held fax, a fax not processed), within the hourly and daily limits on the Communication page, and every note ends with the one-click problem link.

Keeping this page true¶

Each box above is a decision in code. When a session changes one — a new switch, a rule that opens or joins a document, a type that files differently, a part the note copies — the box and its stage paragraph change in the same commit. The close-session checklist lists this page beside the handoff document.