KYC and Identity Verification Domain - Residence Permit OCR and Credit Report OCR Processing Paths

Overview

This section covers the OCR-backed verification paths that turn identity and bureau documents into normalized data for KYC and credit workflows. On the residence-permit side, the frontend proxy accepts either an uploaded file or a file URL, forwards it to the FastAPI OCR endpoint, and returns structured permit fields plus page-level language metadata.

On the credit-report side, the backend manages a signed upload session, validates the final uploaded object, runs Google Document AI OCR against the stored file, and maps the extracted OCR payload into a canonical report shape. That canonical shape is designed for downstream verification and scoring flows: it preserves raw OCR data, captures provenance, and exposes stable feature vectors for model ingestion.

Architecture Overview

flowchart TD
  User[Applicant or reviewer] --> NextProxy[Next js residence permit OCR proxy]
  NextProxy --> FastAPIResidence[FastAPI residence permit OCR endpoint]
  FastAPIResidence --> DocumentAI[Google Document AI]
  DocumentAI --> FastAPIResidence
  FastAPIResidence --> NextProxy
  NextProxy --> User

  User --> CreditUpload[Credit report upload and OCR service]
  CreditUpload --> GCS[Google Cloud Storage]
  CreditUpload --> DocumentAI
  DocumentAI --> CreditUpload
  CreditUpload --> CanonicalCredit[Canonical credit report mapping]
  CanonicalCredit --> VerificationWorkflow[Verification and scoring workflows]

  CreditUpload --> CreditReportUsecase[Credit report analysis use case]
  CreditReportUsecase --> BureauAPI[Credit bureau APIs]
  CreditReportUsecase --> LLM[LLM summary generation]
  LLM --> CreditReportUsecase

  subgraph PresentationLayer[Presentation Layer]
    NextProxy
    FastAPIResidence
  end

  subgraph BusinessLayer[Business Layer]
    CreditUpload
    CanonicalCredit
    CreditReportUsecase
  end

  subgraph InfrastructureLayer[Infrastructure Layer]
    DocumentAI
    GCS
    BureauAPI
    LLM
  end

Residence Permit OCR Path

Next.js Residence Permit OCR Proxy Route

[!NOTE] The credit-report analysis use case in backend/src/usecase/credit_report.py currently consumes the cleaned bureau JSON report and builds an LLM prompt from that payload. The get_pdf_report import is present, but the PDF fetch line is commented out, so the live flow does not use the PDF content.

frontend/app/api/v1/application/residence-permit/ocr/route.ts

This route is the browser-facing ingress for residence-permit OCR submissions. It validates that the request includes either file or file_url, resolves the backend base URL from environment variables, forwards the multipart payload, and returns the backend response as JSON.

Public Methods

Method Description
POST Validates the incoming form data, forwards the OCR request to the backend, and passes the backend response through to the caller.

API Endpoint

Submit Residence Permit OCR Request via Next.js Proxy

{
    "title": "Submit Residence Permit OCR Request via Next.js Proxy",
    "description": "Accepts a residence permit file upload or file URL and forwards it to the backend OCR service",
    "method": "POST",
    "baseUrl": "<NextJsAppBaseUrl>",
    "endpoint": "/api/v1/application/residence-permit/ocr",
    "headers": [
        {
            "key": "Content-Type",
            "value": "multipart/form-data",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [],
    "bodyType": "formData",
    "requestBody": "{\n    \"file\": \"<binary residence permit file>\",\n    \"file_url\": \"https://example.com/residence-permit.pdf\"\n}",
    "formData": [
        {
            "key": "file",
            "value": "<binary residence permit file>",
            "required": false
        },
        {
            "key": "file_url",
            "value": "https://example.com/residence-permit.pdf",
            "required": false
        }
    ],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Pass-through OCR response from the backend",
            "body": "{\n    \"residence_permit_number\": \"AB12345678CD\",\n    \"residence_card_number\": \"AB12345678CD\",\n    \"full_name\": \"TURNER ELIZABETH\",\n    \"date_of_birth\": \"1985\\u5e7412\\u670831\\u65e5\",\n    \"nationality\": \"\\u7c73\\u56fd\",\n    \"address\": \"\\u6771\\u4eac\\u90fd\\u5343\\u4ee3\\u7530\\u533a\",\n    \"status_of_residence\": \"\\u7559\\u5b66\",\n    \"period_of_stay\": \"4\\u5e743\\u6708\",\n    \"expiry_date\": \"2023/07/01\",\n    \"extracted_text\": \"\\u5728\\u7559\\u30ab\\u30fc\\u30c9 \\u756a\\u53f7 AB12345678CD ...\",\n    \"pages\": [\n        {\n            \"page_number\": 1,\n            \"languages\": [\n                \"ja\",\n                \"en\"\n            ]\n        }\n    ]\n}"
        },
        "400": {
            "description": "Validation failure in the proxy route",
            "body": "{\n    \"detail\": \"Either file or file_url is required.\"\n}"
        }
    }
}

