build.allanninal.dev

Part 5 of 7 · Vendor onboarder series ~5 min read

How a vendor file gets approved

Bright Spark Electrical just uploaded their last document. Every required item is present, in date, and confirmed, so the file flips to ready-to-approve and a message lands in the owner’s inbox: the whole Bright Spark file, every item green, with an Approve button. What happens when they tap it? And what if they don’t? This post walks through the three things the owner can do with a finished file — approve, request a fix, reject — and how the system of record, the file state, and the audit trail all stay in sync. This is the human-in-the-loop step the whole system is built around: nothing is added without it.

Key takeaways

  • Three actions on the finished file: approve (write to the system of record), request a fix (send back one item), reject.
  • Approve is the only action that adds the vendor — and it only ever happens on a human tap.
  • Request-a-fix re-opens one item and re-starts the chase for just that document.
  • Every action writes an audit row with who acted, when, and the file they saw.
  • The Approve button is backed by a Function URL; the click is signed and logged.

Three actions on the finished file

Three actions on the finished vendor file A diagram showing one input on the left flowing through the owner's review, then branching into three action paths. Far left: a "File ready for owner" box showing the complete file — vendor name, every required item green, a link to view each document — with three button placeholders below: Approve, Request fix, Reject. The owner taps one button. The middle column shows the three branches. Branch one, Approve: a Function URL Lambda writes the vendor to the system of record (the accounting tool) via its API, locks the file so the documents can't be changed, marks the vendor approved, and writes an approved event to the audit trail. This is the only action that adds the vendor. Branch two, Request fix: opens a small form where the owner picks which item needs redoing and adds a note; the Function URL Lambda re-opens just that one item on the checklist, sends the vendor a message asking for a fresh copy, and re-starts the chase for that single item. The rest of the file stays as it was. Branch three, Reject: closes the file without adding the vendor, with a reason; useful when the vendor falls through or fails a check that can't be fixed. The right side shows the convergence: every action writes a row to the vo-audit DynamoDB table with timestamp, vendor id, action, by-user, and the file snapshot the owner saw. A note at the bottom: only Approve adds the vendor — and it never happens without a human tap. File ready for owner vendor, items, links [Approve] [Request fix] [Reject] Action 1 Approve • Write vendor to the system of record • Lock the file • The only action that adds Action 2 Request fix • Pick the item to redo + a note • Re-open that one item, re-chase just it Action 3 Reject • Close the file with a reason • Vendor is not added — nothing written Audit trail DynamoDB vo-audit timestamp · vendor_id action · by-user file snapshot Only Approve adds the vendor — and it never happens without a human tap. Every action is logged.
Fig 5. Three actions on the finished file, three different effects. Approve writes the vendor to your system of record and locks the file. Request-a-fix re-opens one item. Reject closes it. Every action writes to the audit trail.

Action 1: approve (the common one)

The owner opens the message, sees every item green, clicks through to spot-check the certificate and the bank details, and taps Approve. That tap submits to a Function URL Lambda, and three things happen, in order. First, the vendor is written to your system of record — your accounting tool — via its API: the name, the bank details, the tax-ID, and a link back to the document file. Second, the vendor folder is locked so the approved documents can’t be quietly swapped later. Third, an action: approved row is written to vo-audit with the user, the timestamp, and a snapshot of the file exactly as the owner saw it.

This is the one action that adds the vendor, and it is the whole reason the system exists in its careful shape. Everything before it — the checking, the chasing, the confirmations — is in service of putting a complete, verified file in front of a person so that this tap is a quick yes, not a leap of faith. The system never makes this decision itself.

Action 2: request a fix (the small redo)

Sometimes the file is complete on paper but something looks off to the human eye — the bank account name doesn’t match the company name, the certificate is for the wrong type of cover, the agreement is signed by the wrong person. The owner taps Request fix, picks the one item that needs redoing from a short list, and adds a note explaining what’s wrong.

The Function URL Lambda re-opens just that one item on the checklist — marking it not-done again — and sends the vendor a message: “Almost there. We just need to redo one item: [the note].” The chase from Part 4 re-starts for that single document, on a fresh cadence, while every other item stays exactly as it was. The vendor doesn’t have to re-send anything that was already fine. When the new copy arrives and the checker clears it, the file returns to ready-to-approve and the owner gets the message again. Request-a-fix is the escape hatch that keeps “the documents are all here but one is wrong” from forcing a full restart.

Action 3: reject (the clean no)

Occasionally a vendor shouldn’t be added at all — the deal fell through, the supplier turned out not to be a fit, or a check failed in a way that can’t be fixed. The owner taps Reject and gives a reason. The Function URL Lambda closes the file, marks it rejected, and stops all chasing. Nothing is written to the system of record — the vendor simply never gets added. The documents stay in S3 for the retention period so there’s a record of what was collected and why it was turned down, and an action: rejected row goes to vo-audit with the reason.

Reject is deliberately as easy as approve. A system that makes it hard to say no quietly pushes people toward yes, which is the opposite of what a human-in-the-loop gate is for.

Every action is logged, every approval is provable

The vo-audit table records every approve, fix-request, and reject with the user who acted, the timestamp, and a snapshot of the file as it stood at that moment — which documents were present, their expiry dates, who confirmed each read. That snapshot is the thing that matters at audit time. When somebody asks, a year from now, “who approved Bright Spark and what did they see?”, the answer is one row: the person, the date, and the exact file they signed off on. The documents themselves live in versioned S3, so the certificate that was valid at approval time is still there even if a newer one replaced it since.

This is the difference between a folder of files and a vendor record you can stand behind. The folder tells you what you have now. The audit trail tells you what was true when the decision was made, and who made it.

Next post: the cost breakdown. The whole pipeline above runs in coffee-money territory at SMB volume; Part 6 explains exactly where the dollars go and why most of the bill is reading documents, not chasing them.

All posts