AI invoice reader project · Chapter 8 of 12

The review API

By the end of this chapter you can give Rafiq his review queue as an API: list what waits for him, approve an invoice, correct the fields the model read wrong (keeping every change), and make sure that when two reviewers press a button on the same task at the same moment, only one of them closes it, with SELECT ... FOR UPDATE. Build it in your browser: a real editor and terminal, AI that explains, and tests that tell you when it works.

  • Part: People and volume
  • 3 tasks
  • Python
  • In the all labs plan

The first 2 chapters of AI invoice reader project are free. This one comes with the all labs plan.

Why you need this

Chapter 7 stores every invoice and opens a review task for the ones a person must see. But a task can only be read in psql. Rafiq cannot close one, and he certainly cannot fix one.

Two real ones are waiting. ganesh-sg-1052.pdf prints 09/10/2026, and the model stored 10 September. surat-sst-0937.pdf prints the GSTIN 24AAGFS7671H1ZZ: a typo on the supplier's own bill (Surat Steel's GSTIN on its other invoice is 24AAGFS6671H1ZZ). The model copied it as printed, as it should, and the check character rule caught it. That is the September mistake that would have lost the GST input credit on Surat Steel's ₹16,002 of IGST. Rafiq needs to put in the right date and the right GSTIN, and DabbaDrop needs to remember that he did: what was stored, what he changed it to, and who.

And at month-end Rafiq is not alone. A colleague from accounts helps with the close, and both open the queue. If both press a button on the same task in the same second, today's code would let both win.

What you build: 3 tasks

Each task has tests. You write the code in the lab's editor and press Check.

  1. Task 1

    service.py: the queue, and approving

    In app/review/service.py write open_tasks(db): every open ReviewTask joined to its InvoiceRow, oldest first (created_at, then id), each {"task_id", "invoice_id", "file", "kitchen", "reason", "created_at" (isoformat())}. Then approve(db, task_id, reviewer): task, inv = take(db, task_id); an invoice with no data raises AppError(422, "no_data", ...); otherwise close(task, inv, reviewer, "approved", "approved"), commit, and return {"task_id", "invoice_id", "status"}.

    The Check reads five invoices with the given pipeline (four need review), compares your list with its own query, approves patel-prg-0462.pdf and tries to approve the scanned bill. It uses its own take, so this task stands alone.

  2. Task 2

    service.py: correcting fields

    Write correct(db, task_id, reviewer, changes): take the task; a key that is not a field of Invoice raises AppError(422, "bad_correction", ...); Invoice.model_validate({data, changes}) (a ValidationError becomes AppError(422, "bad_correction", a sentence, details=a list of "<loc>: <msg>")); check_invoice it. For each changed field whose stored value differs: a Correction (old, new, by=reviewer.email), and its FieldRow set to the new value, confidence 1.0, reasons [f"corrected by {reviewer.name}"]. Store the new data and problems; with no problems close the task ("corrected", "approved"), else keep it open with the problems' messages as its reason. Commit; return {"task_id", "invoice_id", "status", "problems"}.

    The Check corrects ganesh-sg-1052.pdf's date (read month first) after two bad corrections, then gives surat-sst-0937.pdf another wrong GSTIN.

  3. Task 3 · interview question

    Interview: service.py, one reviewer per task

    Write take(db, task_id): the ReviewTask read with select(...).with_for_update() (SELECT ... FOR UPDATE: its row stays locked until the transaction ends). None raises AppError(404, "not_found", ...); a task that is not open raises AppError(409, "already_closed", a sentence naming task.closed_by). Return (task, db.get(InvoiceRow, task.invoice_id)).

    The Check asks for task 999, approves a closed task, then holds a task's row locked in a transaction of its own while your approve runs in a thread: approve must wait, and once the check closes the task as another reviewer and commits, your approve must raise 409. Then GET /review/tasks as Meera (403) and as Rafiq (200).

    Kunal will ask: Rafiq and his colleague open the same task and both press Approve. What happens without FOR UPDATE, and what does it do?

What you will learn

  • A join that gives pairs: a task and its invoice in one query.
  • Approve, correct, reject: what each means for the invoice and the task.
  • A correction, checked again: the whole invoice validated with the change in it, and the rules run again.
  • The corrections table: old value, new value, who, when.
  • A lost update: two reviewers who both read "open", for real.
  • Row locks: SELECT ... FOR UPDATE (.with_for_update()), who waits, and what they see after.

More in People and volume

Build The review API yourself

DabbaDrop's kitchens get piles of supplier invoices, typed and messy. You build the pipeline that reads them, checks every number, and sends the doubtful ones to a person. A real editor and terminal in your browser, AI that explains, and a Check that says when it works.

The first 2 chapters of AI invoice reader project are free. This one comes with the all labs plan.