OCR Processing Flow

┌──────────────┐
│   User       │
│   Upload     │
└──────┬───────┘
       │
       ▼
┌─────────────────────────────────────────┐
│  ocr-uploader.tsx (Frontend)            │
│  - File validation (image/PDF)          │
│  - Base64 encoding                      │
│  - Mode selection (raw/structured)      │
│  - Extractor selection (v4/compact)     │
└──────┬──────────────────────────────────┘
       │
       ▼
┌─────────────────────────────────────────┐
│  Route Selection                         │
│  ┌─────────────────────────────────┐   │
│  │ Raw Mode → /api/ocr             │   │
│  │ Structured + v4 → /api/ocr-     │   │
│  │                   structured-v4  │   │
│  │ Structured + compact → /api/ocr-│   │
│  │                   structured     │   │
│  └─────────────────────────────────┘   │
└──────┬──────────────────────────────────┘
       │
       ▼
┌─────────────────────────────────────────┐
│  API Route Handler                       │
│  - Validate input                        │
│  - Build OpenRouter payload              │
│  - Add system prompt + schema            │
│  - Configure plugins (PDF)               │
└──────┬──────────────────────────────────┘
       │
       ▼
┌─────────────────────────────────────────┐
│  OpenRouter API Call                     │
│  https://openrouter.ai/api/v1/          │
│         chat/completions                 │
│                                          │
│  Headers:                                │
│  - Authorization: Bearer <API_KEY>       │
│  - HTTP-Referer: <SITE_URL>             │
│  - X-Title: <APP_NAME>                  │
│                                          │
│  Body:                                   │
│  - model (gemini-2.5-flash, gpt-4o...)  │
│  - messages (system + user + file)       │
│  - response_format: {type: json_object}  │
│  - plugins (for PDF parsing)             │
└──────┬──────────────────────────────────┘
       │
       ▼
┌─────────────────────────────────────────┐
│  Response Processing                     │
│  - Coerce to valid JSON                  │
│  - Strip markdown code fences            │
│  - Handle union types                    │
│  - Replace NaN/Infinity with null        │
└──────┬──────────────────────────────────┘
       │
       ▼
┌─────────────────────────────────────────┐
│  Reconciliation (if structured)          │
│  - reconcileV4() for v4 schema           │
│  - reconcile() for compact schema        │
│  - Try multiple hypotheses               │
│  - Pick best match                       │
└──────┬──────────────────────────────────┘
       │
       ▼
┌─────────────────────────────────────────┐
│  Return to Frontend                      │
│  - Structured JSON with reconciliation   │
│  - Or raw text (for raw mode)            │
└──────┬──────────────────────────────────┘
       │
       ▼
┌─────────────────────────────────────────┐
│  Display Components                      │
│  - invoice-viewer-v4.tsx (v4 schema)    │
│  - invoice-viewer.tsx (compact schema)   │
│  - Confetti on success                   │
│  - Show reconciliation status            │
└─────────────────────────────────────────┘

const handleFile = (f: File | null) => {
  // ...
  const pdf = f.type === "application/pdf" || f.name.toLowerCase().endsWith(".pdf");
  setIsPdf(pdf);
  const reader = new FileReader();
  reader.onload = () => setPreview(reader.result as string);
  reader.readAsDataURL(f); // Convert to base64 data URL
};

{
  imageBase64?: string,  // Data URL or base64
  pdfUrl?: string,       // Public URL
  pdfBase64?: string,    // Base64 PDF
  filename?: string,     // PDF filename
  model?: string         // Model override
}

const response = await fetch("https://openrouter.ai/api/v1/chat/completions", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `Bearer ${apiKey}`,
    "HTTP-Referer": site,
    "X-Title": title,
  },
  body: JSON.stringify({
    model,
    temperature: 0,
    messages: [
      {
        role: "system",
        content: "You are an OCR extractor. Return only the raw, verbatim text...",
      },
      {
        role: "user",
        content: [
          { type: "text", text: "Extract all text..." },
          // Image or PDF file attachment
        ],
      },
    ],
  }),
});