Request Handling

  • Accepts multipart form data only.
  • Requires at least one of:
    • file
    • file_url
  • Rejects the request locally with 400 if neither field is present.
  • Resolves the backend target in this order:
    • NEXT_PUBLIC_BACKEND_API_URL
    • BACKEND_API_URL
    • http://localhost:8000

Response Handling

  • Parses JSON responses from the backend when the backend sets an application/json content type.
  • Falls back to a text body wrapped as { detail: "<text>" } when the backend response is not JSON.
  • Returns the backend status code unchanged.

FastAPI Residence Permit OCR Endpoint

backend/src/interface/http_endpoints.py

This endpoint performs the actual OCR work. It validates environment configuration, accepts either an uploaded file or a remote file URL, calls Google Document AI, and normalizes the OCR result into a ResidencePermitOcrResponse.

Public Methods

Method Description
ocr_residence_permit Runs Document AI on a residence-permit document and returns normalized identity fields.

API Endpoint

Process Residence Permit OCR

{
    "title": "Process Residence Permit OCR",
    "description": "Runs Google Document AI on a residence permit upload or URL and returns normalized verification fields",
    "method": "POST",
    "baseUrl": "<BackendApiBaseUrl>",
    "endpoint": "/api/v1/application/residence-permit/ocr",
    "headers": [
        {
            "key": "Content-Type",
            "value": "multipart/form-data",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [],
    "bodyType": "formData",
    "requestBody": "{\n    \"file\": \"<binary residence permit file>\",\n    \"file_url\": \"https://example.com/residence-permit.pdf\"\n}",
    "formData": [
        {
            "key": "file",
            "value": "<binary residence permit file>",
            "required": false
        },
        {
            "key": "file_url",
            "value": "https://example.com/residence-permit.pdf",
            "required": false
        }
    ],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Normalized OCR result for verification workflows",
            "body": "{\n    \"residence_permit_number\": \"AB12345678CD\",\n    \"residence_card_number\": \"AB12345678CD\",\n    \"full_name\": \"TURNER ELIZABETH\",\n    \"date_of_birth\": \"1985\\u5e7412\\u670831\\u65e5\",\n    \"nationality\": \"\\u7c73\\u56fd\",\n    \"address\": \"\\u6771\\u4eac\\u90fd\\u5343\\u4ee3\\u7530\\u533a\",\n    \"status_of_residence\": \"\\u7559\\u5b66\",\n    \"period_of_stay\": \"4\\u5e743\\u6708\",\n    \"expiry_date\": \"2023/07/01\",\n    \"extracted_text\": \"\\u5728\\u7559\\u30ab\\u30fc\\u30c9 \\u756a\\u53f7 AB12345678CD ...\",\n    \"pages\": [\n        {\n            \"page_number\": 1,\n            \"languages\": [\n                \"ja\",\n                \"en\"\n            ]\n        }\n    ]\n}"
        },
        "400": {
            "description": "Client-side input validation failure",
            "body": "{\n    \"detail\": \"Either file or file_url is required.\"\n}"
        },
        "500": {
            "description": "Document AI configuration or runtime failure",
            "body": "{\n    \"detail\": \"Document AI environment variables are not fully configured.\"\n}"
        },
        "502": {
            "description": "Document AI service failure",
            "body": "{\n    \"detail\": \"Document AI error: <service error>\"\n}"
        }
    }
}

