Instruction file imported from SAICHARAN03718/JK_frontend_v2 (.github/instructions/OCR-Strategy.instructions.md). Copyright stays with the author.

OCR & Information Extraction Strategy - Simplified Implementation

1. Overview & Context

This document outlines the simplified technical strategy for implementing automated data extraction from logistics documents (Invoices, LRs, PODs) using basic OCR and text search patterns. The system is designed to provide immediate functionality without complex job queues or coordinate-based extraction.

Core Constraint: Build using open-source tools without relying on major cloud APIs (Google Cloud Vision, Azure, AWS Textract).

Primary Goal: Create a working end-to-end extraction flow that feeds into the automated billing workflow with minimal complexity.

2. Simplified Architecture: Direct Processing

The solution uses a single-step, synchronous approach:

OCR + Immediate Extraction

• Purpose: Convert document images into machine-readable text and immediately extract key-value pairs
• Technology: PaddleOCR (Python-based, open-source) for text recognition
• Method: Basic text search patterns using regular expressions and keyword matching
• Output: Extracted field values stored directly in the database

3. Implementation Strategy

Phase 1: Basic Text Extraction (Current Implementation)

Approach: Skip coordinate-based and anchor-based extraction, focus on pattern matching

# Core Extraction Logic (Simplified)
def extract_fields_basic(text, field_templates):
    extracted = {}
    for field in field_templates:
        field_key = field['field_key']
        field_name = field['field_name']
        
        # Try multiple patterns for each field
        patterns = [
            rf"{re.escape(field_name)}\s*[:#\-]?\s*([A-Za-z0-9\-/]+)",
            rf"Invoice\s*No[.:]?\s*([A-Za-z0-9\-/]+)" if 'invoice' in field_key else None,
            rf"([A-Z]{{2}}\d{{2}}[A-Z]{{2}}\d{{4}})" if 'vehicle' in field_key else None,
        ]
        
        for pattern in patterns:
            if pattern and re.search(pattern, text, re.IGNORECASE):
                match = re.search(pattern, text, re.IGNORECASE)
                extracted[field_key] = {
                    'value': match.group(1)[:100],
                    'method': 'regex_pattern',
                    'confidence': 0.8
                }
                break
    
    return extracted

# Core OCR Service Structure
{
  "document_id": "doc_123",
  "page_number": 1,
  "text_blocks": [
    {
      "text": "Invoice Number",
      "bbox": [x1, y1, x2, y2],
      "confidence": 0.95,
      "block_type": "text|table|line",
      "font_size": 12,
      "is_bold": false
    }
  ],
  "tables": [
    {
      "bbox": [x1, y1, x2, y2],
      "cells": [...]
    }
  ]
}

Key Features:

• Document preprocessing (deskew, contrast enhancement, DPI normalization)
• Separate table detection for tabular data
• Multi-page document handling
• Confidence scoring for quality control

Phase 3: Template Annotation Tool (2-3 weeks)

Purpose: Visual tool for administrators to create extraction templates

Workflow:

1. Admin uploads sample document
2. System runs OCR and displays detected text boxes
3. Admin clicks on text boxes and labels them (e.g., "invoice_number", "vehicle_number")
4. System generates JSON template with coordinates and metadata
5. Template stored in database for that client/branch

Template Structure:

{
  "template_id": "client_123_invoice_v1",
  "client_id": 123,
  "branch_id": 456,
  "document_type": "invoice",
  "fields": [
    {
      "field_key": "invoice_number",
      "field_name": "Invoice Number",
      "extraction_methods": [
        {
          "type": "coordinate",
          "bbox": [100, 200, 300, 250],
          "priority": 1
        },
        {
          "type": "anchor",
          "anchor_text": "Invoice No:",
          "search_direction": "right",
          "max_distance": 200,
          "priority": 2
        },
        {
          "type": "regex",
          "pattern": "INV-\\d{6}",
          "priority": 3
        }
      ],
      "validation": {
        "required": true,
        "data_type": "string",
        "max_length": 50
      }
    }
  ]
}

Phase 4: Extraction Engine

Three Extraction Methods (in priority order):

