Case study / ShiftClarity
Find where approved work, contract terms, and invoices stop agreeing.
A contract-to-invoice review workspace for healthcare staffing teams. It traces potential billing differences to approved terms and source records, preserves review decisions, and keeps unsupported work visible without inventing a financial answer.
- Role
- Independent builder
- System
- ShiftClarity
Pilot boundary
Synthetic AWS pilot
Fictional records / public demo in memory / persistent workspace requires access
Independent synthetic AWS pilot using fictional records only. The public standalone demo keeps changes in memory and resets on refresh; its roles are simulated. The separate persistent workspace requires an assigned Cognito account, authenticator MFA, and server-side membership. No customer adoption, recovered revenue, compliance certification, or production service commitment is claimed.
01 / Business workflow
The invoice is not the whole story.
- Staffing teams can approve a rate amendment while an invoice still uses the old rate. Approved work may be absent from billing, and a contract term may lack enough support for a reliable calculation.
- A difference is only actionable when the reviewer can identify the applicable dated terms, approved work, posted invoice lines, and the assumptions behind the amount.
- ShiftClarity brings those records into one review: inspect the calculation, confirm or dismiss a finding with a reason, and separate potential financial discrepancies from coverage gaps.
What a reliable review must preserve
- Fictional normalized JSON is the input boundary. No live vendor connector, arbitrary PDF/OCR ingestion, real patient data, or source-invoice editing is included.
- Money calculations must be exact and reproducible. Missing terms produce an unknown value, not an estimated recovery opportunity.
- A rule author cannot approve their own change. Historical source revisions, rule versions, completed runs, and human decisions must remain inspectable after later changes.
02 / Workflow
From source records to a decision someone can defend.
01
Prepare
Import bounded fictional records with registered sources, approved work, and posted invoice lines. Private originals retain their lineage.
02
Approve terms
An author proposes effective-dated terms; a different permitted account approves the version against its source.
03
Calculate
The shared exact-decimal engine selects applicable rules and allocates invoices. Unsupported or pending records remain coverage tasks.
04
Inspect
Open a finding to see expected versus invoiced amounts, source excerpts, affected work, and the calculation.
05
Decide
Confirm, dismiss, or mark evidence as needed with a recorded reason. Evidence changes reopen affected findings without erasing prior decisions.
06
Publish
Durable jobs publish immutable completed runs transactionally. Reloaded reviews retain their source and version context.
03 / System
Current architecture, with every major boundary visible.

From approved work and dated terms to evidence-backed review. Deployed synthetic pilot / fictional records only; the standalone demo is a separate memory-only mode.
- Entry
- Identity is not permissionCognito MFA identifies a person; server-side memberships govern the persistent workspace.
- Processing
- One calculation contractReact and FastAPI share the exact-decimal engine. Private imports feed Lambda/SQS jobs.
- Data ownership
- Sources stay with the decisionNeon transactions preserve revisions, rules, immutable runs and audit. S3 retains private originals.
- Recovery
- Publish once, recover explicitlyJob claims, lease fencing, retries and a matched restore rehearsal support the synthetic workflow—not a production RPO/RTO.
04 / Product in use
Potential differences, their evidence, and the unresolved work.

