<Feature> Document Quality Check at Upload and Pre-Packet Stages (Online & Offline)

[Varaniya201]

As a **registration operator **
I want the android registration client — in both online and offline modes — to validate the authenticity of uploaded documents and confirm that keyed-in demographic data matches those documents, routing any discrepancy to a supervisor for an approve-or-reject decision
So that only genuine, issuer-authorised, and consistent registrations become packets, with a controlled human checkpoint for exceptions.

Description

The android registration client today accepts scanned supporting documents (PDF/DOC) and lets the operator key in demographic data, with no automated check on document genuineness or on whether the entered data agrees with the document. This feature introduces an automated Document Quality Check (DQC) at two points, and it must operate identically in online and offline registration:

• Stage 1 — Authenticity at upload. Right after upload in an allowed format, the system validates whether the document is a genuine scanned original and whether it comes from an authorised issuer, using barcode/MRZ parsing, hologram/watermark detection, or AI/ML anomaly detection.
• Stage 2 — Demographic consistency before packet creation. Before the packet is created, the system runs OCR and cross-verifies entered demographic fields against the document, with the field set driven by the document category (identity proof → name, gender, DOB; address proof → name, address; etc.).
  When Stage 2 finds a discrepancy, the packet is not created automatically. The registration is held for a supervisor decision: the supervisor either approves it to proceed (packet created) or rejects it, in which case no packet is created and the resident must re-register. The entire DQC capability is configurable at country level and is only active where the country requires it.

---

Problem Statement

There is currently no guarantee that an uploaded document is authentic or that captured demographic data corresponds to it. Fraudulent, tampered, or mismatched submissions are caught late or not at all, driving rejections, rework, cost, and fraud risk — and the operator gets no feedback at the point of capture, where correction is cheapest. The control must work even when centres operate offline, and exceptions must be governed by a supervisor rather than silently passed or blocked.

---

Goals

• Detect tampered/regenerated/forged documents and unauthorised issuers at upload.
• Verify operator-entered demographics against the document, per document category.
• Operate consistently in both online and offline registration modes.
• On a Stage 2 discrepancy, enforce a supervisor approve/reject checkpoint, with rejection leading to resident re-registration.
• Keep the whole feature configurable per country (enable/disable), plus configurable field mappings, match thresholds, and hard-stop vs. warning behaviour.
• Give operators and supervisors clear, field-level, actionable results.
• Record every check and every supervisor decision in the audit trail.

---

Non-Goals

• Does not replace supervisor judgement — it flags; the supervisor decides on exceptions.
• Does not auto-populate or auto-correct demographic fields from OCR (verification only).
• Does not perform biometrics or de-duplication (separate flows).
• Does not perform live external issuer-database lookups in this iteration; issuer validation is against a locally configured/synced issuer registry.
• Does not change the standard flow at all when the country configuration disables DQC.

---

Configuration & Modes

• Country-level switch. A country/policy configuration flag enables or disables DQC end-to-end. When disabled, registration behaves exactly as today with no checks invoked.
• Online mode. Checks may use remote services (OCR, anomaly model, issuer registry) where configured; otherwise local equivalents are used.
• Offline mode. Checks run on-device or via a local service, using configuration and the issuer registry synced to the client. If a specific check genuinely cannot run offline, the configured fallback applies (defer-and-recheck on next sync, or mandatory manual review) — it must never silently auto-pass.
• Parity requirement. Outcomes, operator feedback, and the supervisor workflow behave consistently across both modes; only the execution location and any deferral differ.
• Field-to-category mappings, match thresholds (exact/normalised/fuzzy), and hard-stop vs. warning classification are all configurable.

---

Supervisor Approval Workflow (Stage 2 discrepancy)

1. Stage 2 detects a discrepancy on one or more required fields (mismatch beyond configured tolerance).
2. Packet creation is halted; the registration enters a Pending Supervisor Approval state showing field-level details (entered value vs. OCR-extracted value, confidence).
3. An authorised supervisor authenticates (online or via offline credentials) and chooses one of:
   • Approve / Proceed — supervisor records a reason; the packet is created and the decision is audited.
   • Reject — supervisor records a reason; no packet is created, the registration is discarded/marked rejected, and the resident must re-register.
4. The decision, supervisor identity, reason, timestamp, mode (online/offline), and the underlying discrepancy are written to the audit trail.
5. The workflow functions identically in offline mode; if no supervisor is available, the registration remains in the Pending state per the configured handling rather than auto-proceeding.

Stage 1 is a hard stop. If a document is found invalid or tampered, the operator cannot proceed under any circumstances — there is no supervisor override to continue. The system blocks the document and prompts the operator to re-upload a valid document. The supervisor approve/reject workflow above applies only to Stage 2 demographic-data discrepancies, never to Stage 1 authenticity failures.

---

Acceptance Criteria

1. Document quality check can be enabled/disabled at country level; when disabled, no checks run and the registration flow is unchanged.
2. When enabled, both online and offline registration run Stage 1 and Stage 2, with outcomes and the supervisor workflow behaving consistently across modes.
3. Stage 1 runs automatically on upload and evaluates genuineness (scanned original, not tampered/recaptured) and authorised-issuer status via barcode/MRZ, hologram/watermark, and ML anomaly signals; each result resolves to Pass / Warning / Fail with a readable reason. A Fail (invalid or tampered) is a hard stop: the operator cannot proceed, the system prompts re-upload of a valid document, and there is no override to continue with an invalid/tampered document.
4. Stage 2 verifies entered demographics against OCR-extracted values, using the configured category→field mapping and configurable match rules, producing per-field and overall results.
5. On a Stage 2 discrepancy, packet creation is halted and the registration is placed in Pending Supervisor Approval; it cannot become a packet without a supervisor decision.
6. A supervisor can Approve/Proceed (authenticated, reason captured → packet created) or Reject (authenticated, reason captured → no packet, registration rejected, resident must re-register).
7. The supervisor decision and its context (identity, reason, timestamp, mode, discrepancy details) are recorded in the audit trail, along with all Stage 1/Stage 2 outcomes.
8. Imperfect-input behaviour is defined and graceful: unreadable barcode/MRZ, low OCR confidence, unsupported/corrupt files, and offline-unavailable checks follow configured fallbacks rather than silent pass/fail.
9. Each check completes within an agreed performance budget; on timeout or service unavailability (especially offline), the defined fallback (retry/defer/manual review) applies.
10. Configuration covers: country enable/disable, per-category field mapping, match thresholds.

