Route extracted invoices through validation and review

Application background

A finance team uploads invoice documents and wants usable accounting records. An extraction service reads each document and proposes values such as supplier, invoice number, currency and total. A reviewer handles proposals that do not meet the acceptance rules.

A document can be readable but contain inconsistent totals. Separately, the extraction provider can be unavailable. Those situations require different next steps. A corrected document may also arrive with the same invoice number, so that number alone cannot identify the exact source.

Source data that needs human review

An illustrative extraction result says:

{"invoice_number":"17","currency":"USD","line_amounts_minor":[1000,250],"total_minor":1990}

The lines add to 1,250 cents, but the proposed total is 1,990 cents. That mismatch calls for a document review. A provider timeout, by contrast, supplies no such extracted fields and belongs in the separate provider-failure path.

Validation checks whether proposed fields satisfy the accounting rules. Source identity says which exact document those fields came from. Keep both separate from the business invoice number.

Your assignment

Deliver: Extend the supplied extraction workflow with document-version tracking and a review interface. Give invalid document content and provider failures different next actions.

Required behavior: Preserve source identity/version, extractor version and validated candidate fields. Review-required is a content outcome. Retryable failure is a transport/processing outcome. A corrected source gets a new version and cannot silently reuse an old accepted result.

The required first milestone is a working local implementation of the behavior above. The numbered implementation steps define the scope. The cloud architecture is a later extension, not something the starter has already provisioned.

Get the code and run the supplied example

The code is in the public junior-to-staff repository. Install Git and Python 3.12+. No AWS account or Python packages are required for this first run. If you already have a checkout, use it and skip cloning.

git clone https://github.com/Soulful-Iris/junior-to-staff.git
cd junior-to-staff
python3 examples/ai-systems/demo.py extraction

Supplied code: AI workflow implementation, starting at demo.py. These are local workflows with fixture providers and temporary storage. They do not include the user interface or connect to the AWS services in the diagram.

Example output from the supplied run:

Generated IDs and timestamps may differ. Compare the state transitions and outcomes.

[
  {
    "request": {
      "action": "invoice.extract",
… (more output follows)

Set up your implementation workspace

Create work/03-invoice-review/ in your checkout (or use a separate repository). Copy examples/ai-systems/ there so you can change the workflow and its storage/provider boundaries together. The record and module names below describe what you must implement. They are not a promise that files with those names already exist. Keep a README.md beside your implementation with its exact run commands and observed results.

Local components and state to implement

This table names the records, interfaces or decision inputs for your deliverable. Unless a name is explicitly linked to supplied source above, it is something you create. Implement the local state transitions first, then connect the HTTP, storage or worker boundaries required by the steps.

Implement the assignment

1. Inspect the complete local workflow

Run the extraction demo and follow submission, extraction, validation, retry and review states. Use the retained code walkthrough to identify the source fingerprint and idempotency boundary before adding an OCR/model service.

2. Validate domain meaning

Check required fields, currency, dates and line-total arithmetic using explicit decimal/minor-unit rules. Keep raw suggestions and evidence locations. A schema-valid object can still contain the wrong total or vendor identity.

3. Separate retry from review

Retry transient timeouts under a bounded budget. Route ambiguous content, missing evidence and inconsistent totals to human review. Preserve the previous confirmed decision when a machine retry produces another suggestion.

4. Handle corrected source versions

A new source hash/version creates a new processing intent. Link it to the business invoice and prior review history, then require an explicit decision about superseding confirmed data. Reconciliation records explain which source version reached downstream accounting.

Demonstrate the completed local result

Handoff: In your implementation README, include the start command, one successful operation, the failure case above and the resulting stored state or decision. State which dependencies are simulated. Someone with a fresh checkout should be able to reproduce this without your chat history.

Workload assumptions and capacity decisions

These are constructed exercise assumptions. The stated workload is a design target. The local demonstration does not establish that throughput. Use the estimation constants to check units before choosing capacity.

Map the local implementation to AWS

Deployment status: local only. Running the supplied command creates no AWS resources and configures no cloud connections. The diagram is a proposed deployment of the completed application. Each box needs either a deployed runtime, a provisioned service or an explicitly external dependency.

Read the diagram by following the arrows from the entry point: application code accepts the request or event, the state owner commits it, and any worker produces the later result. The table ties those roles to code and adapter work. Multiple boxes do not imply multiple Python files already exist.

The extractor proposes fields. Deterministic validation and human review decide whether those fields are usable. Separate source versions prevent a retry from hiding a corrected invoice.

Provision resources, then connect the application

Use one disposable AWS environment for the cloud exercise. Put the named resources in infra/template.yaml or your existing IaC tool, pass resource IDs through configuration, and scope each runtime role to its own tables, buckets and queues. The diagram is a design to implement. It is not a claim that these resources have been deployed. Record the commands you used to deploy and remove the exercise resources.

For concrete provisioning commands, configuration wiring and cleanup, use the AWS foundation guide. It includes a deployable table/queue/object-storage foundation and explains which application and service adapters you still implement.

A provisioned queue or table does not make the local program use it. Configure resource IDs in the deployed runtime, replace the local adapter, and replay the same successful and failing operation against that runtime. Record the deployed commit and observable result, then remove the disposable resources using your infrastructure tool.

Extend the design after the baseline works

Worked follow-up: Assemble a multi-file invoice before extraction

Page one may contain the supplier and subtotal while page two contains tax and the final total. Treating each upload as a complete invoice can publish partial or duplicate results.

Revised architecture. Follow the changed responsibility and failure path below. This is a design to implement. The supplied local example does not provision these components.

What to implement. Create a bundle manifest with invoice identity, expected members, object hashes, version and closed state. Do not infer completeness merely from a quiet queue. A sender completion signal or an explicit operator decision closes the bundle. Derive extraction identity from the complete ordered manifest and extraction version. Corrected members create a new bundle version. Publish a reviewed result only if it still matches the current accepted source version.

Walk through the result. Upload page two first and show waiting for source completion. Upload page one, close bundle v1 and extract once. Replace page two with a corrected total to create v2, then replay v1. The old result remains historical and cannot replace v2. Deliver the manifest, completion rule and result-version timeline.

One invoice is split across several files. Define the complete source bundle identity and completion rule before extracting. A partial bundle must not be published as a final invoice.

if existing:
    if existing["source_hash"] != source_hash:
        raise Conflict("record ID reused with different source")
    return existing

python3.12 examples/ai-systems/demo.py extraction