InvoiceGuard

• 

• 

• 

• 

• 

🧾 InvoiceGuard: A Human-Gated Multi-Agent System for Intelligent Invoice Validation, Risk Detection, and Financial Review

📋 1. Project Overview

InvoiceGuard is an agentic invoice-processing and financial-risk review platform that we built to demonstrate how AI-assisted automation can help finance teams process invoices while keeping consequential financial decisions under human control.

The core idea is simple: invoice automation should do much more than extract a few fields from a document.

When an invoice enters InvoiceGuard, the system:

• 📄 Extracts structured invoice information
• 🔎 Retrieves the corresponding vendor and purchase-order context
• ✅ Validates the invoice against procurement records
• ⚠️ Detects duplicate invoices, amount anomalies, unapproved vendors, and PO/vendor conflicts
• 📊 Assigns an explainable risk level and risk score
• 🚨 Surfaces high-risk invoices for review
• 🧑‍⚖️ Requires a human to make the final approve/reject decision
• 📜 Records the processing and decision history in an audit trail

Instead of allowing an AI system to autonomously approve financial transactions, InvoiceGuard deliberately separates automated analysis from human authorization.

Every processed invoice ends in:

pending_review

regardless of whether it is low, medium, or high risk.

Only an explicit human action can change that state to:

approved

or:

rejected

InvoiceGuard is currently a working, tested prototype designed to demonstrate this architecture end-to-end. It is not presented as a production-certified accounts-payable system.

❓ 2. Problem We Wanted to Solve

Invoice processing looks straightforward until organizations start handling hundreds or thousands of invoices.

Finance teams need to answer questions such as:

• 🔁 Has this invoice already been submitted?
• 🏢 Is this supplier approved?
• 📋 Does the invoice correspond to a real purchase order?
• 💰 Does the amount agree with the PO?
• 📈 Is the amount unusual compared with the supplier's historical invoices?
• 🔗 Does the PO actually belong to the vendor named on the invoice?
• 🚨 Which invoices deserve immediate attention?
• 🧑‍⚖️ Who ultimately approved or rejected the invoice?
• 📜 Can we reconstruct why the system flagged it?

A simple OCR or LLM extraction tool does not solve these problems.

The challenge is not merely:

"Can AI read an invoice?"

The more useful question is:

"Can we build an explainable workflow that reads an invoice, retrieves business context, validates it, identifies financial risk, and supports a human reviewer without allowing the AI to make the final financial decision?"

That became the central idea behind InvoiceGuard.

💡 3. Why We Chose This Project

We wanted to build something that demonstrated a genuine agentic workflow, rather than putting a chatbot interface around an LLM.

Invoice processing was a good fit because different stages naturally require different responsibilities:

• 📄 Information extraction
• 🔎 Business-context retrieval
• ✅ Validation
• ⚠️ Risk assessment
• 🚨 Monitoring
• 🧑‍⚖️ Human authorization

This allowed us to separate the workflow into specialized components instead of asking one model to perform every task.

It also gave us an opportunity to combine:

• 🤖 Multi-agent orchestration
• 📄 Document processing
• 🔎 Retrieval against structured business data
• 📊 Explainable risk scoring
• 🧑‍⚖️ Human-in-the-loop governance
• 📜 Auditability
• 🗄️ Relational data
• ⚛️ A full finance-review frontend
• ☁️ Production-oriented deployment architecture

One of our priorities was also graceful degradation.

InvoiceGuard can use Claude when the Anthropic API is configured for extraction, but the application does not become unusable without an external model. A deterministic extraction path allows the core demo workflow to continue functioning.

👥 4. Who Could Use This System

InvoiceGuard demonstrates an architecture that could be relevant to:

• 💼 Accounts-payable teams reviewing incoming invoices
• 🧾 Finance departments processing supplier payments
• 🛒 Procurement teams reconciling invoices against purchase orders
• 🔍 Internal audit and compliance teams investigating suspicious transactions
• 🏢 Organizations looking to introduce AI-assisted invoice processing without removing human authorization
• 🧑‍💻 Developers exploring explainable and human-gated agentic financial workflows

The current implementation is a prototype and demonstration platform rather than a production accounting or payment system.

