System boundary and technical judgment
AI handles document variation. Code controls financial risk.
End-to-end responsibility map
Thirteen stages with an explicit owner
Pipeline
Selected stage · 01 / 13
Intake & file validation
Type, size, and magic-byte checks. No active content ever reaches a browser context.
- Owner
- Deterministic code
- Pipeline position
- Stage 1 of 13
- Review principle
- Explicit responsibility
Selected stage · 02 / 13
OCR & structured extraction
Document rendered and read; header fields and line items extracted into a strict schema (tool-forced JSON).
- Owner
- AI model
- Pipeline position
- Stage 2 of 13
- Review principle
- Explicit responsibility
Selected stage · 03 / 13
Evidence alignment
Every extracted value is aligned against the OCR/text-layer token positions. A value that can't be found in the document drops to ‘uncertain’ — the model never emits its own bounding boxes.
- Owner
- Deterministic code
- Pipeline position
- Stage 3 of 13
- Review principle
- Explicit responsibility
Selected stage · 04 / 13
Instruction screening
Notes and free-text fields are scanned for instruction-shaped content before anything downstream reads them.
- Owner
- Deterministic code
- Pipeline position
- Stage 4 of 13
- Review principle
- Explicit responsibility
Selected stage · 05 / 13
Arithmetic validation
Line totals, subtotal, tax, and grand total are recomputed from scratch using decimal-safe code — never trusted from the printed figure.
- Owner
- Deterministic code
- Pipeline position
- Stage 5 of 13
- Review principle
- Explicit responsibility
Selected stage · 06 / 13
Supplier identity match
Tax ID first, name as a supporting signal only. Multiple credible matches or a new supplier never auto-resolve.
- Owner
- Deterministic code
- Pipeline position
- Stage 6 of 13
- Review principle
- Explicit responsibility
Selected stage · 07 / 13
Duplicate detection
File hash, normalized identity (supplier + invoice number + date + amount), and line-item fingerprint — runs before any approval routing.
- Owner
- Deterministic code
- Pipeline position
- Stage 7 of 13
- Review principle
- Explicit responsibility
Selected stage · 08 / 13
PO & receipt matching
Supplier, currency, status, and remaining balance compared; SKU takes precedence over description similarity.
- Owner
- Deterministic code
- Pipeline position
- Stage 8 of 13
- Review principle
- Explicit responsibility
Selected stage · 09 / 13
Tolerance & exception rules
Configured, versioned tolerances decide pass/fail — not a confidence score.
- Owner
- Deterministic code
- Pipeline position
- Stage 9 of 13
- Review principle
- Explicit responsibility
Selected stage · 10 / 13
Exception summary drafting
Designed but not implemented in this build: this stage would generate a plain-language explanation from already-verified control results, without the model seeing or drafting from unscreened invoice text. It isn’t called anywhere in the current pipeline — the decision reason strings below are produced deterministically instead.
- Owner
- AI model
- Pipeline position
- Stage 10 of 13
- Review principle
- Explicit responsibility
Selected stage · 11 / 13
Decision & routing
Ready / Exception / Duplicate Hold / Blocked, with an approval route and required actions.
- Owner
- Deterministic code
- Pipeline position
- Stage 11 of 13
- Review principle
- Explicit responsibility
Selected stage · 12 / 13
Accounting draft
Idempotent draft-bill creation only. No workflow can execute a payment.
- Owner
- Deterministic code
- Pipeline position
- Stage 12 of 13
- Review principle
- Explicit responsibility
Selected stage · 13 / 13
Human review
AP and approvers act on exceptions, holds, and blocks — every decision recorded to the audit trail.
- Owner
- Human review
- Pipeline position
- Stage 13 of 13
- Review principle
- Explicit responsibility
What AI does
- Locating candidate fields across varied invoice layouts
- Extracting header data and line items to a strict schema
- Classifying invoice type
- Mapping free-text descriptions to likely PO lines
- Drafting an exception summary from verified control results
- Explaining discrepancies in plain language
What deterministic code decides
- Decimal arithmetic and total recalculation
- Supplier-master comparison, tax-ID and domain normalization
- Exact and fuzzy duplicate rules
- Quantity and unit-price tolerances, PO balance checks
- Approval thresholds and accounting-period rules
- Idempotency, permissions, retry limits
- Instruction-shaped-content screening
The model proposes extracted values. Deterministic code decides whether they satisfy financial controls — never the other way around.
Tolerance policy
Fictional v1 values — all versioned as configuration (current: policy_2026.3).
| Unit price | Lower of 2% or $25 per line |
| Quantity | Zero, unless a receipt records the additional quantity |
| Total invoice | Lower of 1% or $50 |
| Tax | $0.02 rounding only |
| Invoice date | Cannot precede the PO date |
| Due date | Cannot precede the invoice date |
Security & privacy
- Invoice text and QR codes are treated as untrusted data — embedded instructions directed at the model or operator are ignored, never executed.
- File type, size, and magic bytes are validated at intake. A real AV engine is not practical on serverless infrastructure — this is documented as a production deployment requirement, not simulated.
- All tables are RLS-locked to service-role access only, from the first migration.
- Remittance/bank details from an invoice never overwrite the supplier master, ever.
- Bank and tax identifiers are masked in ordinary logs; full document text is kept out of model-provider logs.
- Invoice submitters cannot approve their own invoices.
- No real supplier or financial data appears anywhere in the public portfolio.
Stack & integrations
- App
- FastAPI (Python, async ASGI) with server-rendered Jinja2 templates
- Data
- PostgreSQL via SQLAlchemy — NUMERIC money, audit events, jobs; a durable worker process drains the job queue outside the request path
- Extraction
- Anthropic Claude, native PDF/vision input, tool-forced JSON schema output
- Deployment
- Docker Compose — app, worker, and Postgres as separate services
- Accounting integration
- A sandbox accounting adapter — draft-bill change sets only (the AccountingBill model and proposedAccountingChange on each decision are real). External OAuth integration (e.g. QuickBooks Online) is intentionally out of scope for this build; the public demo stops before any external write.
Built by Ariel
Ariel Magalso
AI Engineer
Philippines · Remote
The architecture makes the model boundary inspectable.
This design demonstrates evidence alignment, decimal-safe arithmetic, identity resolution, duplicate rules, versioned tolerances, approval routing, idempotency, security boundaries, and honest integration limits.