Workflow — Duplicate Candidate Detection (BR-011)

Purpose

Catch repeat award candidates — the same person applying again (previous event) or a second identity sharing signals — and alert the admin, who reviews and confirms or dismisses. Applications are accepted but flagged (never auto-blocked).

Signals & weights

Any hit ⇒ alert row (score = sum of weights).

When the scan runs

1. Public award registration (/register/award) — after save (also on claim merge).
2. Visitor / GoH registration — same scan (name+whatsapp/email/link signals).
3. Staff manual entry (/admin/registrations/new) — optional CNIC supported.

Flow

sequenceDiagram
    participant A as Applicant
    participant W as Website
    participant D as Duplicates
    participant DB as MariaDB
    participant AD as Admin
    A->>W: submit registration (CNIC, email, WhatsApp, LinkedIn)
    W->>DB: registration saved (hash-only CNIC on user)
    W->>D: scanAndAlert(reg, user)
    D->>DB: compare signals vs all registrations
    alt match found
        D->>DB: duplicate_alerts row(s) + audit (duplicate.suspected)
        D->>AD: in-app notification to every admin
    end
    AD->>W: /admin/duplicates — side-by-side review
    AD->>W: Confirm → status=confirmed + new registration auto-vetoed
    AD->>W: Dismiss → status=dismissed

Admin review

• /admin/duplicates — queue ordered new-first, score desc; chips show matched signals.
• Registrations list shows a red ⚠ dup badge; filter chip "dupes".
• Overview KPI card counts open alerts.
• Confirm duplicate → the new registration is vetoed (excluded from voting & winners);

Dismiss → closed. Both audit-logged (duplicate.confirmed / duplicate.dismissed).

Data touched

Rules applied

BR-011 (detection + flag-and-review), BR-005 (veto path reuses admin veto), NFR-06 (PII minimization: CNIC hash-only).