Runtime Behavior

  • Requires these environment variables:
    • GOOGLE_CLOUD_PROJECT
    • DOCUMENT_AI_LOCATION
    • DOCUMENT_AI_RESIDENCE_PERMIT_PROCESSOR_ID
    • DOCUMENT_AI_PROCESSOR_ID is used as a fallback when the residence-permit processor ID is not set
  • Rejects requests with 500 if the Document AI configuration is incomplete.
  • Accepts two input modes:
    • file: validated against the allowed MIME types
    • file_url: downloaded by _download_residence_permit_file_from_url
  • Allowed uploaded MIME types:
    • application/pdf
    • image/png
    • image/jpeg
    • image/tiff
  • Rejects empty uploads with 400.
  • Uses google.cloud.documentai.DocumentProcessorServiceClient.
  • Uses a regional API endpoint when DOCUMENT_AI_LOCATION is not us:
    • "{location}-documentai.googleapis.com"
  • Sends the raw bytes and MIME type to documentai.ProcessRequest.

Normalization Rules

The endpoint turns the OCR document into a verification-friendly payload:

  • residence_permit_number and residence_card_number are set from the same extracted permit value.
  • extracted_text preserves the full OCR text.
  • pages includes page number and detected language codes for each page.
  • Page numbers fall back to the loop index when page.page_number is absent.
  • Language codes are de-duplicated and sorted.
  • The backend test fixture proves the field extractor recognizes Japanese labels and maps them into canonical response fields:
    • 氏名 → full_name
    • 住所 → address
    • 在留資格 → status_of_residence
    • 在留期間 → period_of_stay
    • 生年月日 → date_of_birth
    • 国籍・地域 → nationality
    • DATE OF EXPIRATION → expiry_date

Residence Permit OCR Flow

sequenceDiagram
  participant U as User
  participant N as Next js Proxy Route
  participant F as FastAPI OCR Endpoint
  participant D as Google Document AI
  participant R as Residence Permit Response

  U->>N: Submit file or file_url
  N->>N: Validate multipart payload
  N->>F: Forward form data
  F->>F: Validate env vars and input
  F->>D: ProcessRequest with raw document bytes
  D-->>F: OCR document
  F->>F: Extract text, pages, and canonical fields
  F-->>N: ResidencePermitOcrResponse
  N-->>U: JSON response

Credit Report OCR and Canonicalization

OCR Configuration and Constraints

backend/src/usecase/credit_upload.py

This module owns the OCR upload lifecycle for credit reports. It creates signed upload sessions, validates completed uploads, runs Google Document AI, and maps OCR output into a canonical report structure.

Constants

Name Type Description
ALLOWED_CONTENT_TYPES set[str] Allowed uploaded content types for credit report ingestion.
MAX_UPLOAD_BYTES int Maximum accepted upload size, set to 25 MB.

Allowed credit report file types:

  • application/pdf
  • image/png
  • image/jpeg
  • image/tiff

Upload size limit:

  • 25 MB

Public Types

UploadOcrError

backend/src/usecase/credit_upload.py

Raised when OCR extraction cannot be completed.

Property Type Description
— — Exception type with no instance properties.

Public Methods

Method Description
create_signed_upload_session Creates a validated upload session, persists it, and returns a signed PUT URL for the object path.
finalize_upload_session Verifies that the uploaded object exists and matches the declared size and MIME type.
run_document_ai_ocr Downloads the finalized object, sends it to Document AI, and returns parsed OCR text plus page metadata.
map_ocr_to_canonical_credit Converts OCR payload fields into the canonical credit-report structure used by verification workflows.
build_credit_model_adapter_features Builds a stable feature envelope from OCR tradelines for model ingestion.

Upload Session Behavior

create_signed_upload_session builds the storage path as:

