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.

  1. 01

    Prepare

    Import bounded fictional records with registered sources, approved work, and posted invoice lines. Private originals retain their lineage.

  2. 02

    Approve terms

    An author proposes effective-dated terms; a different permitted account approves the version against its source.

  3. 03

    Calculate

    The shared exact-decimal engine selects applicable rules and allocates invoices. Unsupported or pending records remain coverage tasks.

  4. 04

    Inspect

    Open a finding to see expected versus invoiced amounts, source excerpts, affected work, and the calculation.

  5. 05

    Decide

    Confirm, dismiss, or mark evidence as needed with a recorded reason. Evidence changes reopen affected findings without erasing prior decisions.

  6. 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.

System architecture ShiftClarity

Inspect diagram
ShiftClarity synthetic pilot: Cloudflare Pages proxy, API Gateway, FastAPI web Lambda and shared TypeScript calculation engine, Cognito MFA, private S3, SQS FIFO worker, and Neon PostgreSQL with transactional publication

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.

System review / ShiftClarity

Inspect the architecture.

Zoom for service labels. Scroll or swipe to explore the diagram.

ShiftClarity synthetic pilot: Cloudflare Pages proxy, API Gateway, FastAPI web Lambda and shared TypeScript calculation engine, Cognito MFA, private S3, SQS FIFO worker, and Neon PostgreSQL with transactional publication

04 / Product in use

Potential differences, their evidence, and the unresolved work.

ShiftClarity synthetic review workspace with billing findings, review statuses and checked coverage

Review workspace

Recorded synthetic pilot capture. Finding amounts and coverage describe fictional records, not customer savings or collected revenue.

Full-resolution source
ShiftClarity fictional finding detail with expected and invoiced values, source lineage and persisted review history

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 source

05 / Decisions

Three decisions and the cost of each.

  1. 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.

  2. 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.

  3. 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.

  4. 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 evidence
  • 70

    Domain / component tests

    Exact calculations, effective dates, invoice allocation, coverage and review state using controlled fixtures—not measured business value.

    Inspect evidence
  • 8

    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 evidence
  • Matched

    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 boundary

Interrupted 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 gates

08 / 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

  1. Validate source semantics and supported billing terms with an authorized customer; agree data-use, retention, incident and legal boundaries before importing real records.
  2. Measure finding validity, reviewer effort and actual resolution outcomes independently. Potential discrepancies must never be equated with collected money.
  3. Qualify representative capacity, multi-workspace isolation, cost and recovery targets with the approved environment and workload.
  4. 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.

ReactTypeScriptExact decimal arithmeticFastAPIAWS LambdaAPI GatewayCognito MFAS3SQS FIFONeon PostgreSQLTerraformCloudflare Pages