Private records workspace
Case management, signed PDF uploads, document processing status, original source viewing, and explicit retry and deletion flows.
Engineering case study / Document intelligence
Shivru AI
Medical records, ready for review.
A private workspace for medical-legal PDFs: source-linked timelines, case questions, billing checks, and reports.
- 500 synthetic pages
- 251 automated checks
- 50 browser tests
11 Oct 2026 validation snapshot. Technical and synthetic checks; production readiness and clinical accuracy are not established.
Explore further: Product workflows · Engineering decisions · Lessons learned
01The problem & my contribution
From document volume to reviewable evidence
Medical-legal review involves fragmented records, scanned pages, repeated documents, conflicting date roles, and bills that may not have an obvious corresponding clinical record. A useful system needs to show what a finding is based on and what still needs review.
Shivru AI organizes this work around a private case workspace: original PDFs, extracted events, evidence citations, exception review, and consistent report outputs.
My contribution
As Co-Founder & AI Engineer, I developed medical-legal document workflows spanning OCR, structured extraction, retrieval, chronology generation, billing reconciliation, missing-record checks, and citation verification.
The project connects applied AI with the software around it: typed contracts, background processing, evidence mapping, reviewer actions, and document exports.
02What the workspace does
Source-linked chronology
Structured medical events with cited pages and excerpts. Reviewers can inspect the original PDF and correct or review extracted information.
Ask Records
Case-scoped vector retrieval with verified source excerpts. When evidence is insufficient, the workflow returns a bounded no-evidence response.
Records & bills
Physical-page accounting, provider coverage, requested date ranges, billing-page matches, and explicit treatment of incomplete or ambiguous inventory.
Exceptions & follow-ups
Evidence-linked review prompts for gaps, unmatched bills, possible duplicates, contradictions, omissions, and citation mismatches, with dispositions and assigned follow-ups.
History & report exports
Versioned case review and immutable report bundles. Chronology PDF/DOCX and attorney PDF/XLSX outputs retain source references and coverage disclosures.
Implemented workflows described in the repository. A processing-complete status does not certify complete clinical extraction or attorney readiness.
03Technical architecture
A source-preserving pipeline, with deterministic checks around model calls and a separate worker for long-running document processing.
- 01
Ingest
Authenticated case
Private PDF upload
Durable processing job - 02
Read
Native PDF text first
OCR when needed
Physical-page inventory - 03
Structure
Classify pages
Page-bound chunks
Typed event & fact proposals - 04
Ground
Validate source excerpts
Check field support
Reject invalid references - 05
Retrieve
Embeddings & vector index
Case-scoped search
Verified answer excerpts - 06
Review & export
Source PDF & corrections
Coverage & exceptions
Frozen report bundle
Across the pipeline
Tenant isolation · source provenance · leased checkpoints · version checks · human review
Application
Next.js · React · TypeScript
Data & access
Supabase Auth / Storage · PostgreSQL · pgvector · row-level security
AI & contracts
Configurable OpenAI / Gemini providers · Zod validation · deterministic grounding
Documents & OCR
PDF.js · Tesseract · Azure Document Intelligence / Google Document AI adapters
Verification
Unit and database checks · PGlite · Playwright · parser and report regressions
04Engineering decisions that matter
Read the 5 engineering decisions
Keep evidence attached to the physical page
Chunks do not cross page boundaries. Extracted events and accepted answers require supporting excerpts from the referenced source. Unsupported fields, invented quotations, and cross-case references are rejected.
Make uncertainty visible
Ambiguous dates stay unknown. Missing records become review prompts. Potential duplicates and provider variants require human judgment rather than speculative merging. Rule-based checks do not manufacture an AI confidence score.
Resume work without mixing source versions
Page and chunk checkpoints preserve completed work. Fenced leases prevent expired workers from writing after a successor takes over, and source hashes guard checkpoint reuse against changed document bytes.
A provider response can be repeated if interruption occurs before its checkpoint is committed; persisted database writes are designed to remain idempotent.
Export a consistent view of the case
Write-once report bundles preserve source versions, coverage, and report inputs. Stale corrections and inconsistent export inputs are rejected instead of silently overwriting or mixing reviewed state.
Enforce access beyond the interface
Organization, role, and case access are checked server-side and in database policies. PDFs use private storage and short-lived signed access; worker and provider credentials remain on the server.
05Validation & evidence
The project records technical regression tests, synthetic load checks, and a small live-model fixture. Their scopes are kept separate.
Synthetic pages processed
400 native-text pages and 100 raster pages, including actual OCR for the raster subset.
Load / regression fixtureAutomated checks passed
Unit, database, parser, and renderer suite in the documented validation run.
Historical technical test resultBrowser tests passed
Production-build browser tests recorded in the same validation handoff.
Software behavior verificationExport formats checked
Chronology PDF/DOCX and attorney PDF/XLSX, from a shared frozen bundle.
Export consistency checksWhat the synthetic load run measured
The 500-page native-text/OCR fixture reported approximately 119 seconds for parsing and grounding checks on the measured environment. It made no external model calls. The templates are synthetic and repetitive; this result is a load/regression check, not representative medical-record accuracy.
What the live-model sample measured
A separate ten-page synthetic fixture recorded 20 extraction/page-fact operations and retained its 12 expected clinical fields and 8 expected billing fields. This small, fixture-specific result does not establish representative recall or model precision.
Limitations & open validation
Independent clinical adjudication, representative handwritten and dense-table records, a representative 500-page live-model evaluation, and remaining hosted security/reliability acceptance. Production readiness and clinical accuracy are not established by these technical checks.
06Challenges & engineering lessons
Read the engineering lessons
A date needs a role, not just a pattern
Clinical dates, print dates, filing dates, and dates of birth can appear together. Source context, encounter boundaries, and retained offsets matter more than simply detecting a date-shaped string.
Literal support is necessary, but not sufficient
A field occurring in a passage does not establish that it belongs to the correct encounter or that the clinical meaning is complete. Containment checks and independent clinical review answer different questions.
Coverage is a data contract
The records view, coverage API, and frozen exports should agree on the physical-page ledger. Finishing a job must not make partial, unreadable, or unreviewed pages disappear.
Reports are an engineering surface
Measured PDF layout, wrapped tables, repeated headers, separate summary/dossier modes, and consistent frozen inputs make exported work products easier to inspect and reproduce.
What this work brings together
Applied AI, backed by careful engineering.
Document processing, structured data contracts, retrieval, background jobs, review workflows, and full-stack product delivery.
Evidence scope: implementation documentation and the 11 October 2026 validation handoff. Architecture diagrams are simplified. Test counts describe that dated snapshot; no private record content is reproduced.