manual-credit-reports/{user_id}/{bureau}/{upload_session_id}/{object_name}

It then:

  • validates MIME type and file size,
  • persists the upload session,
  • creates a Google Cloud Storage blob,
  • returns a version 4 signed PUT URL,
  • sets the signed URL expiration to the computed upload expiry.

finalize_upload_session is the upload-complete checkpoint. It:

  • loads the active session by upload_session_id, user_id, and bureau,
  • rejects expired or invalid sessions,
  • checks that the object exists in Cloud Storage,
  • reloads the blob metadata,
  • rejects objects missing a size,
  • deletes the blob and rejects the upload if:
    • the stored size exceeds the declared size,
    • the stored size exceeds MAX_UPLOAD_BYTES,
    • the stored content type does not exactly match the session content type,
  • re-applies the content-type constraint before returning the session.

Google Document AI OCR Behavior

[!IMPORTANT] The upload-complete path is strict about the stored object metadata. If the object size or content type does not match the session, the blob is deleted and the completion step fails immediately.

run_document_ai_ocr uses the finalized upload session to produce OCR output.

Required environment variables:

  • GOOGLE_CLOUD_PROJECT
  • DOCUMENT_AI_LOCATION
  • DOCUMENT_AI_PROCESSOR_ID

Runtime behavior:

  • Loads the upload object from Google Cloud Storage using upload_session.object_path.
  • Rejects the run if the object is missing.
  • Downloads the object bytes.
  • Selects a Document AI client in the same region-aware way as the residence-permit endpoint.
  • Builds the processor resource path from:
    • project
    • location
    • processor ID
  • Sends a documentai.ProcessRequest with:
    • name
    • raw_document.content
    • raw_document.mime_type
  • Raises UploadOcrError when the OCR call fails.

The parsed OCR output is normalized into:

  • text
  • pages

Each page includes:

  • page_number
  • languages
  • tables

The table extraction logic copies header cells and body cells from the Document AI table layout into a JSON-friendly shape.

Canonical Credit Mapping

map_ocr_to_canonical_credit converts OCR payloads into a verification-ready report envelope.

Mapped OCR keys:

Canonical field OCR keys used
consumer.full_name full_name, name
consumer.date_of_birth date_of_birth, dob
consumer.ssn ssn, social_security_number
consumer.address address, current_address
scores[0].model score_model, model
scores[0].score score, credit_score, fico_score
summary.total_balance total_balance, balances_total
summary.total_limit total_limit, credit_limit
summary.utilization utilization, credit_utilization
summary.delinquent_accounts delinquent_accounts

The function also preserves:

  • raw_ocr
  • model_adapter
  • upload session metadata
  • user confirmation metadata

Canonical Report Shape

report_metadata
Property Type Description
upload_session_id string Upload session identifier.
bureau string Bureau source identifier.
user_id string User identifier tied to the upload.
country string Country associated with the report.
object_path string Cloud Storage object path.
ingested_at string UTC timestamp when mapping ran.
user_confirmation.confirmed boolean User confirmation flag.
user_confirmation.confirmed_at string Confirmation timestamp in ISO format.
consumer, scores, and summary

Each mapped field is emitted through the same field envelope:

Property Type Description
value any Extracted OCR value.
confidence `number \ null`
provenance.source string Always set to ocr.
provenance.page any Source page metadata copied from OCR.
provenance.bounding_box any Source bounding box copied from OCR.
model_adapter

The model adapter output provides a stable contract for scoring models.

Property Type Description
adapter_schema_version string Fixed adapter version string.
feature_vector.no_of_unsecured_loans number Count of unsecured tradelines.
feature_vector.value_of_unsecured_loans number Sum of unsecured tradeline values.
feature_vector.no_of_major_loans number Count of major tradelines.
feature_vector.value_of_major_loans number Sum of major tradeline values.
feature_vector.years_since_first_major_loan number Maximum age among major tradelines.
feature_vector.tradeline_count number Number of normalized tradelines.
normalized_tradelines array Tradeline array with normalized numeric flags and amounts.

Normalized tradeline fields:

