POA System

Summary

POA is the purchase order acknowledgement workflow: document intake, interpretation, matching, validation, operator repair, and external sync. It is a mature example of the platform's human-in-the-loop state-machine pattern. Automation reads evidence and proposes structure; operators repair ambiguity; jobs resume and synchronize only after state is safe enough to continue.

This thread explains POA from the operator queue backward. A reader should understand why POA is not just document parsing, and why repair and external sync are first-class parts of the module.

Module At A Glance

Reader Question

How does the platform ingest procurement documents, interpret them, validate them against operational context, expose repairable issues, and synchronize accepted results outward?

Surface Or Workflow

The entry surfaces are POA operator queues and POA greenfield routes. An operator sees acknowledgements, interpreted fields, matching evidence, validation failures, document artifacts, and available repair actions. They need to decide whether automation found the right job, purchase order, packing slip, invoice, credit memo, or confirmation context.

The engineer enters through POA services, jobs, route maps, tests, and runbooks. The question is usually which stage failed: intake, document runtime, interpretation, lookups, matching, diagnostics, command dispatch, or external sync.

Architecture Rationale

POA carries workflow state because procurement ambiguity is operationally meaningful. A parser can extract fields, but only a state machine can preserve evidence, pause on mismatch, let an operator repair context, and dispatch external sync only after validation.

Lifecycle

The lifecycle starts with source intake. POA jobs and services collect documents or source references, normalize them into domain runtime state, and prepare artifacts for interpretation. Interpretation uses deterministic logic, document processors, and model-assisted paths where appropriate, but the result is still validated against POA domain rules.

Matching and validation decide whether interpreted evidence can safely map to operational entities. Ambiguity becomes cases, issues, diagnostics, or repair actions rather than an uncaught failure. Operators use the repair surface to correct state with actor context.

External sync is the final operational side effect. It should consume accepted domain state and leave audit evidence. If sync fails or becomes ambiguous, the module should expose a repairable status rather than hiding provider behavior inside a job.

Child Threads

  • POA Console Orientation: operator queue, stage dashboard, case detail, diagnostics, and history surfaces.
  • POA Workflow State Machine: the system-level lifecycle from source intake through interpretation, matching, validation, repair, command dispatch, sync, and audit.
  • POA Source Intake Workflow: SharePoint source scanning, fingerprints, batches, source records, and cases.
  • POA Interpretation Workflow: document processors, model-assisted interpretation, validation, and structured output.
  • POA Matching And Validation Workflow: matching evidence, lookup context, policy checks, and validation failures.
  • POA Matching Methodology: how interpreted evidence, candidate scoring, policy checks, workflow state, review, and command eligibility fit together.
  • POA Operator Repair: cases, issues, diagnostics, field corrections, commands, and retries.
  • POA External Sync Workflow: QBO, Spectrum, SharePoint-style outbound sync, command dispatch, and audit.
  • POA Operations And Runbooks: smoke checks, debugging, diagnostics, and repair runbooks.

Implementation Boundaries

app/web/app/poa and app/web/app/poa-greenfield are operator surfaces. app/api/poa adapts requests. services/poa owns domain state, document runtime, interpretation, diagnostics, jobs, lookups, commands, and sync helpers. jobs/poa remains thin entrypoints around reusable service behavior. tests/poa and docs/runbooks/poa should become direct child-thread evidence as the recursive POA tree is drafted.

Tradeoffs

POA carries more state than a parser because procurement ambiguity is operationally meaningful. The system must preserve evidence, allow repair, and resume safely. That makes the architecture heavier, but it prevents fragile automation from silently synchronizing the wrong interpretation.

Visual

The current visual is a graph neighborhood. The intended first-level visual is a POA lifecycle diagram: source intake, interpretation, matching/validation, operator repair, command/sync execution, and audit.

Operator Narrative

