Architecture
A Bun and Hono service on Cloud Run. It reads Fulfil on each request and has no database.
Request flowβ
- API Gateway forwards
/tally/*to the service. Cloud Run only accepts calls from the gateway. - 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
503rather than being let through. - 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:
| Stage | Compares | Endpoints | Alert |
|---|---|---|---|
| 1. Before goods arrive | The supplier invoice against the purchase order | /documents/totals, /documents/line-items | Supplier Invoice |
| 2. After goods arrive | The supplier invoice against what was received | /documents/receipt, /documents/receipt/line-items | Supplier 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:
| Quantity | Amount | Usually means |
|---|---|---|
| Match | Match | Agreed |
| Match | Differs | A pricing difference, or a valuation document |
| Differs | Differs | Short 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
409instead 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 Detailsheet, or from a vendor invoice that lists SKUs.
Alertsβ
| Alert | Posted when |
|---|---|
| Supplier Invoice | After each stage 1 comparison. An agreement posts as one line; a difference posts a table. Skipped once the invoice is posted or paid |
| Supplier Shipment | After each stage 2 comparison, with an icon showing whether anything differs. Skipped once the invoice is posted or paid |
| Line-item detail | Threaded under either alert, listing the SKUs that differ |
| Needs review | One 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.