Property Type Description
unsecured_loan_flag number Normalized unsecured flag.
major_loan_flag number Normalized major-loan flag.
disbursed_amount number Normalized disbursed amount.
years_since_disbursement number Normalized age in years.

Credit OCR and Canonicalization Flow

sequenceDiagram
  participant U as User
  participant S as Upload Session Service
  participant G as Google Cloud Storage
  participant D as Google Document AI
  participant M as Canonical Mapper
  participant V as Verification Workflow

  U->>S: Complete upload and request finalization
  S->>G: Load blob metadata and validate object
  G-->>S: Blob size and content type
  S->>D: ProcessRequest with raw document bytes
  D-->>S: OCR document
  S->>M: Parsed OCR payload
  M->>M: Build canonical credit report
  M-->>V: Canonical report with provenance and model adapter

Credit Report Upload Complete Request and Response Models

backend/src/interface/schemas.py

These models represent the upload-complete handoff for OCR normalization.

CreditReportUploadCompleteRequest

Property Type Description
user_id str User identifier associated with the upload session.
bureau str Bureau name for the uploaded report.
ocr_payload Dict[str, Any] Raw OCR payload to be normalized.
user_confirmed bool Indicates whether the user confirmed the extracted OCR fields.
confirmed_at Optional[datetime] Optional confirmation timestamp.

CreditReportUploadCompleteResponse

Property Type Description
upload_session_id str Upload session identifier.
object_path str Cloud Storage object path for the finalized upload.
canonical_credit_report Dict[str, Any] Canonicalized report payload ready for verification workflows.

Canonical Credit Upload Complete Example

{
  "user_id": "user-1",
  "bureau": "equifax",
  "ocr_payload": {
    "fields": [
      {
        "name": "full_name",
        "value": "Alex Doe",
        "confidence": 0.94,
        "provenance": {
          "page": 1,
          "bounding_box": {
            "x": 10,
            "y": 20,
            "width": 140,
            "height": 18
          }
        }
      },
      {
        "name": "credit_score",
        "value": 712,
        "confidence": 0.88,
        "provenance": {
          "page": 1,
          "bounding_box": {
            "x": 10,
            "y": 42,
            "width": 60,
            "height": 18
          }
        }
      }
    ],
    "tradelines": [
      {
        "unsecured_loan_flag": "1",
        "major_loan_flag": "1",
        "disbursed_amount": "12000",
        "years_since_disbursement": "4"
      }
    ]
  },
  "user_confirmed": true,
  "confirmed_at": "2026-04-26T12:00:00Z"
}
{
  "upload_session_id": "sess-1",
  "object_path": "manual-credit-reports/user-1/equifax/sess-1/report.pdf",
  "canonical_credit_report": {
    "report_metadata": {
      "upload_session_id": "sess-1",
      "bureau": "equifax",
      "user_id": "user-1",
      "country": "US",
      "object_path": "manual-credit-reports/user-1/equifax/sess-1/report.pdf",
      "ingested_at": "2026-04-26T12:00:00Z",
      "user_confirmation": {
        "confirmed": true,
        "confirmed_at": "2026-04-26T12:00:00Z"
      }
    },
    "consumer": {
      "full_name": {
        "value": "Alex Doe",
        "confidence": 0.94,
        "provenance": {
          "source": "ocr",
          "page": 1,
          "bounding_box": {
            "x": 10,
            "y": 20,
            "width": 140,
            "height": 18
          }
        }
      },
      "date_of_birth": null,
      "ssn": null,
      "address": null
    },
    "scores": [
      {
        "model": {
          "value": "FICO 8",
          "confidence": 0.91,
          "provenance": {
            "source": "ocr",
            "page": 1,
            "bounding_box": {
              "x": 10,
              "y": 42,
              "width": 80,
              "height": 18
            }
          }
        },
        "score": {
          "value": 712,
          "confidence": 0.88,
          "provenance": {
            "source": "ocr",
            "page": 1,
            "bounding_box": {
              "x": 10,
              "y": 42,
              "width": 60,
              "height": 18
            }
          }
        }
      }
    ],
    "summary": {
      "total_balance": {
        "value": 12000,
        "confidence": 0.82,
        "provenance": {
          "source": "ocr",
          "page": 2,
          "bounding_box": {
            "x": 12,
            "y": 18,
            "width": 120,
            "height": 18
          }
        }
      },
      "total_limit": {
        "value": 24000,
        "confidence": 0.82,
        "provenance": {
          "source": "ocr",
          "page": 2,
          "bounding_box": {
            "x": 12,
            "y": 40,
            "width": 120,
            "height": 18
          }
        }
      },
      "utilization": {
        "value": 0.5,
        "confidence": 0.82,
        "provenance": {
          "source": "ocr",
          "page": 2,
          "bounding_box": {
            "x": 12,
            "y": 62,
            "width": 120,
            "height": 18
          }
        }
      },
      "delinquent_accounts": {
        "value": 0,
        "confidence": 0.82,
        "provenance": {
          "source": "ocr",
          "page": 2,
          "bounding_box": {
            "x": 12,
            "y": 84,
            "width": 120,
            "height": 18
          }
        }
      }
    },
    "model_adapter": {
      "adapter_schema_version": "v1",
      "feature_vector": {
        "no_of_unsecured_loans": 1,
        "value_of_unsecured_loans": 12000,
        "no_of_major_loans": 1,
        "value_of_major_loans": 12000,
        "years_since_first_major_loan": 4,
        "tradeline_count": 1
      },
      "normalized_tradelines": [
        {
          "unsecured_loan_flag": 1,
          "major_loan_flag": 1,
          "disbursed_amount": 12000,
          "years_since_disbursement": 4
        }
      ]
    },
    "raw_ocr": {
      "fields": [
        {
          "name": "full_name",
          "value": "Alex Doe",
          "confidence": 0.94
        },
        {
          "name": "credit_score",
          "value": 712,
          "confidence": 0.88
        }
      ],
      "tradelines": [
        {
          "unsecured_loan_flag": "1",
          "major_loan_flag": "1",
          "disbursed_amount": "12000",
          "years_since_disbursement": "4"
        }
      ]
    }
  }
}