⚙️ 5. How the System Works

The central architectural decision was to separate invoice processing into specialized stages coordinated by an orchestrator.

Invoice Text / PDF
        ↓
   Orchestrate Agent
        ↓
┌───────────────────────────┐
│       Extract Agent       │
│ Invoice → structured data │
└─────────────┬─────────────┘
              ↓
┌───────────────────────────┐
│      Retrieve Agent       │
│ Vendor + PO + history     │
└─────────────┬─────────────┘
              ↓
┌───────────────────────────┐
│      Validate Agent       │
│ Business-rule validation  │
└─────────────┬─────────────┘
              ↓
┌───────────────────────────┐
│       Assess Agent        │
│ Risk score + risk flags   │
└─────────────┬─────────────┘
              ↓
┌───────────────────────────┐
│       Monitor Agent       │
│ High-risk alert handling  │
└─────────────┬─────────────┘
              ↓
        pending_review
              ↓
        HUMAN REVIEWER
           ↙      ↘
     approved    rejected
              ↓
         Audit Trail

The orchestrator coordinates the pipeline but is deliberately prevented from approving invoices.

That boundary is enforced in the application logic.

✨ 6. Main Features We Implemented

InvoiceGuard currently includes:

• 🤖 Specialized agent pipeline for extraction, retrieval, validation, assessment, monitoring, and orchestration
• 📄 Text and PDF invoice submission
• 🧠 Optional Claude-based invoice extraction
• 🛡️ Deterministic extraction fallback
• 🏢 Vendor lookup and approval verification
• 📋 Purchase-order retrieval
• 🔢 Explicit PO-number matching
• 💰 Amount-proximity PO matching where appropriate
• 🔁 Duplicate invoice detection
• 📈 Historical vendor amount-anomaly detection
• 🚫 Unapproved-vendor detection
• ⚠️ PO/vendor mismatch detection
• 📊 Explainable risk scoring
• 🚨 High-risk monitoring and alerts
• 🧑‍⚖️ Mandatory human approval/rejection gate
• 📜 Per-invoice audit logging
• 📊 Finance review dashboard
• 👤 Multiple demo reviewer personas
• 🗄️ SQLite support for local development
• 🐘 PostgreSQL support for hosted deployment
• 🔐 Environment-controlled CORS
• ☁️ Production startup configuration
• 🧪 Backend and frontend automated testing
• 🏗️ Production frontend build verification

🤖 7. The Multi-Agent Pipeline

Each component has a specific responsibility.

📄 Extract Agent ➜ Invoice Understanding

The Extract Agent converts raw invoice text into structured information needed by the rest of the system.

This includes fields such as:

• Invoice number
• Vendor
• Amount
• Due date
• PO number when provided
• Relevant invoice information

When an Anthropic API key is configured, the project can use Claude for extraction.

When that dependency is unavailable, InvoiceGuard can fall back to deterministic extraction logic.

During our final end-to-end verification, the tested invoice scenarios successfully processed through:

Extraction Method: deterministic_fallback

This means the core workflow does not depend entirely on an external model being available.

🔎 Retrieve Agent ➜ Business Context

Extraction alone cannot determine whether an invoice should be trusted.

The Retrieve Agent therefore searches InvoiceGuard's internal business data for:

• Vendor record
• Vendor approval status
• Historical average invoice amount
• Previous invoice numbers
• Matching purchase orders
• Explicit PO references
• Vendor/PO relationships

It also performs duplicate discovery because duplicate detection is fundamentally a retrieval problem: the system must determine whether the same invoice number already exists.

✅ Validate Agent ➜ Business Rules

The Validate Agent compares the extracted invoice against the retrieved context.

It can identify conditions such as:

• Vendor not approved
• Missing purchase order
• Invoice amount inconsistent with PO amount
• PO belonging to another vendor

Instead of simply returning true or false, validation stores human-readable issues.

For example, our tested amount-anomaly case produced:

Invoice amount ($15,000.00) differs from
PO amount ($4,500.00) by 233.3%.

And the PO/vendor mismatch scenario produced:

Invoice cites PO PO-1003, but that PO belongs
to a different vendor than the invoice's stated vendor.