{
  // ... standard fields
  annotations?: unknown,  // Pass-through for cached parsing
  plugins?: unknown       // Override PDF plugins
}

const coerceToJson = (raw: unknown): unknown => {
  // Strip markdown code fences
  if (s.startsWith("```")) {
    s = s.replace(/^```[a-zA-Z]*\n/, "").replace(/```\s*$/, "").trim();
  }
  
  // Extract first JSON object
  const firstBrace = s.indexOf("{");
  const lastBrace = s.lastIndexOf("}");
  if (firstBrace !== -1 && lastBrace > firstBrace) {
    s = s.slice(firstBrace, lastBrace + 1);
  }
  
  // Clean up union types, trailing commas, NaN/Infinity
  s = s.replace(/"([^"]+)"\s*:\s*"([^"]+)"\s*\|\s*"([^"]+)"/g, '"$1": "$2"');
  s = s.replace(/,\s*([}\]])/g, "$1");
  s = s.replace(/\bNaN\b|\bInfinity\b|\b-?Infinity\b/g, "null");
  
  return JSON.parse(s);
};

try {
  const doc = parsed as V4Doc;
  const out = reconcileV4(doc);  // Apply reconciliation engine
  return NextResponse.json(out);
} catch {
  return NextResponse.json(parsed); // Return raw if reconciliation fails
}

{
  voucher: {
    invoice_number: string,
    invoice_date: string,
    invoice_discount: string,
    invoice_discount_mode: "before_tax" | "after_tax" | "",
    round_off: string,
    total_invoice_amount: string,
    additional_charges: [{ name, amount, tax_rate, amount_includes_tax }],
    reconciliation: { status: "matched" | "unmatched" }
  },
  items: [{ price, unit, name, hsn_sac_code, quantity, tax_rate, discount_rate }],
  party: { party_gstin_number, party_name, party_address, ... }
}

if (isPdf) {
  const engine = process.env.OPENROUTER_PDF_ENGINE || "pdf-text";
  const plugins: unknown = body.plugins || [
    {
      id: "file-parser",
      pdf: { engine },
    },
  ];
  (payload as Record<string, unknown>).plugins = plugins as unknown;
}

messages: [
  { role: "system", content: SYSTEM_PROMPT },
  {
    role: "user",
    content: [
      { type: "text", text: "Return ONLY JSON matching the provided schema." },
      {
        type: "file",
        file: {
          filename: body.filename || "invoice.pdf",
          file_data: pdfData,  // Data URL or public URL
        },
      },
    ],
  },
]

if (body.annotations) {
  const msgs = payload.messages as Array<Record<string, unknown>>;
  msgs.push({
    role: "assistant",
    content: "Previous file parse metadata",
    annotations: body.annotations as unknown,
  });
}

const doc = React.useMemo(() => reconcileV4(data), [data]);
const matched = (doc.reconciliation?.error_absolute ?? 0) <= 0.05 
               && (doc.printed?.grand_total ?? 0) > 0;

// Celebration effect on success
setShowConfetti(true);
setJustCompleted(true);
setTimeout(() => setShowConfetti(false), 100);
setTimeout(() => setJustCompleted(false), 3000);

if (!response.ok) {
  const err = await response.text();
  return NextResponse.json(
    { error: `OpenRouter error: ${response.status} ${err}` },
    { status: 500 }
  );
}

return NextResponse.json(
  { error: `Model did not return valid JSON (${message})`, error_excerpt: excerpt },
  { status: 500 }
);

{error && (
  <div className="flex items-start gap-2 p-4 bg-red-50 ... rounded-lg" role="alert">
    <svg>...</svg>
    <div className="text-sm text-red-800">{error}</div>
  </div>
)}

React.useEffect(() => {
  let id: number | null = null;
  if (loading) {
    if (startRef.current == null) startRef.current = Date.now();
    id = window.setInterval(() => {
      if (startRef.current != null) setDurationMs(Date.now() - startRef.current);
    }, 100);
  }
  // Updates every 100ms to show live progress
}, [loading]);

const doc = React.useMemo(() => reconcileV4(data), [data]);