1. Coordinate-Based Extraction (Primary)

   • Use pre-defined coordinates from template
   • Most reliable for consistent document layouts
   • Works when documents maintain same format

2. Anchor-Based Extraction (Fallback)

   • Find anchor text (e.g., "Vehicle No:")
   • Search for value in relative position
   • Handles slight layout variations

3. Regular Expression Matching (Validation)

   • Pattern matching for consistent formats (GSTINs, dates, vehicle numbers)
   • Additional validation layer
   • Backup when coordinate/anchor methods fail

Quality Control Features:

def calculate_field_confidence(extraction_result):
    scores = []
    scores.append(extraction_result.ocr_confidence)
  
    if matches_expected_format(extraction_result.value):
        scores.append(0.9)
    else:
        scores.append(0.3)
  
    if similar_to_previous_extractions(extraction_result.value):
        scores.append(0.8)
  
    return weighted_average(scores)

Phase 2: Simplified Workflow Integration

Integration Points:

• Connect to existing lorry_receipts and invoices tables
• Populate raw_ocr_data JSONB field with extraction results
• Trigger human validation workflow for all extractions
• Use existing 3-status workflow: Pending_Validation → Validated → Billed

Simple Processing Pipeline:

1. Direct Processing: No job queue, process PDF immediately when user clicks "Extract"
2. Basic Field Matching: Use regex patterns and keyword matching from client_field_templates
3. Immediate Results: Store results in invoices table and show validation modal
4. Manual Review: All extractions require user validation (no automatic approval)

4. Simplified Database Requirements

Use Existing Schema Only

-- NO new tables needed, use existing:
-- ✅ clients
-- ✅ client_branches  
-- ✅ client_field_templates
-- ✅ lorry_receipts
-- ✅ invoices
-- ✅ bulk_bills
-- ✅ generated_bill_files

-- NO extraction_jobs table
-- NO document_templates table
-- NO complex status workflows

Simplified Status Flow

-- Keep original constraint:
ALTER TABLE lorry_receipts 
ADD CONSTRAINT chk_lorry_receipts_status 
CHECK (status IN ('Pending_Validation','Validated','Billed'));

-- No intermediate statuses like 'Processing', 'Queued', 'Extracting'

Indexes for Performance

CREATE INDEX idx_document_templates_client_branch ON public.document_templates(client_id, branch_id, document_type);
CREATE INDEX idx_extraction_results_invoice ON public.extraction_results(invoice_id);
CREATE INDEX idx_extraction_results_needs_review ON public.extraction_results(needs_review);
CREATE INDEX idx_extraction_results_confidence ON public.extraction_results USING GIN (confidence_scores);

5. Simplified Implementation Benefits

Immediate Benefits

✅ No database migrations needed - Use existing schema ✅ Faster development - Skip complex job queue implementation
✅ Simpler testing - Direct function calls, no async complexity ✅ Easier debugging - Synchronous flow, clear error handling ✅ Quick iteration - Changes take effect immediately

Trade-offs Accepted

❌ No progress tracking - User waits for completion ❌ UI blocking - Interface shows loading during extraction ❌ No background processing - All work happens in request cycle ❌ No retry logic - Failed extractions require manual restart

Success Metrics for Basic Implementation

• Extraction Accuracy: 80%+ for common fields (invoice_number, amount, date)
• Processing Time: < 30 seconds for typical 5-page PDF
• User Experience: Clear loading states, intuitive validation interface
• Error Handling: Graceful failures with actionable error messages

6. Integration with Existing System

This simplified OCR strategy seamlessly integrates with the existing system architecture:

1. Workflow Integration: Fits into Step 2 (Synchronous Document Processing) of the existing workflow
2. Database Integration: Uses existing raw_ocr_data JSONB field in invoices table
3. Status Management: Leverages existing 3-status workflow (no changes needed)
4. UI Integration: Validation interface builds on existing dashboard structure

The basic approach ensures minimal disruption to existing operations while providing immediate value through automated field extraction.

This simplified approach prioritizes getting a working system quickly over complex features. Advanced functionality like job queues, progress tracking, and sophisticated error handling can be added later as needed.