Review workspace
Recorded synthetic pilot capture. Finding amounts and coverage describe fictional records, not customer savings or collected revenue.
Full-resolution source
Evidence-linked calculation
A fictional approved-rate amendment produces a potential discrepancy. The source, calculation, and human review history stay together; payment outcomes are unknown.
Full-resolution source05 / Decisions
Three decisions and the cost of each.
01
Use one calculation engine on both sides of the boundary
A shared TypeScript engine with exact decimal arithmetic keeps browser explanations and backend publication aligned on effective dates, allocations, and coverage.
Tradeoff
FastAPI invokes a Node adapter, adding a runtime boundary. The versioned container packages both runtimes and tests the same engine instead of maintaining competing financial implementations.
02
Make uncertainty a first-class result
Unsupported terms, pending approvals, and missing records retain their reason and unknown value. A finding remains potential until an accountable reviewer evaluates it.
Tradeoff
This produces fewer headline financial totals, but it avoids fabricating value from incomplete evidence. Independent value measurement still requires a real-data pilot.
03
Separate identity, workspace permission, and rule approval
Cognito establishes identity and MFA; server-side memberships authorize actions. A different permitted actor must approve a proposed rule version.
Tradeoff
Account provisioning and explicit approval add operational steps. A synthetic single-workspace pilot does not establish multi-customer isolation or enterprise readiness.
04
Publish immutable results through durable jobs
SQS notifies a worker; PostgreSQL job claims, lease fencing, and transactions govern completed-run publication, lineage, and audit history.
Tradeoff
Queues, retries, and interrupted workers require explicit reconciliation. A matched restore rehearsal supports recoverability, not a production RPO/RTO promise.
06 / Evidence
What the record supports—and how far it goes.
52
Backend / PostgreSQL tests
Recorded October 13 synthetic release: permissions, separate approval, immutable evidence, jobs, conflicts and recovery. These are historical full-suite results, not a full rerun for the subsequent Pages-origin change.
Inspect evidence70
Domain / component tests
Exact calculations, effective dates, invoice allocation, coverage and review state using controlled fixtures—not measured business value.
Inspect evidence8
Live AWS browser journeys
Recorded before the final wording-only UI update: Cognito OTP, persisted reviews, private imports, SQS publication and denied actions. The later origin change has its own focused verification record.
Inspect evidenceMatched
Database + source-object restore
Isolated Neon/S3-to-local rehearsal compared original bytes, lineage, rule/run history and review state. No production recovery-time or recovery-point commitment.
Inspect evidence
07 / Reliability & security
A financial answer must retain the evidence and rules that produced it.
Exact calculations, separate approval, immutable source/rule/run history, object permissions and transactionally published results keep findings inspectable. Unknown terms stay unknown. Forced RLS and server memberships have synthetic checks; they are not a multi-customer certification.
Threat model and synthetic data boundaryInterrupted work is recoverable without publishing half a result.
The recorded synthetic tests exercised killed workers, lease fencing, retries and stale requests. Completed-run publication is atomic; an isolated database and original-object restore matched lineage and review state. These checks do not establish a production RPO/RTO or sustained service reliability.
Synthetic-release verification and incomplete gates08 / Limits
Known limits
- Fictional records only. No customer-data permission, hospital adoption, compliance certification, or recovered/collected revenue is established.
- The standalone demo simulates roles and stores changes in memory. The persistent AWS pilot is a separate assigned-account experience with server permissions.
- Vendor connectors, arbitrary CSV/PDF/OCR ingestion, source-invoice edits and outgoing evidence requests are not included.
- This is a single-workspace synthetic pilot. Representative load, independent security/accessibility review, customer retention policies and production approval remain open.
- Full-suite evidence predates the final Pages-origin update; its focused cloud journey is separate, not a claim that all backend tests were rerun.
Path to sustained operation
- Validate source semantics and supported billing terms with an authorized customer; agree data-use, retention, incident and legal boundaries before importing real records.
- Measure finding validity, reviewer effort and actual resolution outcomes independently. Potential discrepancies must never be equated with collected money.
- Qualify representative capacity, multi-workspace isolation, cost and recovery targets with the approved environment and workload.
- Add only the approved source connectors and ingestion formats, with independent security/accessibility review and explicit production acceptance.
09 / Artifact index
Follow the work into the repository.
- architectureDeployed synthetic pilot / C4 and trust boundaries
- architectureShared engine, identity and evidence ADRs
- iacAWS Terraform infrastructure
- testsLocal verification commands / no hosted CI pipeline claimed
- testsSynthetic-release verification and incomplete gates
- runtimePages-origin release and live checks
- securityThreat model and synthetic data boundary
- runbookAWS and database operating guide
- limitationsReal-data and production acceptance gates