How hamida-c/invoice-fraud-detection works
Project type & purpose (from README + tree)
This is a single-repo, Python-based ML/AI application delivered as a Streamlit web app for real-time invoice fraud/anomaly detection. It is an end-to-end pipeline:
Invoice image upload → OCR (EasyOCR) → field extraction (regex) → feature engineering → rule-based checks + autoencoder anomaly score → fraud risk + explanation in UI
There is no “backend service” folder; the “system” is mostly a local inference pipeline packaged into streamlit.py, with trained artifacts stored in /model and /feature cols and encoder.
What the file structure implies architecturally
• streamlit.py
Application entrypoint. Contains UI layer and likely orchestrates the full inference pipeline.
• main.ipynb
• dataset/…csv
Training/validation data (offline). Not used at runtime except for development.
• model/invoice_autoencoder.h5
Trained TensorFlow/Keras autoencoder for anomaly detection (reconstruction error).
• feature cols and encoder/feature_cols.pkl
Defines the exact feature schema/order expected by the model. Critical for runtime correctness.
• feature cols and encoder/scaler_invoice.pkl
A scaler/normalizer (sklearn) used before feeding features into the autoencoder.
• feature cols and encoder/threshold.txt
The decision threshold for reconstruction error → “fraud/anomaly” classification.
This structure strongly suggests two major “subsystems”:
Offline model development/training (notebook + dataset → artifacts)
2) Online inference & UI (Streamlit + OCR + feature pipeline + artifacts → decision + explanation)
Offline Training & Artifact Generation (lifecycle)
This avoids mixing concerns and makes data/artifact provenance explicit.
User / Client
• End User (Browser)
Interacts with Streamlit UI.
Document Ingestion & Preprocessing
• File Handler
• Accepts uploaded file bytes
• Image Preprocessing (PIL)
• Convert to image, resize/denoise if applicable
OCR Layer
• EasyOCR Engine
• Input: preprocessed invoice image
Parsing / Field Extraction
• Regex Field Extractor
• Extracts: amounts, dates, vendor name, invoice id, etc.
• Output: structured fields (JSON-like dict)
Feature Engineering
• Feature Builder (15+ features)
• Financial features (e.g., totals, tax patterns, currency format)
• Textual features (e.g., vendor string patterns)
• Completeness/consistency checks (missing fields, date anomalies)
Feature Schema Alignment
• Feature Column Selector (feature_cols.pkl)
• Enforces exact order and presence of features
• Handles missing columns (fill defaults) if implemented
Scaling / Normalization
• Scaler (scaler_invoice.pkl)
• Transforms features to the scale used in training
ML Inference: Autoencoder
• Keras Model (invoice_autoencoder.h5)
• Produces reconstruction (or reconstruction error)
• Reconstruction Error Calculator
• Metric: MSE/MAE across features (whatever notebook defines)
Decision Logic (Hybrid)
• Threshold Comparator (threshold.txt)
• reconstruction_error > threshold => anomaly
• Rule-Based Fraud Checks
• Deterministic rules (e.g., suspicious date gaps, negative totals, etc.)
• Risk Aggregator
• Combines rule flags + anomaly score into final fraud risk label
Explainability / Output Formatter
• Explanation Generator
• “Triggered rules: …”
• “Reconstruction error exceeded threshold by …”
• Response Payload
• Fraud label, score(s), extracted fields, flagged reasons
Local Storage (Artifacts)
• /model/invoice_autoencoder.h5
• /feature cols and encoder/*.pkl
• threshold.txt
Even if it’s “just a notebook,” capture it explicitly because it explains where artifacts come from.
Data Source
• **CSV Dataset (dataset/*.csv)**
Training Pipeline (Notebook)
• Training & Experimentation (main.ipynb)
• Data cleaning
• Feature engineering definition
• Fit scaler
• Train autoencoder
• Select threshold (e.g., percentile of reconstruction error)
Outputs / Artifacts
• Model Artifact
• invoice_autoencoder.h5
• Preprocessing Artifacts
• scaler_invoice.pkl
• feature_cols.pkl
• Decision Artifact
• threshold.txt
User Upload → Preprocess → OCR → Regex Extraction → Feature Engineering → Scaling → Autoencoder → Error Score → Threshold/Rules → Fraud Decision → UI Output
Streamlit App → loads → Model (.h5)
Streamlit App → loads → Scaler (.pkl)
Streamlit App → loads → Feature Columns (.pkl)
Streamlit App → loads → Threshold (.txt)
External library boundaries (optional but useful)
OCR (EasyOCR) and ML (TensorFlow/Keras) as labeled subcomponents to clarify runtime dependencies.
Architectural patterns to highlight (specific to this repo)
• Pipeline architecture: sequential stages from ingestion to decision.
• Hybrid detection: deterministic rule-based + learned anomaly detection (autoencoder).
• Artifact-driven inference: runtime behavior is governed by versioned artifacts (model + scaler + schema + threshold).
• Single-process web app: Streamlit likely runs everything in-process (no separate API server).
• Streamlit (UI + orchestration)
• EasyOCR (OCR)
• Regex (field parsing)
• Pandas/NumPy (feature engineering)
• Scikit-learn (scaler + joblib)
• TensorFlow/Keras (autoencoder inference)
• PIL (image preprocessing)
What NOT to do (common inaccuracies)
• Don’t omit the artifact files (they are essential system components).
• Don’t collapse the detection logic into “model predicts fraud” (it’s explicitly autoencoder + rules + threshold).