⚠️ Assess Agent ➜ Risk Analysis

The Assess Agent converts contextual findings into an explainable risk assessment.

It considers signals including:

• Duplicate invoice numbers
• Historical amount anomalies
• Validation failures
• PO/vendor mismatch
• Vendor history

Rather than producing an unexplained classification, the assessment contains both a risk score and human-readable flags.

🚨 Monitor Agent ➜ High-Risk Visibility

High-risk invoices can trigger monitoring behavior.

The application supports audit-based alerts and optional notification channels configured through environment variables, including Slack and email settings.

The core alert trail remains available even if external notification channels are not configured.

🎛️ Orchestrate Agent ➜ Workflow Coordination

The Orchestrate Agent connects all stages:

Extract → Retrieve → Validate → Assess → Monitor

But one responsibility is intentionally missing: it cannot approve an invoice.

The orchestrator always places the processed invoice into:

pending_review

A separate human decision endpoint is required to move it forward.

📄 8. Invoice Intake and Extraction

InvoiceGuard supports multiple ways of getting invoice information into the pipeline.

The API exposes text submission as well as document upload functionality.

For testing, we created controlled invoice scenarios that allowed individual risk paths to be reproduced reliably.

These included:

clean_match.txt
duplicate.txt
amount_anomaly.txt
unapproved_vendor.txt
po_number_direct_match.txt
po_vendor_mismatch.txt

We also created sample PDF invoices for document-oriented testing, including cases for:

• Clean matching
• Duplicate invoices
• Amount anomalies
• PO-number matching
• PO/vendor mismatch
• Unapproved vendors
• Different invoice layouts
• Scanned/no-text-layer documents

This made it possible to test specific behavior rather than relying only on random uploads.

🔎 9. Vendor and Purchase-Order Retrieval

The demo environment contains synthetic vendor and procurement records.

We intentionally used fabricated data rather than presenting real vendor information as demo data.

The seeded environment contains:

5 vendors
4 purchase orders

Example vendors include:

Acme Office Supplies
Brightline Logistics
Shadow Consulting LLC
Meridian Cloud Services
Sterling Print & Signage

The purchase orders include:

PO-1001
PO-1002
PO-1003
PO-1004

The seed operation is idempotent.

We explicitly ran it twice against an already-seeded database and confirmed that it returned:

Data already seeded, skipping.

both times.

The database remained:

Vendors:         5
Purchase orders: 4

rather than duplicating the reference data.

🛡️ 10. Validation and Risk Detection

One of the most important parts of InvoiceGuard is that we tested individual financial-risk paths independently.

🟢 Scenario 1 — Clean Invoice

The clean invoice was submitted against the synthetic Acme Office Supplies vendor.

Results:

HTTP:        200
Invoice:     INV-9001
Amount:      $1,250
Risk:        low
Risk Score:  0
Validation:  True
Duplicates:  []
PO Match:    amount_proximity
Flags:       []

This established our clean baseline.

The invoice passed validation and produced no risk flags.

🔴 Scenario 2 — Duplicate Invoice

We then submitted the same invoice number again.

Results:

Invoice:        INV-9001
Risk:           high
Risk Score:     50
Validation:     True
Duplicate IDs:  [1]

The generated risk flag explained the reason:

Possible duplicate: invoice number already exists
(invoice id(s) [1]).

This is an important distinction.

The invoice can be structurally valid while still being financially suspicious because it has already appeared in the system.

🔴 Scenario 3 — Amount Anomaly

We submitted:

Vendor: Brightline Logistics
Invoice Amount: $15,000
Historical Average: $4,500

Results:

Risk:       high
Risk Score: 50
Validation: False

The validation issue reported:

Invoice amount ($15,000.00) differs from
PO amount ($4,500.00) by 233.3%.

The risk assessment also reported:

Amount is 3.3x this vendor's historical average ($4,500.00).

This scenario therefore demonstrated two different forms of context: purchase-order comparison and historical vendor behavior.

🔴 Scenario 4 — Unapproved Vendor

We submitted an invoice from:

Shadow Consulting LLC

which is intentionally configured as an unapproved vendor.