Credit Report Analysis Use Case

backend/src/usecase/credit_report.py

This use case turns a bureau response into an LLM-ready summary for underwriting or review. It is not the OCR step itself; instead, it consumes bureau data after extraction and preprocessing.

Public Methods

Method Description
generate_credit_report Logs into the bureau service, fetches the report, preprocesses it, generates an analysis prompt, and returns the LLM summary plus the raw report.

Processing Flow

  • Calls login_user()
  • Reads the returned token
  • Calls get_credit_report(token, user_data)
  • Extracts RequestID from the bureau response
  • Preprocesses the report with preprocess_equifax_data
  • Builds the prompt with get_analyze_credit_report_prompt
  • Calls generate_llm_response(prompt)
  • Returns:
    • llm_summary
    • raw_report

Output Shape

Property Type Description
llm_summary any LLM-generated summary payload.
raw_report dict Raw bureau response used as the source of truth.

Credit Report Analysis Flow

sequenceDiagram
  participant U as User or workflow
  participant C as Credit Report Use Case
  participant B as Bureau APIs
  participant P as Preprocessor
  participant L as LLM Client

  U->>C: generate_credit_report user_data
  C->>B: login_user
  B-->>C: token
  C->>B: get_credit_report token and user_data
  B-->>C: report_data
  C->>P: preprocess_equifax_data report_data
  P-->>C: cleaned_data
  C->>C: get_analyze_credit_report_prompt cleaned_data
  C->>L: generate_llm_response prompt
  L-->>C: llm_summary
  C-->>U: llm_summary and raw_report

Google Document AI OCR Service

This section is the shared infrastructure layer behind both OCR paths. It is used in two places:

  • backend/src/interface/http_endpoints.py for residence-permit OCR
  • backend/src/usecase/credit_upload.py for credit-report OCR

Client Initialization and Region Selection