---

Scenario-wise Expected Behaviour

Legend — Flow Type: Main = happy/primary path · Alternate = valid non-happy variation · Exception = error/edge handling.

Configuration

ID	Scenario	Flow Type	Mode	Given (Precondition)	When (Trigger)	Then (Expected Behaviour)
CFG-01	DQC enabled	Main	Both	Country config has DQC enabled	Operator uploads documents and proceeds to packet creation	Stage 1 and Stage 2 checks run per configured rules
CFG-02	DQC disabled	Alternate	Both	Country config has DQC disabled	Operator uploads documents and creates a packet	No authenticity/consistency checks run; flow is identical to current behaviour

Stage 1 — Authenticity at Upload

ID	Scenario	Flow Type	Mode	Given (Precondition)	When (Trigger)	Then (Expected Behaviour)
S1-01	Genuine, authorised document	Main	Both	Valid scanned PDF/DOC in an allowed format	Authenticity check runs on upload	MRZ/barcode parses, watermark & anomaly checks pass, issuer recognised → marked Pass, accepted
S1-02	Tampered / digitally altered	Exception	Both	Anomaly model detects manipulation (edits, splicing, inconsistent fonts/compression)	Check runs	Hard stop — marked Fail, operator cannot proceed, system prompts re-upload of a valid document, reason "possible tampering detected" shown, event logged
S1-03	Invalid / not a scanned original	Exception	Both	File is a screenshot, recapture, photo of a screen, or otherwise invalid	Check runs	Hard stop — marked Fail, operator cannot proceed, system prompts re-upload of a valid document, reason "not a valid scanned original" shown, event logged
S1-04	Unauthorised / unknown issuer	Alternate	Both	Issuer not present in authorised issuer registry	Check runs	Marked Fail/Warning per policy, reason "issuer not recognised"; proceeding requires configured path
S1-05	Barcode/MRZ unreadable	Exception	Both	MRZ/barcode absent, damaged, or unreadable	Parsing fails	No silent pass; falls back to watermark/anomaly signals → resolves to Warning / manual review
S1-06	Unsupported / corrupt file	Exception	Both	File outside allowed formats or corrupt	File uploaded	Rejected with format/integrity error before authenticity checks run
S1-07	Offline execution	Alternate	Offline	Client is offline; config & issuer registry synced locally	Document uploaded	Checks run on-device/locally; any check that can't run offline follows configured deferral/manual-review fallback with a clear pending state
S1-08	Authenticity service unavailable	Exception	Online	Remote authenticity service/model unreachable	Upload occurs	Configured fallback applies (defer-and-recheck / queue / allow-with-mandatory-review); pending state shown, no silent fail

Stage 2 — Demographic Consistency & Supervisor Workflow

ID	Scenario	Flow Type	Mode	Given (Precondition)	When (Trigger)	Then (Expected Behaviour)
S2-01	All fields match (identity proof)	Main	Both	Identity proof; entered name, gender, DOB	OCR extracts fields, all match within tolerance	Result Pass; packet creation allowed
S2-02	All fields match (address proof)	Main	Both	Address proof; entered name, address	OCR extracts fields, both match within tolerance	Result Pass; only category-relevant fields evaluated (DOB/gender not required)
S2-03	Discrepancy → supervisor approves	Alternate	Both	One or more required fields mismatch beyond tolerance	Check runs; supervisor authenticates and approves with reason	Registration enters Pending Supervisor Approval → packet created on approval; decision audited
S2-04	Discrepancy → supervisor rejects	Alternate	Both	Same pending-discrepancy state	Supervisor authenticates and rejects with reason	No packet created; registration marked rejected/discarded; resident must re-register; decision audited
S2-05	Discrepancy offline	Alternate	Offline	Client offline; discrepancy detected	Supervisor authenticates with offline credentials and decides	Approve/reject workflow behaves identically; decision recorded with mode = offline
S2-06	No supervisor available (offline)	Exception	Offline	Pending discrepancy and no supervisor present	Operator cannot escalate	Registration stays in Pending per configured handling; does not auto-proceed
S2-07	Low OCR confidence / field not found	Exception	Both	Required field can't be read reliably (poor scan, handwriting, layout)	Check runs	Field flagged low-confidence/not-found; routed to supervisor checkpoint; not auto-passed or auto-failed
S2-08	Fuzzy match within tolerance	Alternate	Both	Minor variations (initials, transliteration, date formats)	Matched under configured fuzzy/normalisation rules	Resolves to match (or grey-zone Warning), not a hard discrepancy
S2-09	Multiple documents	Alternate	Both	More than one supporting document uploaded	Check runs	Each document verified against fields mapped to its own category; overall result aggregates per-document outcomes
S2-10	Connectivity lost mid-flow	Exception	Online→Offline	Connectivity drops after upload	Stage 2 runs	Client completes checks locally where possible or defers per fallback; same supervisor workflow preserved at decision point