Results:

Amount:      $8,000
Risk:        high
Risk Score:  60
Validation:  False
PO Match:    None

Validation identified:

Vendor is not on the approved vendor list.

It also surfaced the supplier-policy context requiring procurement review and reported that no matching purchase order existed.

This demonstrated that InvoiceGuard can combine several validation failures into one review case instead of hiding them behind a single generic error.

🟢 Scenario 5 — Explicit PO Number Matching

We tested an invoice containing:

Vendor: Meridian Cloud Services
PO Number: PO-1003
Amount: $2,000

Results:

Risk:       low
Risk Score: 0
Validation: True
PO Match:   po_number
Flags:      []

This confirmed that explicit PO references are recognized directly rather than relying only on amount-based matching.

🔴 Scenario 6 — PO/Vendor Mismatch

This was one of the more important edge cases discovered during testing.

The invoice claimed:

Vendor: Sterling Print & Signage
PO Number: PO-1003

but PO-1003 belongs to a different vendor.

Results:

Risk:                high
Risk Score:          50
Validation:          False
PO Match:            po_number
PO Vendor Mismatch:  True

Validation returned:

Invoice cites PO PO-1003, but that PO belongs
to a different vendor than the invoice's stated vendor.

The risk layer separately surfaced:

PO vendor mismatch: invoice cites PO-1003,
but that purchase order belongs to a different vendor.

During development, this case helped expose a weakness in the original risk calculation. We corrected the assessment logic so that a cross-vendor PO mismatch is explicitly treated as a high-risk event and then added a regression test to prevent the behavior from returning.

🧑‍⚖️ 11. Human-in-the-Loop Approval Gate

The most important governance rule in InvoiceGuard is:

AI analyzes. Humans authorize.

The agent pipeline cannot approve invoices.

Every newly processed invoice receives:

status = pending_review

The human reviewer then explicitly chooses:

Approve

or:

Reject

We tested the approval lifecycle end-to-end.

For the clean invoice:

Invoice:    INV-9001
Status:     approved
Risk:       low
Decided by: Demo Reviewer

The corresponding audit event was:

Agent:  orchestrate_agent
Action: human_approved

We then intentionally attempted to approve the same invoice again.

The API correctly returned:

HTTP/1.1 400 Bad Request

with:

{"detail":"Invoice is already approved"}

This demonstrates that the decision lifecycle is state-controlled rather than allowing repeated approval operations.

Approved invoices also feed back into vendor history so future anomaly detection can incorporate newly accepted invoice amounts.

📜 12. Audit Trail and Explainability

InvoiceGuard stores an audit history associated with each invoice.

Agent actions can therefore be reconstructed after processing.

The audit model records:

• Invoice
• Agent name
• Action
• Detail
• Timestamp

For the tested human approval, the stored event contained:

Agent: orchestrate_agent
Action: human_approved
Detail:
{
  "decided_by": "Demo Reviewer",
  "note": "Approved during final end-to-end verification."
}

This is important because financial automation should not merely produce a final state.

A reviewer or auditor should be able to ask:

What happened to this invoice, and why?

📊 13. Finance Dashboard and Alerts

The backend exposes dedicated dashboard endpoints:

GET /dashboard/stats
GET /dashboard/alerts

During end-to-end verification, one dashboard snapshot reported:

Total invoices:       6
Pending review:       5
Approved:             1
Rejected:             0
High-risk open:       4
Total amount pending: $27,050

The dashboard also aggregates flagged reasons so reviewers can see which types of problems are appearing in the queue.

The React frontend presents this information through a finance-oriented review interface rather than exposing raw database objects.

🔐 14. Security, Configuration, and Data Integrity

We made several deployment and configuration improvements during final verification.

🌐 Environment-Controlled CORS

The original prototype allowed every origin:

allow_origins=["*"]

Before deployment, we replaced that with environment-controlled configuration:

CORS_ORIGINS

Local defaults support the development frontend while production can specify the actual deployed frontend origin.

🔑 Environment Variables

Sensitive or deployment-specific values are configured through environment variables rather than being hardcoded into the application.

These include:

