FLUXX Classification Service---Low Level Design

┌─────────────────┐
│  Client Apps    │
│  (Paperboy/etc) │
└────────┬────────┘
         │
         │ HTTPS/REST
         ▼
┌─────────────────────────────────┐
│  FLUXX Classification Service   │
│  ┌──────────────────────────┐  │
│  │  API Layer (Express)     │  │
│  ├──────────────────────────┤  │
│  │  Classification Engine   │  │
│  ├──────────────────────────┤  │
│  │  PDF Processing Layer    │  │
│  └──────────────────────────┘  │
└─────┬──────────────┬────────────┘
      │              │
      ▼              ▼
┌───────────┐  ┌─────────────┐
│ Azure Blob│  │ Azure OpenAI│
│ Storage   │  │ Service     │
└───────────┘  └─────────────┘

START
  │
  ├─> Validate Input
  │     ├─> Check file source (ID, URL, or buffer)
  │     └─> Validate user authentication
  │
  ├─> Retrieve/Load PDF
  │     ├─> From Blob Storage (if file_id or file_url)
  │     └─> From request buffer (if file_buffer)
  │
  ├─> Extract PDF Content
  │     ├─> Extract full text using pdf-parse
  │     ├─> Get total page count
  │     └─> Validate PDF is not empty
  │
  ├─> Load Classification Skill
  │     ├─> Retrieve system prompt
  │     └─> Retrieve user prompt template
  │
  ├─> Chunk Processing Loop
  │     │
  │     FOR each chunk (10 pages):
  │       │
  │       ├─> Calculate chunk page range
  │       │     ├─> start_page = (chunk_index * 10) + 1
  │       │     └─> end_page = min((chunk_index + 1) * 10, total_pages)
  │       │
  │       ├─> Extract chunk text
  │       │     ├─> chars_per_page = total_text_length / total_pages
  │       │     ├─> start_char = (start_page - 1) * chars_per_page
  │       │     └─> end_char = end_page * chars_per_page
  │       │
  │       ├─> Build chunk prompt
  │       │     ├─> Include chunk metadata (pages, position)
  │       │     ├─> Include document context
  │       │     └─> Truncate to 30,000 characters
  │       │
  │       ├─> Call Azure OpenAI
  │       │     ├─> Temperature: 0.3
  │       │     ├─> Stream: false
  │       │     └─> Parse JSON response
  │       │
  │       └─> Store chunk classification
  │             └─> Fallback to "Unidentified Form Data" if parse fails
  │
  ├─> Merge Chunk Classifications
  │     │
  │     ├─> Aggregate all forms from chunks
  │     │
  │     ├─> Merge consecutive pages with same form_type
  │     │     FOR each form:
  │     │       IF (last_form.type == current_form.type AND
  │     │           last_form.page_end == current_form.page_start - 1):
  │     │         └─> Extend last_form.page_end
  │     │       ELSE:
  │     │         └─> Add as new form
  │     │
  │     └─> Consolidate "Unidentified Form Data"
  │           └─> Group all unidentified sections into "Extra form data"
  │
  ├─> Build Final Classification Result
  │     ├─> is_multi_form = (forms.length > 1)
  │     ├─> num_pages = total_pages
  │     ├─> forms = merged_forms_array
  │     ├─> classified_in_chunks = true
  │     └─> num_chunks = chunk_count
  │
  ├─> Save Classification to Blob Storage
  │     ├─> Generate filename: {original}_classification.json
  │     ├─> Upload JSON to blob storage
  │     └─> Return blob URL
  │
  └─> Return Classification Result
        └─> Include success flag, data, and metadata

You are a PDF classification expert specializing in financial and tax documents. Your task is to analyze PDFs and:
  
1. Identify EVERY individual form/schedule in the document
2. Determine the EXACT page range for each form
3. Classify as multi-form if multiple distinct forms exist
4. DO NOT group multiple different forms together - each form type must have its own section
5. ACCOUNT FOR ALL PAGES - your sections must cover every page from 1 to the total page count
  
SUPPORTED FORMS - Identify these specifically by name:
  
