Judgement

This document describes the Judgement feature, where Referees approve or reject evidence submitted by Taskers.

1. Prerequisites

  • Task Lifecycle — Judgements exist within the Task → Request → Judgement hierarchy.

  • Evidence Submission — Evidence must be submitted before a Referee can judge.

2. Overview

After a Tasker submits evidence, the assigned Referee reviews it and either approves or rejects it with a comment, so that the Tasker receives feedback on their task completion. The judgement is performed via the judge_evidence RPC, which validates the caller, checks the current status, and updates the judgement record.

3. Judgement Flow

The following sequence diagram illustrates the full judgement flow, including evidence submission notification, the judge action, and the optional rejection-resubmission cycle.

Diagram

4. State Transitions

Judgement status values (PostgreSQL enum judgement_status):

Status Description Transitions To

awaiting_evidence

Initial state. Waiting for Tasker to submit.

in_review, evidence_timeout

in_review

Evidence submitted. Referee is reviewing.

approved, rejected, review_timeout

approved

Referee approved. Tasker can confirm & rate.

Confirmed (via is_confirmed = true)

rejected

Referee rejected. Tasker may resubmit (once, before due date).

in_review (resubmission), Confirmed

review_timeout

Referee failed to judge in time.

Confirmed

evidence_timeout

Tasker failed to submit evidence in time.

Confirmed
For the full state diagram including Task and Request lifecycles, see Task Lifecycle.

5. Technical Components

5.1. RPC: judge_evidence

  • Parameters: p_judgement_id (uuid), p_status (judgement_status: approved or rejected), p_comment (text)

  • Validation:

    • Caller must be the matched referee for this judgement.

    • Current judgement status must be in_review.

    • Comment must be non-empty.

    • Status must be approved or rejected.

5.2. Flutter: JudgementSection widget

  • Displays an inline form for referees when status is in_review.

  • Shows read-only result cards (avatar, status, comment) for completed judgements.

  • Displays a confirmation form for the tasker when status is approved or rejected and is_confirmed = false:

    • Binary rating buttons (positive / negative) for the Referee.

    • Optional comment field.

  • Uses JudgementController (AsyncNotifier) and JudgementRepository.

5.3. Triggers: Notifications

  • on_task_evidences_upserted_notify_referee — Notifies the referee when evidence is submitted or updated.

  • on_judgements_status_changed — Notifies the tasker when judgement is approved or rejected.

Both triggers use the notify_event() function, which calls the send-notification Edge Function.

6. Confirm Judgement

After a Referee approves or rejects, the Tasker confirms the judgement via confirm_judgement_and_rate_referee RPC. This atomically settles points, grants the Referee a reward, and records a binary rating (is_positive). See Payment & Reward Flow for settlement details.

7. Confirm Evidence Timeout

When evidence times out, settlement happens automatically via the settle_evidence_timeout trigger (see Evidence Submission). The Tasker then calls confirm_evidence_timeout RPC to set is_confirmed = true, which may trigger task closure.

8. Data Model

8.1. judgements table

Column Type Description

id

uuid (PK, FK → task_referee_requests)

Shares ID with its parent request

status

judgement_status (enum)

Current judgement state

comment

text

Referee’s comment (required on approve/reject)

is_confirmed

boolean

Whether the judgement has been finalized

reopen_count

smallint

Number of times evidence was resubmitted (max 1)

9. Related Links