ANTHROPIC_API_KEY
DATABASE_URL
CORS_ORIGINS
SLACK_WEBHOOK_URL
SMTP_HOST
SMTP_PORT
SMTP_USER
SMTP_PASSWORD
ALERT_EMAIL_FROM
ALERT_EMAIL_TO
ANOMALY_MULTIPLIER

We also checked the repository for tracked secret-like files.

The actual .env is ignored.

Only example environment files are tracked for configuration documentation.

🗄️ SQLite + PostgreSQL

Local development uses:

sqlite:///./invoiceguard.db

For hosted environments, we added PostgreSQL support through SQLAlchemy and Psycopg 3.

We tested URL normalization for:

postgres://...
postgresql://...
postgresql+psycopg://...

Hosted PostgreSQL URLs are normalized to the SQLAlchemy/Psycopg 3 format:

postgresql+psycopg://...

🔌 Database Connection Reliability

The production SQLAlchemy engine uses:

pool_pre_ping=True

to help detect stale database connections before use.

🧪 Synthetic Demo Data

The seeded vendors and purchase orders are fabricated for demonstration.

That lets the application demonstrate financial workflows without presenting real company/vendor records as demo data.

🧪 15. Testing and Validation

We deliberately did not stop after getting the interface to work.

The final project went through backend regression tests, frontend tests, linting, production compilation, manual API testing, database-reset testing, risk-scenario testing, and deployment preparation.

🐍 Backend Regression Suite

The final backend suite contained five regression tests:

test_dashboard_stats_empty
test_invoice_submit_and_decision_lifecycle
test_po_vendor_mismatch_is_high_risk
test_root_endpoint
test_vendor_and_po_flow

Final result:

Ran 5 tests

OK

What those tests protect

They cover important behaviors including:

• Empty dashboard state
• Invoice submission
• Human decision lifecycle
• Vendor creation
• Purchase-order flow
• PO/vendor mismatch classification
• API root availability

The PO/vendor mismatch test was added specifically after we improved that risk path.

⚛️ Frontend Unit Tests

The frontend test suite contains authentication/persona and formatter tests.

Final result:

tests 9
suites 2
pass 9
fail 0

The tested behaviors included:

• Multiple distinct demo personas
• Correct primary demo reviewer
• Required persona fields
• Unique demo-user emails
• Currency formatting
• Null/invalid currency handling
• Date formatting
• Risk-level UI mapping
• Invoice-status UI mapping

🧹 Frontend Lint

We ran the frontend through Oxlint.

Result:

Found 0 warnings and 0 errors.

🏗️ Production Frontend Build

We then compiled the frontend using:

tsc -b && vite build

Result:

✓ 1976 modules transformed
✓ built successfully

Vite produced a warning that one JavaScript bundle exceeded 500 kB after minification.

This is a performance optimization warning, not a build failure.

It gives us a clear future optimization target: code splitting and lazy loading.

🕒 Python UTC Compatibility Check

During testing, Python 3.13 warned that:

datetime.datetime.utcnow()

is deprecated.

We replaced those calls with UTC-aware current-time generation while preserving the database's existing naive UTC representation.

We then searched the backend and tests again.

Result:

✓ No deprecated utcnow() calls found

The complete backend regression suite passed after the change.

♻️ Demo Reset Verification

Repeated demonstrations originally left previous invoices in SQLite, which affected duplicate detection.

We therefore added:

python -m app.reset_demo

The reset utility removes:

• Transactional invoices
• Associated audit logs

while preserving:

• Seeded vendors
• Seeded purchase orders

One verification produced:

Before reset:
Invoices:        12
Audit logs:      82
Vendors:         5
Purchase Orders: 4

After reset:
Invoices:        0
Audit logs:      0
Vendors:         5
Purchase Orders: 4

This became particularly useful for reproducible demonstrations.

🧪 Clean-State End-to-End Risk Verification

After resetting the database, we submitted the scenarios in the correct sequence.

The results were:

Scenario	Validation	Risk	Score	Main Result
Clean match	Passed	Low	0	Correct clean baseline
Duplicate	Passed	High	50	Existing invoice detected
Amount anomaly	Failed	High	50	233.3% PO difference + 3.3× history
Unapproved vendor	Failed	High	60	Vendor approval/policy/PO issues
Direct PO match	Passed	Low	0	Explicit PO matched correctly
PO/vendor mismatch	Failed	High	50	Cross-vendor PO conflict detected