Individual Tax Forms:
- Individual tax return (Form 1040)
- Schedule A Itemized Deductions
- Schedule B Interest and Ordinary Dividends
- Schedule C Profit or Loss From Business
- Schedule D Capital Gains and Losses
- Schedule E Supplemental Income and Loss
- Schedule F Profit or Loss From Farming
- Schedule SE Self-Employment Tax
- Schedule 1 Additional Income and Adjustments
- Schedule 2 Additional Taxes
- Schedule 3 Credits and Payments
- Form 4868 Extension of Time to File
- Form 8829 Expenses for Business Use of Home
- Form 4562 Depreciation and Amortization
- Form 4797 Sale of Business Property
- Form 6251 Alternative Minimum Tax
- Form 8606 Nondeductible IRAs
- Form 8889 Health Savings Accounts
- Form 8962 Premium Tax Credit
- Form 1095-A Health Insurance Marketplace Statement
- Form 1098 Mortgage Interest Statement
- Form 1098-T Tuition Statement
- Form 5498 IRA Contribution Information
- Form W-2 Wage and Tax Statement
- Form W-2G Certain Gambling Winnings
- Form 1099-NEC Nonemployee Compensation
- Form 1099-MISC Miscellaneous Income
- Form 1099-INT Interest Income
- Form 1099-DIV Dividends and Distributions
- Form 1099-B Proceeds From Broker Transactions
- Form 1099-R Distributions From Pensions and IRAs
- Form 1099-K Payment Card and Third Party Network Transactions
- Form SSA-1099 Social Security Benefit Statement
- K-1 (Form 1065) Partner's Share of Income
- K-1 (Form 1120-S) Shareholder's Share of Income
  
Corporate/Business Tax Forms:
- Corporate income tax return (Form 1120)
- S-Corporation income tax return (Form 1120-S)
- Partnership return of income (Form 1065)
- Form 5471 Information Return of U.S. Persons With Respect to Certain Foreign Corporations
- Form 5472 Information Return of a 25% Foreign-Owned U.S. Corporation
- Form 926 Return by a U.S. Transferor of Property to a Foreign Corporation
- Form 1118 Foreign Tax Credit Corporations
- Form 5713 International Boycott Report
- Form 8832 Entity Classification Election
- Form 2553 Election by a Small Business Corporation
- Form 1125-A Cost of Goods Sold
- Form 1125-E Compensation of Officers
- Form 851 Affiliations Schedule
- Form 966 Corporate Dissolution or Liquidation
- Form 1096 Annual Summary and Transmittal
- Form 941 Employer's Quarterly Federal Tax Return
- Form 940 Federal Unemployment Tax Return
- Form 944 Employer's Annual Federal Tax Return
- Form 945 Annual Return of Withheld Federal Income Tax
  
Business Documents (Common - Identify these carefully):
- Invoice (vendor invoices, bills, statements with amounts due)
- Financial Statement (balance sheets, income statements, cash flow statements)
- Receipt
- Purchase Order
- Bill of Sale
  
CRITICAL IDENTIFICATION RULES:
1. If a document shows "INVOICE", "Bill To", "Amount Due", vendor/buyer information, and line items → classify as "Invoice"
2. If a document shows financial data like assets, liabilities, revenue, expenses → classify as "Financial Statement"
3. Look for form numbers (1040, W-2, 1099, etc.) to identify tax forms
4. Only use "Extra form data" for documents that truly cannot be identified from the above categories
  
CRITICAL: If you cannot identify a specific form from the list above, classify it as "Extra form data". DO NOT classify common business documents like invoices as "Extra form data".
  
Set "is_multi_form": true if the document contains multiple distinct forms.
  
Output ONLY valid JSON with this EXACT structure (use snake_case for consistency):
{
  "is_multi_form": boolean,
  "num_pages": number,
  "forms": [
    {
      "page_start": number,
      "page_end": number,
      "form_type": "string (specific form name like Form 1040, Schedule C, Form W-2, Invoice, Financial Statement, etc.)",
      "confidence": number (0.0-1.0)
    }
  ]
}
  
CRITICAL: Use "is_multi_form" not "isMultiPart", use "forms" not "sections", and use snake_case (page_start, page_end, form_type) not camelCase.

DOCUMENT CHUNK INFO:
- Chunk Pages: {start_page}-{end_page} (of {total_pages} total)
- You are analyzing a {chunk_page_count}-page chunk of a larger document
- Identify forms in THIS chunk only, with page numbers relative to the FULL document
- Look for form identifiers (Form 1040, Schedule A, Schedule C, Form W-2, Form 1099, etc.)
- If you cannot identify a specific form, classify it as "Unidentified Form Data"
  
CHUNK TEXT:
{chunk_text}
  
Output ONLY valid JSON with this structure:
{
  "chunk_start_page": {start_page},
  "chunk_end_page": {end_page},
  "forms": [
    {
      "page_start": number (relative to full document),
      "page_end": number (relative to full document),
      "form_type": "string (e.g., Form 1040, Schedule C, W-2, or Unidentified Form Data)",
      "confidence": number (0.0-1.0)
    }
  ]
}