Touli Docs

Appearance

Touli Verification Architecture (DLD) ​

Purpose ​

Define the detailed architecture for deed verification, confidence routing, and manual-review escalation.

Inputs and Outputs ​

Input envelope ​

  • submission_id
  • user_id
  • pillar
  • hours_claimed
  • activity_at
  • declared_location
  • evidence[] (photo/video/location/peer/qr)
  • device_context (device_id_hash, ip_hash, app_version)

Verification output contract ​

  • verification_outcome: approved | rejected | manual_review
  • verify_level: self | photo_only | photo_gps | peer | manager | ngo_qr
  • group_size_bucket: solo | small_group | group | community_moment
  • beneficiary_flag: self | others | community
  • confidence_score: 0.00 - 1.00
  • reason_codes[]
  • review_required: boolean
  • review_deadline_at

Verification State Machine ​

mermaid
stateDiagram-v2
  [*] --> pending
  pending --> processing : dequeue
  processing --> rulesCompleted : rulesPass
  rulesCompleted --> visionCompleted : visionCall
  visionCompleted --> confidenceComputed : blendScore

  confidenceComputed --> approved : scoreGteAutoThreshold
  confidenceComputed --> manual_review : scoreBetweenThresholds
  confidenceComputed --> rejected : scoreLtRejectThresholdOrFraud

  manual_review --> approved : reviewerApprove
  manual_review --> rejected : reviewerReject
  manual_review --> expired_review : slaBreach
  expired_review --> rejected : failClosedPolicy

  approved --> finalized
  rejected --> finalized
  finalized --> [*]

Confidence Routing ​

Baseline thresholds (configurable by market):

  • auto_approve_threshold = 0.75
  • manual_review_lower = 0.40
  • < 0.40 or hard fraud flag routes to reject/manual policy.

Blended score formula:

  • confidence = rules_score * 0.45 + vision_score * 0.35 + trust_score * 0.20

Hard overrides:

  • Known fraud signatures force manual_review or rejected.
  • Evidence integrity failure can force reject regardless of blend score.
  • Market launch mode can downgrade verify_level outcomes before points stage.

Stage-by-Stage Pipeline ​

Stage A: Rules Evaluation ​

  • EXIF/timestamp sanity checks
  • GPS radius check via geospatial query
  • Perceptual hash duplicate checks (user and global corpus)
  • Velocity checks (device/IP/submission cadence)
  • QR authenticity checks

Output:

  • rules_score
  • rules_features (json)
  • rules_reason_codes[]

Stage B: Vision Evaluation ​

  • Vision API checks relevance to declared pillar
  • AI-generated/screen-of-screen detection
  • Contradiction detection against claimed context

Output:

  • vision_score
  • vision_features (json)
  • vision_reason_codes[]

Stage C: Trust and Blend ​

  • Trust score from historical user behavior
  • Blend scores and apply hard override rules
  • Produce initial outcome and escalation decision

Stage D: Manual Review (if escalated) ​

  • Reviewer decision + mandatory reason code
  • Optional structured notes
  • SLA-bound queue management

Human Review Escalation Contract ​

Escalation payload:

  • review_id
  • submission_id
  • snapshot_context (immutable evidence pointers + rule summaries)
  • suggested_outcome
  • reason_codes[]
  • expires_at

Reviewer actions:

  • approve
  • reject
  • request_more_evidence (optional policy-controlled path)

SLA policy:

  • Standard: 24h max
  • Breach behavior: expired_review transitions to fail-closed policy unless overridden by market policy.

Idempotency and Retry Behavior ​

  • Verification jobs are idempotent by submission_id + verification_attempt_version.
  • Duplicate dequeues must no-op after terminal status (approved|rejected).
  • Vision call retries must preserve original request fingerprint and trace id.

Auditability Requirements ​

For each attempt, persist:

  • stage transition timestamps
  • all scores and threshold versions
  • reason codes and actor (system|reviewer)
  • model/provider metadata for vision calls
  • immutable references to evidence at decision time

Data Retention Controls ​

  • Precise GPS and photos are scheduled for deletion according to policy windows.
  • Verification summaries remain for audit and dispute handling.
  • Manual review logs are retained as compliance artifacts.

Failure Modes and Handling ​

  • Vision provider outage: route to manual review on retry exhaustion.
  • Queue backlog: apply admission control and alerting on SLA risk.
  • Corrupt evidence pointer: reject with technical reason code.
  • Rules service degradation: suspend auto-approve mode and fail-safe to review.