This test also revealed why clean database state matters.

When the six scenarios were accidentally rerun without resetting first, invoices that should have been clean were correctly detected as duplicates because their invoice numbers already existed.

That was not a duplicate-detection bug.

The system was correctly reacting to previously inserted test data.

After resetting and rerunning from a clean state, the expected results were restored.

🚦 Final Verification Result

Our combined final verification produced:

Backend tests:  PASS
Frontend tests: PASS
Lint:           PASS
Build:          PASS
UTC check:      PASS

✓ ALL FINAL CHECKS PASSED

At that point Git also reported:

Your branch is up to date with 'origin/main'.

nothing to commit, working tree clean

☁️ 16. Deployment Preparation

We did not treat local execution as sufficient.

Before deployment, we prepared the backend for a hosted environment.

🐘 PostgreSQL Support

We added:

psycopg[binary]

and database URL normalization for hosted PostgreSQL.

🌐 Production CORS

CORS is configurable through:

CORS_ORIGINS

instead of allowing every origin.

🐍 Python Version

The production Python version is pinned through:

.python-version

to:

3.13.7

🚀 Production Startup

We created a production startup script that:

1. Seeds reference/demo data
2. Starts the FastAPI application
3. Binds to 0.0.0.0
4. Uses the platform-provided PORT

Conceptually:

python -m app.seed_data
uvicorn app.main:app --host 0.0.0.0 --port "$PORT"

The startup flow was tested locally on a separate port before being committed.

The API responded successfully:

{
  "service": "InvoiceGuard API",
  "status": "ok"
}

The dashboard endpoint also returned live application statistics.

🌍 Live Backend

The FastAPI backend was subsequently deployed successfully to Render.

InvoiceGuard Live API

This moved the project beyond a local-only prototype and gave the frontend a real hosted API target.

🧗 17. Main Challenges We Faced

🔁 Duplicate Detection During Repeated Testing

One of the most confusing issues occurred when a supposedly clean invoice suddenly became high risk.

The reason turned out to be previous test invoices still existing in the database.

The duplicate system was actually behaving correctly.

That led us to build the dedicated demo-reset utility and adopt a clean-state testing procedure.

⚠️ Correctly Handling PO/Vendor Mismatch

Matching a PO number is not sufficient.

An invoice can provide a real PO number that belongs to another supplier.

We therefore needed to distinguish:

PO exists

from:

PO exists AND belongs to this vendor

After identifying this edge case, we strengthened the Assess Agent and added a regression test specifically for it.

🧑‍⚖️ Keeping Approval Human-Controlled

It would have been easy for a low-risk invoice to move directly to approved.

We deliberately avoided that architecture.

The system can recommend and explain, but the state transition requires a separate human action.

🗄️ Moving Beyond Local SQLite

SQLite is ideal for local development but not the architecture we wanted to depend on for hosted persistence.

Adding PostgreSQL support required database-driver installation, URL normalization, and ensuring existing SQLAlchemy models remained database-agnostic.

🌐 Production Configuration

Localhost defaults are useful during development but insufficient for deployment.

We had to separate local and production configuration for:

• API base URL
• Database
• CORS
• Port
• External API keys
• Notification channels

🕒 Python 3.13 Deprecations

Our tests exposed deprecated datetime.utcnow() usage.

Instead of ignoring the warning, we removed the deprecated calls and reran the complete regression suite.

🎓 18. What We Learned

One of the biggest lessons from InvoiceGuard was that agentic systems become much more useful when each agent has a narrow, inspectable responsibility.

Extraction, retrieval, validation, and risk assessment are related tasks, but they are not the same task.

Separating them made debugging much easier.

We also learned that a successful AI response is only one part of a real application.

A useful financial workflow needs:

• State management
• Business rules
• Historical context
• Database integrity
• Explainability
• Audit logs
• Human authorization
• Error handling
• Reproducible tests
• Deployment configuration

