SYSTEM DESIGN & SPECIFICATION
How ClaimClarity works
AI extracts evidence. Deterministic rules reconcile it. The citizen sees the proof.
THE ARCHITECTURAL BOUNDARY
Large language and vision models are exceptional at parsing messy, unstructured artifacts into typed observations. However, the final claim reconciliation decision must never be generated by an LLM. ClaimClarity enforces a strict separation: AI performs evidence extraction only; a pure, deterministic engine performs reconciliation.
End-to-End Reconciliation Pipeline
Click any stage to inspect what it does & does not do1. Citizen Evidence
Screenshots, passbook entries, claim tracker records, and SMS notices provided by the citizen.
2. AI Evidence Extraction
Multimodal vision & language extraction converts messy artifacts into candidate observations.
✓ WHAT IT DOES
- Extract explicit dates, claim IDs, raw status strings, and monetary amounts
- Record provenance pointers directly back to the originating artifact
- Preserve textual ambiguity and explicit uncertainties
✕ WHAT IT DOES NOT DO
- Decide the official claim outcome or final claim state
- Hallucinate or infer missing facts not present in the record
- Give free-form unconstrained advice to the citizen
3. Validated Structured Facts
Rigorous runtime schema validation (Zod) rejects malformed or unverified model outputs.
4. Identity + Chronology
Group records by verified claim identifier and sequence them into a strict chronological timeline.
5. Event Semantics
Map raw source phrases into clear lifecycle semantics (In-Flight vs Terminal vs Financial).
6. Conflict / Stale Checks
Detect outdated records superseded by newer outcomes and surface true terminal contradictions.
7. Deterministic Reconciliation
Pure rule-based state machine evaluates all facts to select the best-supported claim state.
8. Evidence Ledger
Construct an auditable, timestamped ledger linking every conclusion directly to supporting records.
9. Plain-Language Answer + Action
Deliver the 4 critical citizen answers: What happened, Why, What proves it, and What to do next.
WHY THIS ARCHITECTURE?
LLMs are useful for turning messy evidence into structured observations. The final reconciliation decision remains deterministic and auditable.
1. Zero Decision Hallucination
By restricting generative models to extraction, the system is mathematically incapable of hallucinating a settled or credited claim status that is not supported by chronological evidence.
2. Complete Grievance Auditability
Every output produces a deterministic audit trace of fired rules, chronological ordering, and identifier checks. If a citizen files a grievance, the exact proof chain can be reproduced.
3. Safe Refusal by Design
When evidence is missing or fundamentally incompatible, the engine explicitly outputs UNKNOWN or CONFLICT instead of generating plausible-sounding but dangerous advice.
CONCRETE EXAMPLE WALKTHROUGH
How a contradictory claim is resolved
Processing
Processing
₹45,000 credited
Why: Later financial evidence supports a completed outcome. Older portal records reflect delayed sync.
Technical Disclosure & Implementation Notes
Evidence extraction uses Google Gemini 2.5 Flash with structured output schemas (JSON Mode + Zod) on the backend. The reconciliation engine is implemented in pure TypeScript without external model dependencies, guaranteeing deterministic execution across serverless environments.
ClaimClarity is an independent public-utility prototype developed for civic decision support. It is not affiliated with, endorsed by, or integrated with the Employees' Provident Fund Organisation (EPFO).