Skip to main content

Architecture

A Bun and Hono service on Cloud Run. It reads Fulfil on each request and has no database.

Request flow​

  1. API Gateway forwards /tally/* to the service. Cloud Run only accepts calls from the gateway.
  2. Key check: the service confirms the caller's API key with the gateway's authorizer. If the authorizer can't be reached, the request fails with 503 rather than being let through.
  3. Routes read Fulfil, compare, and return the result. Alert routes post to Slack through Birdy Bot.

Every request has a 10-second limit.

The tie-out​

Finance ties out a purchase order in two stages:

StageComparesEndpointsAlert
1. Before goods arriveThe supplier invoice against the purchase order/documents/totals, /documents/line-itemsSupplier Invoice
2. After goods arriveThe supplier invoice against what was received/documents/receipt, /documents/receipt/line-itemsSupplier Shipment

Receiving goods makes Fulfil raise a draft supplier invoice priced at what arrived. Stage 2 compares the vendor's document with that draft. An order leaves stage 2 once finance posts the invoice.

Quantity and amount are compared separately, because the pair tells you what went wrong:

QuantityAmountUsually means
MatchMatchAgreed
MatchDiffersA pricing difference, or a valuation document
DiffersDiffersShort or over shipment, or the wrong document

Tally reports the difference in units, dollars and percent and leaves the judgment to finance. There's no tolerance setting.

Finding the purchase order​

  • A vendor reference and a PO number are both accepted, case-insensitively.
  • A reference that matches two orders returns 409 instead of guessing.
  • Cancelled orders are ignored.
  • The order's warehouse tells a caller whether it's ready-to-ship or made-to-order.

Reading documents​

  • Classify labels files by name: Invoice, Freight Invoice, Packing List, Duty, Sample Invoice, Valuation Invoice, ASN, Shipping Doc, Archive or Unclassified.
  • Match finds the purchase order a filename or email subject refers to.
  • Read pulls totals and every PO reference out of a document, for freight invoices that span several orders.
  • Totals come from PDFs and Excel workbooks. A layout Tally can't read produces an alert asking for a manual check.
  • Per-SKU lines come from the Birdy Grey packing list's Size Detail sheet, or from a vendor invoice that lists SKUs.

Alerts​

AlertPosted when
Supplier InvoiceAfter each stage 1 comparison. An agreement posts as one line; a difference posts a table. Skipped once the invoice is posted or paid
Supplier ShipmentAfter each stage 2 comparison, with an icon showing whether anything differs. Skipped once the invoice is posted or paid
Line-item detailThreaded under either alert, listing the SKUs that differ
Needs reviewOne message listing documents a run couldn't match to a PO. No production workflow calls it yet

Alerts always return 200, reporting sent, suppressed, not_configured or failed. A failed post doesn't fail the caller's run.

Fulfil access​

  • Tally only searches Fulfil. It has no way to call actions such as confirm or cancel.
  • Fulfil rate-limits requests, so Tally spaces out its calls and retries intermittent errors.