Another important lesson came from duplicate testing: test state matters.

An AI workflow can appear incorrect when the underlying database contains leftover records from previous runs. Building reset_demo made our tests reproducible and made the demonstration much easier to trust.

Finally, human-in-the-loop design works best when it is enforced structurally.

Instead of prompting an AI with:

"Please wait for human approval."

we designed the application so the agent simply does not own the transition to approved.

That is a much stronger control.

🚧 19. Current Limitations and Future Improvements

InvoiceGuard is a working prototype, not yet a production financial platform.

There are several clear next steps.

🔐 Real Authentication and Authorization

The current demo personas are useful for demonstrating reviewer workflows, but a production deployment would need genuine authentication, authorization, session management, and role enforcement.

🗄️ Production Database Hardening

PostgreSQL support is now available, but a mature deployment should add formal database migrations, backup/recovery procedures, stronger operational monitoring, and lifecycle management.

📄 Broader Invoice Understanding

More diverse invoice layouts, OCR cases, languages, currencies, and poorly scanned documents should be evaluated.

🧠 Larger Extraction Evaluation

The deterministic and optional model-based extraction paths should be benchmarked against a larger labeled invoice dataset.

📊 Risk Calibration

The current risk rules are transparent and useful for demonstration, but production risk thresholds should be calibrated against genuine organizational transaction histories.

🔔 Production Notifications

Slack and SMTP configuration exist, but real organizational integrations would require credential management, delivery monitoring, retry logic, and escalation policies.

⚛️ Frontend Bundle Optimization

The production build succeeds, but the current JavaScript bundle triggers Vite's >500 kB warning.

Future work could introduce:

• Dynamic imports
• Route-level lazy loading
• Better code splitting

🔐 Secrets Management

Production credentials should ultimately move beyond local .env configuration into a dedicated secret-management system.

🧾 Accounting-System Integration

A future version could integrate with real ERP/accounting environments after appropriate security and authorization controls are in place.

⚠️ These are future improvements, not features we are claiming are already implemented.

🎯 20. Overall Project Summary

InvoiceGuard started with a simple question:

How can AI reduce the manual work involved in invoice review without giving AI uncontrolled authority over financial decisions?

The result is a multi-stage invoice intelligence pipeline combining document extraction, vendor retrieval, purchase-order matching, validation, explainable risk assessment, monitoring, and mandatory human review.

The complete workflow is:

Invoice Submitted
        ↓
Extract Structured Data
        ↓
Retrieve Vendor + PO + History
        ↓
Validate Business Rules
        ↓
Assess Financial Risk
        ↓
Generate Explainable Flags
        ↓
Monitor High-Risk Cases
        ↓
pending_review
        ↓
Human Reviewer
     ↙       ↘
 Approve    Reject
     ↓       ↓
Decision + Audit Trail
        ↓
Dashboard / Historical Context

The most important design principle is straightforward:

InvoiceGuard automates investigation, not authority.

The agents can extract, retrieve, compare, validate, detect, score, flag, and alert.

They cannot make the final approval decision.

That belongs to a human.

Our final verification covered clean invoices, duplicate detection, amount anomalies, unapproved vendors, direct PO matching, cross-vendor PO misuse, approval lifecycle protection, backend regression testing, frontend unit testing, linting, production compilation, database resets, environment configuration, PostgreSQL readiness, and deployment preparation.

Backend regression tests: 5/5 PASS
Frontend unit tests:       9/9 PASS
Frontend lint:             0 errors / 0 warnings
Production build:          PASS
Deprecated UTC check:      PASS
Clean invoice:             PASS
Duplicate detection:       PASS
Amount anomaly:            PASS
Unapproved vendor:         PASS
Direct PO match:           PASS
PO/vendor mismatch:        PASS
Human approval:            PASS
Repeat approval blocked:   PASS
Production API deployment: PASS

✅ Every major claim above corresponds to functionality we implemented or a test/manual verification we actually performed.

Built With

• anthropic-claude
• axios
• fastapi
• framer-motion
• lucide-react
• oxlint
• postgresql
• psycopg
• python
• react
• sqlalchemy
• sqlite
• tailwind-css
• typescript
• vite