The code uses google.cloud.documentai.DocumentProcessorServiceClient.

  • For location == "us", it uses the default client.
  • For any other location, it uses:
    • ClientOptions(api_endpoint=f"{location}-documentai.googleapis.com")

That pattern is implemented in both OCR paths so the processor can run in the correct Document AI region.

Document AI Input Shape

Both paths send a documentai.ProcessRequest with:

  • name: the processor resource path
  • raw_document.content: raw file bytes
  • raw_document.mime_type: uploaded or resolved MIME type

Output Normalization Pattern

  • The raw Document AI document is not returned directly.
  • The backend extracts:
    • full text
    • page numbers
    • language codes
    • table contents for credit reports
  • The resulting JSON becomes the contract for downstream verification and scoring logic.

Google Cloud Storage Service

Google Cloud Storage is the persistence layer for finalized credit-report uploads.

Public Methods Used by the OCR Flow

Method Description
bucket Resolves the upload bucket.
blob Resolves the object path for an upload session.
generate_signed_url Creates the V4 signed upload URL for the session.
exists Verifies that the uploaded object is present.
reload Refreshes blob metadata before validation.
delete Removes invalid uploads during completion validation.
download_as_bytes Fetches the finalized upload bytes for OCR.

Data Flow

  • create_signed_upload_session creates the object path.
  • The browser uploads directly to the signed URL.
  • finalize_upload_session validates the stored object.
  • run_document_ai_ocr downloads the object bytes and sends them to Document AI.

Storage Path Pattern

manual-credit-reports/{user_id}/{bureau}/{upload_session_id}/{object_name}

Error Handling

Residence Permit OCR

  • 500 when Document AI environment variables are missing.
  • 500 when the backend dependency import fails.
  • 400 when:
    • the uploaded file type is unsupported,
    • the uploaded file is empty,
    • neither file nor file_url is provided.
  • 502 when Google Document AI raises API or retry errors.
  • 500 for generic OCR failures.

Credit Report OCR

  • UploadValidationError when:
    • the session is invalid or expired,
    • the uploaded object exceeds the declared file size,
    • the uploaded object exceeds MAX_UPLOAD_BYTES,
    • the content type does not match the session.
  • UploadStorageError when:
    • the blob is missing,
    • the size is missing,
    • the upload object cannot be validated.
  • UploadOcrError when Document AI extraction fails.
  • RuntimeError when the consent/session state is invalid for processing.

Dependencies

Runtime Libraries

  • fastapi
  • next/server
  • google.cloud.documentai
  • google.cloud.storage
  • google.api_core.client_options.ClientOptions
  • google.api_core.exceptions
  • zod

External Services

  • Google Document AI
  • Google Cloud Storage
  • Credit bureau APIs consumed by backend/src/usecase/credit_report.py
  • LLM generation service consumed by generate_llm_response

Repository-Local Dependencies

  • src.usecase.credit_upload
  • src.usecase.credit_report
  • src.usecase.prompts.credit_report_prompt
  • src.infra.external_apis.credit_report
  • src.infra.external_apis.equifax_cleaner

Testing Considerations

Residence Permit OCR

  • Confirms Japanese label extraction from the OCR document.
  • Confirms form-field values are preferred when both anchor text and form data are present.
  • Confirms the canonical response fields are populated from the extracted schema.

Credit Report OCR

  • Confirms OCR payload indexing uses fields entries and top-level scalar values.
  • Confirms canonical fields map from multiple OCR key aliases.
  • Confirms model adapter features are derived from tradeline data.
  • Confirms tradeline normalization preserves numeric values and flags.

Credit Report Analysis

  • Confirms the analysis use case returns both the LLM summary and the raw bureau report.
  • Confirms bureau preprocessing feeds the prompt generator.

Key Classes Reference

Class Responsibility
route.ts Next.js proxy for residence-permit OCR submissions.
http_endpoints.py FastAPI residence-permit OCR endpoint and response assembly.
credit_upload.py Credit-report upload validation, Document AI OCR, and canonicalization.
schemas.py Request and response models for upload-complete credit workflows.
credit_report.py Credit-report preprocessing and LLM summary generation.