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.pycurrently consumes the cleaned bureau JSON report and builds an LLM prompt from that payload. Theget_pdf_reportimport 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:
filefile_url
- Rejects the request locally with
400if neither field is present. - Resolves the backend target in this order:
NEXT_PUBLIC_BACKEND_API_URLBACKEND_API_URLhttp://localhost:8000
Response Handling
- Parses JSON responses from the backend when the backend sets an
application/jsoncontent 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_PROJECTDOCUMENT_AI_LOCATIONDOCUMENT_AI_RESIDENCE_PERMIT_PROCESSOR_IDDOCUMENT_AI_PROCESSOR_IDis used as a fallback when the residence-permit processor ID is not set
- Rejects requests with
500if the Document AI configuration is incomplete. - Accepts two input modes:
file: validated against the allowed MIME typesfile_url: downloaded by_download_residence_permit_file_from_url
- Allowed uploaded MIME types:
application/pdfimage/pngimage/jpegimage/tiff
- Rejects empty uploads with
400. - Uses
google.cloud.documentai.DocumentProcessorServiceClient. - Uses a regional API endpoint when
DOCUMENT_AI_LOCATIONis notus:"{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_numberandresidence_card_numberare set from the same extracted permit value.extracted_textpreserves the full OCR text.pagesincludes page number and detected language codes for each page.- Page numbers fall back to the loop index when
page.page_numberis 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国籍・地域→nationalityDATE 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/pdfimage/pngimage/jpegimage/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, andbureau, - 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_PROJECTDOCUMENT_AI_LOCATIONDOCUMENT_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.ProcessRequestwith:nameraw_document.contentraw_document.mime_type
- Raises
UploadOcrErrorwhen the OCR call fails.
The parsed OCR output is normalized into:
textpages
Each page includes:
page_numberlanguagestables
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_ocrmodel_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
RequestIDfrom 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_summaryraw_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.pyfor residence-permit OCRbackend/src/usecase/credit_upload.pyfor 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 pathraw_document.content: raw file bytesraw_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_sessioncreates the object path.- The browser uploads directly to the signed URL.
finalize_upload_sessionvalidates the stored object.run_document_ai_ocrdownloads 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
500when Document AI environment variables are missing.500when the backend dependency import fails.400when:- the uploaded file type is unsupported,
- the uploaded file is empty,
- neither
filenorfile_urlis provided.
502when Google Document AI raises API or retry errors.500for generic OCR failures.
Credit Report OCR
UploadValidationErrorwhen:- 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.
UploadStorageErrorwhen:- the blob is missing,
- the size is missing,
- the upload object cannot be validated.
UploadOcrErrorwhen Document AI extraction fails.RuntimeErrorwhen the consent/session state is invalid for processing.
Dependencies
Runtime Libraries
fastapinext/servergoogle.cloud.documentaigoogle.cloud.storagegoogle.api_core.client_options.ClientOptionsgoogle.api_core.exceptionszod
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_uploadsrc.usecase.credit_reportsrc.usecase.prompts.credit_report_promptsrc.infra.external_apis.credit_reportsrc.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
fieldsentries 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. |