Open decision: how DeltaTrack reaches staffers (delivery channel), waiting on Hill IT, workflow and packaging signals #112

What needs deciding

DeltaTrack hasn't decided how it will reach its main users, congressional staffers: as a web page, a browser extension, a desktop install, or something else. The decision is waiting on information from outside the project, not on engineering work. This issue keeps the options, the settled constraints and the evidence in one place, so the question isn't re-argued from scratch. The outcome becomes a new ADR (architecture decision record, in docs/decisions/).

Some background, for anyone new to this:

• Delivery channel. How a user runs the tool. The comparison engine is Python. Its output is canonical JSON (a fixed data format, ADR 0006) turned into an HTML report by a single renderer (ADR 0007).
• Local-only rule. ADR 0011 says a user's bill content never leaves their machine, even to a server that stores nothing. Drafts can be confidential. Any channel that uploads bills to a server breaks the rule.
• Install gate. Staffers use locked-down computers. In the Senate, software is installed centrally by the Sergeant at Arms (SAA) from an approved list. In the House, the Chief Administrative Officer (CAO) approves it. An arbitrary executable is hardest to get through; something that needs no install is easiest (ADR 0011, "Context").

Where things stand (develop 5ef9a5e, checked 2026-10-05)

• A hosted web app exists and breaks the local-only rule, on purpose and for now. https://deltatrack.agoradmv.org/ takes two uploaded PDFs or XML files and compares them on the project's server. The upload page says so and asks users not to upload drafts (web/webapp/compare.html:29-33). docs/PRODUCT.md:123 records this as a known, deliberate interim state tracked here. Its "browser-only" option is marked "Coming soon" (docs/web-compare.md).
• The hosted app now has a deploy pipeline. .github/workflows/deploy.yml builds an image and deploys it to a Dokku server (Dokku is a self-hosted platform for running apps). It was added 2026-09-13 and set to deploy from main on 2026-10-03. main was last updated 2026-08-11 and doesn't have the workflow yet, so the next production deploy waits on Epic: promote develop to main so the demo and hosted app show current code #555 (the open epic to promote develop to main). See docs/deployment.md. This is new investment in the upload channel that ADR 0011 rules out. It doesn't change that ruling, but it raises the question of how long "interim" lasts.
• The in-browser route has evidence behind it. The PDF backend study (wrapped up by Close out the PDF study with a one-page summary #740, the PR that wrote its summary; its files were removed from the tree by Remove the closed PDF backend study #783, a PR merged 2026-10-05) moved its conclusions into the ADRs:
  • ADR 0003: the Python engine runs inside a web page under Pyodide (Python compiled for the browser) and produces byte-identical XML comparison output, checked by scripts/pyodide_parity.py. The PDF path hasn't run end to end in a browser.
  • The XML comparison cannot load in a browser because it imports a PDF library it never uses #751 (open): the XML comparison imports a PDF library it never uses, which stops it loading in a browser without a workaround. It matters only for an in-browser channel.
  • ADR 0011: a page's Content Security Policy alone can't guarantee no network traffic, because window.open and WebRTC are outside it. A browser channel's no-egress claim needs a browser- or device-level control and a network-level check.

Already decided (not reopened here)

• No uploads to a server for the real product (ADR 0011). A server can serve the interface, or work on bills that are already public when the user sends no bill content.
• PDF input is required, because drafts exist only as PDF (ADR 0010).
• The engine keeps no state and writes nothing the user didn't ask for (ADR 0005).
• Rewriting the engine in JavaScript is not free. Its correctness is validated independently (ADR 0009), and a rewrite starts that over.

The options

More than one can win. The public-bills-only hosted row is allowed by ADR 0011's "Consequences" section but hasn't been discussed here before.

What would unblock it

• Hill IT specifics: what staffers in each chamber can actually install or run. This isn't public, so it needs a contact in SAA or CAO.
• Workflow shape: how a real staffer wants to use it: drop in two PDFs, paste text, from inside a browser?
• Packaging direction: whether BillTrax, a sibling project that carries a vendored copy of DeltaTrack's engine, converges with this one. It's listed as open in docs/research/naming-architecture/README.md.

Done when

• The three signals above are in, or the maintainer decides to go ahead without one of them and says why.
• A new ADR records the channel(s), the engine runtime that follows, and what happens to the hosted upload path.
• docs/PRODUCT.md:123 and docs/web-compare.md are updated to match.

Scope

• In scope: choosing the channel(s) and the runtime that follows from them.
• Out of scope:
  • The README's entry point for non-technical readers: The README sends readers who only want to see output to the command line, not to the example reports or the hosted app #608 (open).
  • Promotion timing: Epic: promote develop to main so the demo and hosted app show current code #555.
  • Making the XML path loadable in a browser: The XML comparison cannot load in a browser because it imports a PDF library it never uses #751.

History

• ADR 0010 and ADR 0011, listed as in-flight PRs in the original version of this issue, merged on 2026-06-28 (PRs Add ADR 0010 (PDF pipeline for pre-publication bills) + bill-publishing reference #102 and Add ADR 0011 (local-only processing of user-provided bill content) #111).
• On 2026-07-28 the maintainer confirmed that the hosted app is transitional and that the target is something local with a light install, preferably a browser extension. The upload warning and the PRODUCT.md note were added afterwards.

Unverified

• That the hosted app is up today; it couldn't be reached from the sandbox used for this check.
• Who controls the Dokku host. docs/deployment.md says to "ask the host maintainer", and the naming research lists ownership of the domain as open. The maintainer reports that civictechdc holds access.
• Whether any of the three signals has moved since 2026-09-22.