The POA operator is not simply approving extracted text. They are resolving a procurement event. A document or source signal arrives with evidence about a purchase, receipt, invoice, credit memo, acknowledgement, or confirmation. The platform has to decide what that evidence means, which operational entities it matches, whether the result is safe to sync, and what an operator must repair when confidence is not high enough.

That is why the POA surface is queue and case oriented. The operator needs to see interpreted fields, document artifacts, matching candidates, validation failures, command affordances, provider diagnostics, and history in one workflow. A table of parsed documents would not be enough. The surface has to show why a document is blocked, which repairs are available, and what will happen if the operator retries or dispatches a command.

The workflow is also temporal. A document may be interpreted before all lookup context is ready. A command may wait on a receipt. A provider sync may fail after the platform accepted the domain state. A repair may unlock a later stage. POA therefore needs durable stage and issue state rather than a single success/failure flag.

Evidence And State

POA's strongest architectural lesson is that evidence and state are different. Document processors, OCR, model-assisted interpretation, and deterministic parsers produce evidence. Matching policy, validation rules, and operator repairs decide state. Keeping those separate lets the system preserve the source artifact even when the interpretation changes.

A corrected job number, vendor, purchase order, invoice route, packing slip assignment, or command eligibility decision should not erase the fact that the source document was ambiguous. The platform should retain the original evidence, the automated interpretation, the validation issue, the operator correction, and the resulting command state. That history is what makes later support and audit possible.

This same distinction explains why commands are separate from interpretation. Interpreting a document is not the same as writing to an accounting provider, moving a file, or updating an external system. Commands need payload rendering, dependency checks, eligibility, idempotency, dispatch, provider results, and diagnostics. A valid interpretation can still produce a blocked command if a provider dependency is missing.

Repair And Resumption

POA repair should be narrow and explicit. An operator should be able to fix the field or relationship that is blocking the workflow without manually editing unrelated state. Repair actions should record actor context and should make it clear which downstream stages need to be retried. The system should then resume through services and jobs rather than relying on an engineer to run an ad hoc database update.

This model turns common procurement ambiguity into workflow data. Wrong vendor? Create a vendor-resolution issue or correction. Ambiguous packing slip? Expose candidate evidence. Provider write failed? Record the command result and retryability. Missing source file? Keep intake state blocked and point to source recovery. Each failure mode gets a state shape that support can reason about.

POA also shows why human repair and automation are not opposites. Automation does the repeatable work: source scanning, interpretation, matching, validation, command rendering, and sync dispatch. Human repair handles the ambiguous decisions that should not be automated blindly. The platform is valuable because it lets the two cooperate without losing evidence.

Integration Boundary

The external sync stage should be read through the provider-boundary lens. POA may interact with accounting, document, or operational providers, but the POA domain should consume internal command results and diagnostics. Provider clients should not leak into UI components or route handlers. Commands should carry enough context to decide idempotency, retry, blocked state, and audit.

This makes POA a useful reference for other workflows that combine document interpretation with external side effects. The same pattern can apply to finance sync, notification delivery, precon document publication, or any workflow where a human-reviewed interpretation eventually becomes a provider write.

Why POA Needs Workflow State

POA is not just a document interpretation feature. It is a workflow where uncertain evidence can lead to real operational commands. That is why state is central. The system needs to know what evidence was collected, which interpretation was proposed, what an operator accepted or corrected, which command was prepared, whether it was dispatched, and what provider outcome came back.

Without that state, the platform would be unable to distinguish a parsing problem from a provider failure or an operator hold. With it, POA becomes repairable. A support person can resume from the failed step, inspect the evidence, and decide whether to retry, correct, or stop the workflow.

Source Evidence

  • docs/domains/poa.md
  • docs/domains/poa-greenfield-route-map.md
  • app/web/app/poa
  • app/web/app/poa-greenfield
  • app/api/poa
  • services/poa
  • jobs/poa
  • tests/poa
  • docs/runbooks/poa