KYC and Identity Verification Domain - KYC, AML, and Underwriting Eligibility Interactions
Overview
This domain ties together applicant identity verification, bureau access rules, consent enforcement, and underwriting eligibility gating. On the frontend side, frontend/components/underwriting-compliance.tsx presents an underwriting document preview with regenerate and send actions, while the KYC proxy routes in frontend/app/api/kyc/route.ts and frontend/app/api/kyc/[verificationId]/route.ts start identity verification and retrieve verification status. On the backend, backend/src/usecase/kyc.py passes KYC requests through to a KycGateway, and backend/src/usecase/japan_staff_credit.py enforces consent, operator authorization, and bureau-access constraints before a staff-initiated credit pull can proceed.
The compliance policy is not just about identity data collection. It also controls what happens after identity is verified: permissible purpose is carried into bureau access, consent expiry and revocation block pulls, unauthorized operators are rejected, and AML-related flags in the underwriting pipeline can decline an application before scoring. The planning document in documents/spinwheel-integration-plan.md describes a streamlined Equifax-based intake path, but the implemented route still applies stricter field requirements and uses existing KYC gateway orchestration.
Architecture Overview
flowchart TB
subgraph PresentationLayer [Presentation Layer]
UnderwritingCompliance[Underwriting Compliance component]
KycCreateRoute[POST api kyc route]
KycStatusRoute[GET api kyc verification route]
end
subgraph BusinessLayer [Business Layer]
KycUseCases[Kyc use cases]
JapanStaffCreditUseCases[Japan staff credit use cases]
EligibilityGate[AML and underwriting gate]
end
subgraph DataAccessLayer [Data Access Layer]
BackendCreateToken[create_link_token_id_verification]
BackendVerificationStatus[identity_verification_status]
ConsentRepository[StaffCreditConsentRepository]
PullLogRepository[StaffCreditPullLogRepository]
BureauClient[JapanCreditBureauHTTPClient]
end
subgraph ExternalSystems [External Systems]
KycGateway[KycGateway]
BureauNetwork[Bureau network]
EmailOverlay[EmailOverlay]
end
UnderwritingCompliance --> EmailOverlay
KycCreateRoute --> KycUseCases
KycStatusRoute --> KycUseCases
KycUseCases --> BackendCreateToken
KycUseCases --> BackendVerificationStatus
BackendCreateToken --> KycGateway
BackendVerificationStatus --> KycGateway
JapanStaffCreditUseCases --> ConsentRepository
JapanStaffCreditUseCases --> PullLogRepository
JapanStaffCreditUseCases --> BureauClient
BureauClient --> BureauNetwork
EligibilityGate --> KycUseCases
EligibilityGate --> JapanStaffCreditUseCases
Policy and Eligibility Rules
[!NOTE]
documents/spinwheel-integration-plan.mddescribes a phone number and date of birth intake, butbuildPrefillPayloadinfrontend/app/api/kyc/route.tsrequires email, phone, full name, date of birth, and address fields before the backend verifier is called. The current route does not implement the lighter intake shape described in the plan.
The code expresses a set of hard gates that determine whether identity verification can start, whether bureau access is allowed, and whether underwriting can proceed.
| Rule | Code Path | Operational Effect |
|---|---|---|
| Identity payload must include email and phone | buildPrefillPayload in frontend/app/api/kyc/route.ts |
The verification request is rejected with a 400 response if either field is missing. |
| Address fields must be present | buildPrefillPayload |
Missing street, city, region, or postal code stops the KYC bootstrap. |
| Auth token must be present | POST /api/kyc route |
Requests without a token return 401 before any backend lookup. |
| Consent expiration must be in the future | register_staff_credit_consent |
Past-dated consent is rejected with ConsentExpiredError. |
| Consent must be active at request time | perform_staff_credit_pull |
Expired or revoked consent blocks bureau access. |
| Operator must be allowed by consent | perform_staff_credit_pull and consent.ensure_operator_allowed |
Unauthorized staff members are rejected with OperatorNotAllowedError. |
| Permissible purpose must be resolved | perform_staff_credit_pull |
The resolved purpose is passed to the bureau client and becomes part of the audit trail. |
| AML risk blocks underwriting | backend/src/ml/credit_pipeline_validation.py |
AML_RISK_DETECTED is a decline flag, so scoring is halted before model output. |
| KYC failure blocks underwriting | backend/src/ml/credit_pipeline_validation.py |
KYC_NOT_PASSED is a decline flag, so the application does not continue to scoring. |
| Bureau absence can trigger refer status | backend/src/ml/credit_pipeline_validation.py |
Missing bureau data, missing banking data, or insufficient history can refer the application instead of passing it. |
Presentation Layer
Underwriting Compliance Document Preview
[!IMPORTANT]
perform_staff_credit_pulldoes not let staff bypass consent. It checks the stored consent, rejects revoked or expired consent, verifies the operator ID, and only then calls the bureau client. The bureau call happens after those checks, so operator misconfiguration is blocked before any external pull is attempted.
frontend/components/underwriting-compliance.tsx
This component renders a mortgage underwriting document preview, animates the document text while it is “generating,” and opens an email overlay when the operator chooses to send the document onward. It does not call the KYC backend directly; it is the visible underwriting artifact that sits alongside the identity and compliance workflow.
Properties
| Property | Type | Description |
|---|---|---|
isGenerating |
boolean |
Controls the simulated document generation state and disables the regenerate button while active. |
document |
string |
Holds the current underwriting document text rendered inside the preview. |
isOverlayOpen |
boolean |
Controls whether EmailOverlay is displayed. |
animatedDocument |
string |
Output from useAnimatedText(document, isGenerating) used in the preview area. |
Internal Actions
| Action | Description |
|---|---|
handleRegenerate |
Turns generation off, waits 100 ms, resets the document text to INITIAL_DOCUMENT, and re-enables generation. |
handleSend |
Opens the EmailOverlay. |
useEffect timer cleanup |
Starts a 10-second timer on mount and clears it on unmount. |
Dependencies
| Type | Description |
|---|---|
useState |
Local UI state for generation and overlay visibility. |
useEffect |
Handles the generation timeout and cleanup. |
useAnimatedText |
Animates the underwriting document text while generation is active. |
EmailOverlay |
Modal-like sending surface used by the send action. |
Card, Button |
Presentation controls for the preview and action buttons. |
UI States
| State | Trigger | Result |
|---|---|---|
| Generating | Initial mount or handleRegenerate |
Text is animated and the regenerate button is disabled. |
| Ready | Timer completes or document reset finishes | Preview stops animating and the regenerate button becomes usable. |
| Overlay open | handleSend |
EmailOverlay is shown. |
API Integration
Create Identity Verification Link Token
POST /api/kyc
{
"title": "Create Identity Verification Link Token",
"description": "Validates the applicant reference, loads the application, builds the prefill payload, and starts identity verification through the backend verifier",
"method": "POST",
"baseUrl": "<NextJsAppBaseUrl>",
"endpoint": "/api/kyc",
"headers": [
{
"key": "Authorization",
"value": "Bearer <token>",
"required": true
},
{
"key": "Content-Type",
"value": "application/json",
"required": true
}
],
"queryParams": [],
"pathParams": [],
"bodyType": "json",
"requestBody": "{\n \"applicationId\": \"app_100024\"\n}",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Identity verification started",
"body": "{\n \"linkToken\": \"link-sandbox-4d1f9d9f2c3a\",\n \"verification\": {\n \"status\": \"success\"\n },\n \"applicant\": {\n \"id\": \"app_100024\",\n \"email\": \"[email protected]\",\n \"phone\": \"+1-202-555-0148\",\n \"fullName\": \"Jane Doe\",\n \"dateOfBirth\": \"1992-04-18\",\n \"address\": {\n \"street\": \"123 Main St\",\n \"city\": \"Seattle\",\n \"region\": \"WA\",\n \"postalCode\": \"98101\",\n \"country\": \"US\"\n }\n }\n}"
},
"400": {
"description": "Invalid request payload or missing applicant data",
"body": "{\n \"detail\": \"Application id is required\"\n}"
},
"401": {
"description": "Authentication is missing",
"body": "{\n \"detail\": \"Authentication required\"\n}"
},
"404": {
"description": "Applicant not found",
"body": "{\n \"detail\": \"Application not found\"\n}"
},
"502": {
"description": "Backend verification or application lookup failed",
"body": "{\n \"detail\": \"Failed to start Plaid identity verification\"\n}"
}
}
}
This route performs several checks before it reaches the backend verifier:
- Parses
applicationIdwithzod. - Extracts an auth token from the incoming headers.
- Loads application data from backend candidates.
- Builds the prefill payload from application fields.
- Calls the backend verifier with
POST /create_link_token_id_verification. - Returns the link token, backend verification payload, and applicant summary.
Request Model: requestSchema
| Property | Type | Description |
|---|---|---|
applicationId |
`string \ | number` |
Internal Prefill Model: PrefillPayload
| Property | Type | Description |
|---|---|---|
email |
string |
Applicant email forwarded to the backend verifier. |
phone |
string |
Normalized phone number. |
first_name |
string |
First name extracted from the application full name. |
last_name |
string |
Last name extracted from the application full name or defaulted to Applicant. |
dob_year |
number |
Year extracted from the application date of birth. |
dob_month |
number |
Month extracted from the application date of birth. |
dob_day |
number |
Day extracted from the application date of birth. |
street |
string |
Required address line. |
city |
string |
Required address city. |
region |
string |
Required address region. |
postal_code |
string |
Required postal code. |
country |
string |
Address country, defaulting to US. |
Response Model
| Property | Type | Description |
|---|---|---|
linkToken |
string |
Token returned by the backend verification service. |
verification |
Record<string, unknown> |
Verification payload forwarded from the backend. |
applicant |
object |
Applicant details used for the verification prefill. |
[!NOTE] The route’s log and error strings still say “Plaid verification” and “Plaid KYC,” even though the surrounding plan document describes an Equifax-based identity flow. That mismatch affects operator-facing diagnostics and can make the integration look like a different provider than the one described in
documents/spinwheel-integration-plan.md.
Get Identity Verification Status
GET /api/kyc/[verificationId]
{
"title": "Get Identity Verification Status",
"description": "Proxies verification status lookups to the backend identity-verification status endpoint",
"method": "GET",
"baseUrl": "<NextJsAppBaseUrl>",
"endpoint": "/api/kyc/{verificationId}",
"headers": [],
"queryParams": [],
"pathParams": [
{
"key": "verificationId",
"value": "verif_123456",
"required": true
}
],
"bodyType": "none",
"requestBody": "",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Verification status returned",
"body": "{\n \"verification\": {\n \"status\": \"success\"\n }\n}"
},
"400": {
"description": "Invalid verification id",
"body": "{\n \"detail\": \"Invalid verification id\"\n}"
},
"404": {
"description": "Verification record not found",
"body": "{\n \"detail\": \"Verification not found\"\n}"
},
"502": {
"description": "Backend status lookup failed",
"body": "{\n \"detail\": \"Failed to load verification status\"\n}"
}
}
}
This route does not require an auth token in the visible code path. It validates the path parameter, calls the backend identity status endpoint, and returns the result under a verification wrapper. The backend fetch uses cache: "no-store", so each request is evaluated fresh.
Response Model
| Property | Type | Description |
|---|---|---|
verification |
Record<string, unknown> |
Backend verification status payload forwarded without additional normalization. |
Create Verification Link Token
POST /create_link_token_id_verification
{
"title": "Create Verification Link Token",
"description": "Builds a user record from the prefill request, invokes the KYC gateway, and returns the link token response",
"method": "POST",
"baseUrl": "<BackendApiBaseUrl>",
"endpoint": "/create_link_token_id_verification",
"headers": [
{
"key": "Content-Type",
"value": "application/json",
"required": true
}
],
"queryParams": [],
"pathParams": [],
"bodyType": "json",
"requestBody": "{\n \"email\": \"[email protected]\",\n \"phone\": \"+1-202-555-0148\",\n \"first_name\": \"Jane\",\n \"last_name\": \"Doe\",\n \"dob_year\": 1992,\n \"dob_month\": 4,\n \"dob_day\": 18,\n \"street\": \"123 Main St\",\n \"city\": \"Seattle\",\n \"region\": \"WA\",\n \"postal_code\": \"98101\",\n \"country\": \"US\"\n}",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Backend verification bootstrap response",
"body": "{\n \"link_token\": \"link-sandbox-4d1f9d9f2c3a\",\n \"verification\": {\n \"status\": \"success\"\n }\n}"
},
"500": {
"description": "Gateway failure",
"body": "{\n \"detail\": \"Plaid response did not include a link_token\"\n}"
}
}
}
backend/src/interface/http_endpoints.py creates a user_id, maps request values into user_data, instantiates PlaidKycGateway, and passes the payload to generate_link_token_id_verification. If the gateway does not return a link token, the handler raises a 500 error.
Response Model
| Property | Type | Description |
|---|---|---|
link_token |
string |
Link token generated by the KYC gateway. |
verification |
object |
Verification payload returned by the gateway if present. |
Get Verification Status
GET /identity_verification_status/{verification_id}
{
"title": "Get Verification Status",
"description": "Returns the current identity verification status for the provided verification id",
"method": "GET",
"baseUrl": "<BackendApiBaseUrl>",
"endpoint": "/identity_verification_status/{verification_id}",
"headers": [],
"queryParams": [],
"pathParams": [
{
"key": "verification_id",
"value": "verif_123456",
"required": true
}
],
"bodyType": "none",
"requestBody": "",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Status payload returned by the gateway",
"body": "{\n \"status\": \"success\"\n}"
}
}
}
This endpoint passes the verification ID to the gateway and returns the resulting status object directly.
Response Model
| Property | Type | Description |
|---|---|---|
status |
string |
Gateway status response forwarded to the caller. |
Business Layer
KYC Use Cases
backend/src/usecase/kyc.py
These use cases are thin delegators around KycGateway. They do not add policy logic themselves; they simply pass the input through and return the gateway payload.
Methods
| Method | Description | Returns |
|---|---|---|
generate_link_token_id_verification |
Calls create_link_token_id_verification on the injected KycGateway. |
Dict |
kyc_get_identity_verification_status |
Calls get_identity_verification_status on the injected KycGateway. |
Dict[str, Any] |
Dependencies
| Type | Description |
|---|---|
KycGateway |
Gateway contract used to start verification and fetch verification status. |
Dict |
Input and output payloads are dictionary-based. |
Japan Staff Credit Use Cases
backend/src/usecase/japan_staff_credit.py
These use cases control the operator-initiated bureau workflow in Japan. They enforce consent validity, operator authorization, and bureau call logging before any credit report is returned.
Methods
| Method | Description | Returns |
|---|---|---|
register_staff_credit_consent |
Validates that the consent expiry is in the future, deduplicates and sorts allowed operator IDs, and persists the consent. | StaffCreditConsent |
perform_staff_credit_pull |
Validates consent existence, revocation state, expiry, and operator eligibility before requesting a bureau report and persisting the pull log. | Dict[str, object] |
Dependencies
| Type | Description |
|---|---|
StaffCreditConsentRepository |
Stores and retrieves consent records by reference. |
StaffCreditPullLogRepository |
Persists request logs for bureau pulls. |
bureau_client |
Requests the bureau report using customer profile and permissible purpose. |
StaffCreditConsentRequest |
Input model for consent registration. |
StaffCreditPullRequest |
Input model for a staff-initiated bureau pull. |
Eligibility Behavior
register_staff_credit_consentrejects past-dated expirations withConsentExpiredError.perform_staff_credit_pullraisesConsentNotFoundErrorif the consent reference does not exist.perform_staff_credit_pullraisesConsentRevokedErrororConsentExpiredErrorwhen the stored consent is not active.consent.ensure_operator_allowed(request.operator_id)blocks unauthorized operator IDs.- The bureau call uses
request.permissible_purpose or consent.permissible_purpose, so the resolved purpose is what reaches the bureau client. - Bureau failures still create a persisted log entry before
BureauRequestErroris raised.
Eligibility Gate and AML Flags
backend/src/ml/credit_pipeline_validation.py
The scoring pipeline uses deterministic gate ordering before any model call. The documented priority is:
DECLINEREFERPASS
Relevant flags from the code are:
KYC_NOT_PASSEDFRAUD_RISK_DETECTEDAML_RISK_DETECTEDBUREAU_REQUIRED_BUT_ABSENTNO_BANKING_DATAINSUFFICIENT_HISTORY
In practice, a KYC or AML problem can stop underwriting before credit scoring. A bureau gap can push the case into a refer path instead of a pass path.
Data Models
Staff Credit Consent Request
src.domain.japan_credit.StaffCreditConsentRequest as used in backend/tests/usecase/test_japan_staff_credit.py
| Property | Type | Description |
|---|---|---|
consent_reference |
str |
External reference used to retrieve consent. |
customer_reference |
str |
Customer identifier associated with the consent. |
customer_name |
str |
Customer display name. |
permissible_purpose |
str |
Bureau purpose attached to the consent. |
expires_at |
datetime |
Consent expiry timestamp. |
allowed_operator_ids |
list[str] |
Allowed staff operator IDs. |
customer_profile |
dict[str, object] |
Customer profile sent to the bureau client. |
metadata |
`dict[str, object] \ | None` |
Staff Credit Consent
src.domain.japan_credit.StaffCreditConsent as used in backend/tests/usecase/test_japan_staff_credit.py
| Property | Type | Description |
|---|---|---|
id |
`int \ | None` |
consent_reference |
str |
External reference used to locate the consent. |
customer_reference |
str |
Customer identifier. |
customer_name |
str |
Customer name stored with consent. |
permissible_purpose |
str |
Purpose tied to the consent. |
expires_at |
datetime |
Expiration timestamp. |
allowed_operator_ids |
tuple[str, ...] |
Deduplicated and sorted allowed operators. |
customer_profile |
dict[str, object] |
Bureau payload context. |
metadata |
`dict[str, object] \ | None` |
revoked_at |
`datetime \ | None` |
Staff Credit Pull Request
src.domain.japan_credit.StaffCreditPullRequest as used in backend/tests/usecase/test_japan_staff_credit.py
| Property | Type | Description |
|---|---|---|
consent_reference |
str |
Consent reference used to authorize the pull. |
operator_id |
str |
Staff operator requesting the report. |
requested_at |
datetime |
Timestamp of the pull request. |
permissible_purpose |
`str \ | None` |
device_fingerprint |
`str \ | None` |
Staff Credit Pull Log
src.domain.japan_credit.StaffCreditPullLog as used in backend/tests/usecase/test_japan_staff_credit.py
| Property | Type | Description |
|---|---|---|
id |
`int \ | None` |
consent_id |
int |
Reference to the stored consent. |
operator_id |
str |
Operator who initiated the pull. |
requested_at |
datetime |
Timestamp of the request. |
status |
str |
succeeded or failed in the visible flow. |
bureau_reference |
`str \ | None` |
response_payload |
dict[str, object] |
Bureau response body stored in the log. |
error_message |
`str \ | None` |
device_fingerprint |
`str \ | None` |
Bureau Credit Report
src.domain.japan_credit.BureauCreditReport as used in backend/tests/usecase/test_japan_staff_credit.py
| Property | Type | Description |
|---|---|---|
reference_id |
str |
Bureau request reference. |
report |
dict[str, object] |
Full bureau report payload. |
summary |
dict[str, object] |
Normalized summary returned to the caller. |
KYC Gateway Contract
src.domain.kyc_gateway.KycGateway as used in backend/src/usecase/kyc.py and the KYC tests
| Method | Description |
|---|---|
create_link_token_id_verification |
Returns the verification bootstrap payload used by the KYC frontend route. |
get_identity_verification_status |
Returns the current verification status for a verification ID. |
Feature Flows
Identity Verification Bootstrap
sequenceDiagram
participant User as User
participant Route as POST api kyc route
participant Backend as Backend API
participant UseCase as generate_link_token_id_verification
participant Gateway as KycGateway
User->>Route: Submit application id
Route->>Route: Validate application id and auth token
Route->>Backend: Load application data
Backend-->>Route: Application payload
Route->>Route: Build prefill payload
Route->>Backend: POST create_link_token_id_verification
Backend->>UseCase: generate_link_token_id_verification
UseCase->>Gateway: create_link_token_id_verification
Gateway-->>UseCase: link token and verification payload
UseCase-->>Backend: verification payload
Backend-->>Route: link token response
Route-->>User: linkToken, verification, applicant
This flow is the primary verification bootstrap path. The frontend route validates the request, resolves the applicant, and forwards the prefill payload to the backend verifier.
Verification Status Lookup
sequenceDiagram
participant User as User
participant Route as GET api kyc verification route
participant Backend as Backend API
participant UseCase as kyc_get_identity_verification_status
participant Gateway as KycGateway
User->>Route: Request verification status
Route->>Backend: GET identity_verification_status verification id
Backend->>UseCase: kyc_get_identity_verification_status
UseCase->>Gateway: get_identity_verification_status
Gateway-->>UseCase: status payload
UseCase-->>Backend: status payload
Backend-->>Route: status payload
Route-->>User: verification object
The route filters backend candidates, retries 404s across candidates, and returns the verification payload in a verification wrapper.
Staff-initiated Bureau Pull
sequenceDiagram
participant Operator as Operator
participant UseCase as perform_staff_credit_pull
participant ConsentRepo as StaffCreditConsentRepository
participant BureauClient as Bureau client
participant LogRepo as StaffCreditPullLogRepository
Operator->>UseCase: StaffCreditPullRequest
UseCase->>ConsentRepo: get_by_reference
ConsentRepo-->>UseCase: StaffCreditConsent
UseCase->>UseCase: Validate expiry, revocation, operator access
UseCase->>BureauClient: request_credit_report
BureauClient-->>UseCase: BureauCreditReport
UseCase->>LogRepo: create StaffCreditPullLog
LogRepo-->>UseCase: persisted log
UseCase-->>Operator: consent, log, summary, data_source, report
This flow is gated by consent state and operator authorization. If the bureau request fails, the log is still persisted and the use case raises BureauRequestError.
Consent Registration
sequenceDiagram
participant Operator as Operator
participant UseCase as register_staff_credit_consent
participant ConsentRepo as StaffCreditConsentRepository
Operator->>UseCase: StaffCreditConsentRequest
UseCase->>UseCase: Check expires_at is in the future
UseCase->>ConsentRepo: create
ConsentRepo-->>UseCase: StaffCreditConsent
UseCase-->>Operator: persisted consent
Consent registration rejects expired records at creation time and normalizes the allowed operator list before persistence.
Error Handling
The feature uses explicit, domain-specific failure modes instead of silent fallthrough.
| Area | Error or Status | Trigger | Effect |
|---|---|---|---|
| KYC route | 400 |
Invalid body or missing applicationId |
Request is rejected before any backend call. |
| KYC route | 401 |
Missing auth token | No application lookup occurs. |
| KYC route | 404 |
Application cannot be found and no load error exists | The caller receives “Application not found.” |
| KYC route | 502 |
Backend load or verification bootstrap failure | The route returns a backend error detail. |
| Verification route | 400 |
Invalid verification ID | The request is rejected immediately. |
| Verification route | 404 |
No verification is found | The caller receives “Verification not found.” |
| Verification route | 502 |
Backend status lookup fails | The error is surfaced as a proxy failure. |
| Consent registration | ConsentExpiredError |
Expiry is in the past or now | Consent is not persisted. |
| Staff pull | ConsentNotFoundError |
Consent reference is absent | Bureau access is blocked. |
| Staff pull | ConsentRevokedError |
Stored consent is revoked | Bureau access is blocked. |
| Staff pull | ConsentExpiredError |
Stored consent is no longer active | Bureau access is blocked. |
| Staff pull | OperatorNotAllowedError |
Operator ID is not in the allowed set | Bureau access is blocked. |
| Staff pull | BureauRequestError |
Bureau client fails | Pull log is persisted and the request fails closed. |
Caching Strategy
The only explicit cache control in the visible flow is the identity status proxy, which fetches backend verification state with cache: "no-store". That makes every status request a fresh backend lookup rather than a cached response.
| Method | Cache Behavior | Notes |
|---|---|---|
GET /api/kyc/[verificationId] |
no-store |
Backend candidate fetches are retried without caching. |
POST /api/kyc |
Not cached | The route is a live POST that creates a new verification bootstrap request. |
POST /create_link_token_id_verification |
Not cached | The backend call is a live verification bootstrap request. |
GET /identity_verification_status/{verification_id} |
Not cached by the frontend proxy | The route is retrieved on demand for current status. |
perform_staff_credit_pull |
N/A | The use case persists a pull log and returns the bureau payload directly. |
Integration Points
frontend/components/underwriting-compliance.tsxis the visible underwriting surface and usesEmailOverlayfor the send action.frontend/app/api/kyc/route.tsorchestrates applicant lookup, prefill construction, and verification bootstrap.frontend/app/api/kyc/[verificationId]/route.tsproxies status lookups to the backend verifier.backend/src/usecase/kyc.pydelegates toKycGatewayfor verification link creation and status retrieval.backend/src/usecase/japan_staff_credit.pyenforces consent, operator access, and bureau request logging.backend/src/ml/credit_pipeline_validation.pydeclares KYC and AML decline flags that stop underwriting before scoring.documents/spinwheel-integration-plan.mddescribes the intended Equifax-based intake and compliance shape for a streamlined identity and credit workflow.backend/tests/usecase/test_japan_staff_credit.pyexercises the consent and operator rules that protect bureau access.
Testing Considerations
The visible tests cover the contract boundaries that matter most for this domain:
test_generate_link_tokenconfirmsgenerate_link_token_id_verificationreturns a link token.test_get_verification_statusconfirmskyc_get_identity_verification_statusreturns a dictionary payload withstatus == "success".test_register_staff_credit_consent_requires_future_expiryverifies that expired consent cannot be registered.test_register_staff_credit_consent_rejects_past_expiryverifies the same policy from the registration path.test_perform_staff_credit_pull_successconfirms the bureau summary is returned and the pull log is written withstatus == "succeeded".test_perform_staff_credit_pull_rejects_unregistered_operatorverifies operator authorization enforcement.test_perform_staff_credit_pull_rejects_expired_consentverifies the consent validity gate before bureau access.TestKycGatewayandMockKycGatewayprovide the gateway contract used by the use case tests.
Key Classes Reference
| Class | Responsibility |
|---|---|
underwriting-compliance.tsx |
Renders the underwriting document preview, supports regeneration, and opens the email overlay. |
route.ts |
Starts identity verification from the applicant ID and returns the link token response. |
route.ts |
Proxies verification status lookups to the backend status endpoint. |
kyc.py |
Passes KYC requests through to KycGateway for link token creation and status retrieval. |
japan_staff_credit.py |
Enforces consent, operator permissions, and bureau logging for staff-initiated credit pulls. |
test_japan_staff_credit.py |
Verifies the consent and operator rules that protect bureau access. |
spinwheel-integration-plan.md |
Describes the planned Equifax-based intake and compliance requirements for streamlined identity verification. |