flow

KPI Scorecard — tool-call lifecycle

One kpi_scorecard call end to end: four sources fold into 7 KPIs; with publish: true the service performs the one direct bounded write (a dated Smartsheet snapshot row).

Flow

Overview

Mostly a pure read (three sources → 7 KPIs), with the one deliberate CQRS exception in the system: publish: true performs Smartsheet Append Scorecard RowSmartsheet Append Scorecard RowCommandv0.1.0Appends a dated KPI snapshot row to the scorecard sheet, preserving formula columns. The one write that does NOT route t...Ownervisionary-engineeringMapView docs directly from the read service — bounded (one dated row, formulas preserved), WRITE_MODE-throttled, but not routed through the approval bus. Flagged in the audit to close or declare (ADR §5 auto-approve list). The Sheets Read (scorecard sheet + columns)Sheets Read (scorecard sheet + columns)Queryv0.1.0Smartsheet sheet + column reads (static PAT) used to locate the scorecard sheet and protect formula columns on publish..Ownervisionary-engineeringMapView docs locate/verify step precedes the append on the publish path.

The flow

How it works

  1. Max (agent) on claude.ai → MCP tool call
  2. KPI Scorecard → direct request/response — no events
  3. ScorecardService → cash + AR/AP / open SO/PO values / open weighted pipeline / publish: true → direct bounded write (WRITE_MODE-throttled)
  4. Accounting Read → vendor API
  5. Inventory Read → vendor API
  6. CRM Read → vendor API
  7. Smartsheet Append Scorecard Row (publish: true only) → sheets-read locates the sheet first
  8. QuickBooks Online → results fold in
  9. Fishbowl Inventory → absent → the two order-book KPIs omitted (never zero-filled)
  10. ClaritySoft CRM → results fold in
  11. Smartsheet → snapshot row appended (formula columns preserved)
  12. ScorecardView assembled → 7 KPIs with status returned in the tool result