The client brief

Every project here starts the same way. Before models, before Azure, before a single dependency, you understand the client and the recurring problem. The documents and the workflow determine the schema, the model choice, the validation rules, and the UI. Starting from a framework would hide all of those decisions.

The company

Northstar Facilities B.V. is a fictional facilities-management company based in Amsterdam. It buys cleaning, maintenance, electrical, plumbing, and equipment services from suppliers across the European Union.

Maya works in finance and administration. Supplier invoices and employee expense receipts arrive as digital PDFs, scans, screenshots, and phone photos. They may be written in English, Dutch, German, or French. Before a document enters bookkeeping, Maya needs to know what it is, confirm the important values, check VAT and totals, and assign the correct general ledger (GL) account.

Today that is manual work, document by document, in four languages.

The user story

As a finance administrator at a European company, I want to upload a multilingual invoice or receipt and receive a prepared review containing the best combined extraction, VAT and policy results, and a suggested GL account so I can approve valid documents quickly and turn supplier errors into a clear correction request.

Read that carefully. Maya does not want an autonomous system that approves invoices. She wants a prepared review. The app does the reading, checking, and suggesting; she keeps the decision. That distinction drives everything that follows.

What the app must do

The scope for this build:

• Accept one PDF or image per upload, with a 4 MB limit
• Recognize whether the document is an invoice or a receipt automatically
• Extract supplier and customer details, VAT IDs, dates, purchase order, currency, totals, and line items
• Validate EU VAT number formats offline and reconcile subtotal, VAT, and total
• Apply separate deterministic policies for invoices and receipts, including duplicate detection
• Suggest a GL account from a fixed Northstar catalog, with the reviewer able to override
• Let Maya correct fields, approve, reject, and draft (never send) a supplier correction email
• Keep a review history with explicit deletion so a demo can be reset

Just as important is what stays out. No authentication, no queues, no email ingestion, no accounting-system integration. This is a teaching skeleton that keeps the engineering boundaries visible, not a production accounts-payable product.

The rule that shapes the architecture

One idea carries this whole project. Models extract evidence, deterministic code decides policy, and the human owns the final decision.

Azure will read the documents and even suggest an account. But whether an invoice is approvable is a question about Northstar's rulebook, and a rulebook belongs in ordinary Python that you can read, test, and reproduce offline. When we get to business rules, you will see the whole policy expressed as pure functions. Keep this split in mind every time a model output shows up.

Checkpoint

You should be able to describe, without mentioning any implementation:

• Who the user is and what her recurring problem looks like
• What a prepared review contains
• Which decisions the app makes and which decisions Maya keeps
• What is deliberately out of scope

Next: The sample documents

A fictional multilingual corpus with deliberate failures, and the manifest that defines what working means.