Engineering Reference, Workspace Memory, and Supporting Documents
Overview
This section groups the documents/ guides that engineers use to understand the platform contract, implementation behavior, and operational workflows. The guides span customer-facing API specifications, internal implementation notes, partner integration plans, local testing instructions, deployment runbooks, and vertex pipeline verification.
For Dwilar/lita-ehousing, these documents are the canonical reference layer around the FastAPI backend, the Next.js frontend proxy routes, the Salt Edge and Plaid integrations, and the deployment and validation scripts that keep the housing application and applicant-financing flows consistent across environments.
Document Map by Audience and System Area
| Audience | System area | Canonical documents | What the guide is for |
|---|---|---|---|
| External API consumers | Consent, scoring, and data access | documents/lita-consent-data-api.md, documents/us-api-v1.md |
Defines the customer-facing contracts, headers, payloads, and allowed behaviors |
| Product and backend engineers | Applicant coverage and matching | documents/account-coverage.md |
Explains the account coverage check, response shape, and detection logic |
| Backend and frontend engineers | Platform behavior and feature gating | documents/lita-implementation-overview.md, documents/feature-availability.md |
Records how the implementation behaves today and which UI behaviors are derived from backend payloads |
| Integration engineers | Partner workflows | documents/sothebys-agent-initiated-credit-access.md, documents/sothebys-open-banking-refresh.md, documents/spinwheel-integration-plan.md |
Describes partner-specific operating models and integration assumptions |
| Developers | Local setup and debugging | documents/development.md |
Explains how to run the stack locally, seed test users, and inspect application data |
| Release engineers | Deployment and stability | documents/deployment.md, documents/vertex_ai_verification.md |
Describes CI/CD, production rollout, schema application, and Vertex AI verification |
| QA and automation | API and workflow testing | documents/lita-testing-guide.md |
Provides smoke tests and end-to-end checks for the consent and scoring flows |
Documentation Relationship Overview
flowchart TB
subgraph ExternalContracts[External contract guides]
AccountCoverage[account coverage md]
LitaSpec[lita consent data api md]
UsApi[us api v1 md]
end
subgraph WorkspaceMemory[Workspace memory and implementation notes]
ImplOverview[lita implementation overview md]
FeatureAvailability[feature availability md]
SothebysAgent[sothebys agent initiated credit access md]
SothebysOpenBanking[sothebys open banking refresh md]
Spinwheel[spinwheel integration plan md]
end
subgraph Runbooks[Testing and operations runbooks]
Development[development md]
LitaTesting[lita testing guide md]
Deployment[deployment md]
VertexAI[vertex ai verification md]
end
AccountCoverage --> ImplOverview
LitaSpec --> ImplOverview
UsApi --> ImplOverview
FeatureAvailability --> Development
ImplOverview --> LitaTesting
ImplOverview --> Deployment
Development --> LitaTesting
Deployment --> VertexAI
SothebysAgent --> Deployment
SothebysOpenBanking --> Deployment
Spinwheel --> Development
External Contract Guides
Account Coverage Inference
documents/account-coverage.md
This guide defines the applicant account coverage check used to compare what an applicant reported with what Plaid detects for the same access token. It is both a customer-review aid and a fraud-detection support tool.
It ties the contract to the backend implementation at backend/src/interface/http_endpoints.py (get_application_account_coverage), the response schema in backend/src/interface/schemas.py (AccountCoverageResponse, AccountCoverageDetail), and the coverage logic in backend/src/usecase/account_detection.py (infer_account_coverage).
Account Coverage Response Shape
| Property | Type | Description |
|---|---|---|
application_id |
int |
Applicant or application identifier |
status |
string |
complete, incomplete, or unknown |
reported_accounts |
int |
Count of submitted accounts |
detected_accounts |
int |
Count of accounts Plaid detects |
missing_accounts |
int |
Count of detected accounts missing from submission |
coverage_ratio |
`float \ | null` |
details |
list |
Per-connection coverage records |
errors |
list |
Error strings collected during evaluation |
Account Coverage Detail Shape
| Property | Type | Description |
|---|---|---|
connection_name |
`string \ | null` |
institution_name |
`string \ | null` |
reported_accounts |
int |
Submitted account count for the connection |
detected_accounts |
int |
Plaid-detected account count for the connection |
missing_accounts |
int |
Count of detected accounts not submitted |
status |
string |
complete, incomplete, or error |
Get Application Account Coverage
{
"title": "Get Application Account Coverage",
"description": "Returns the applicant account coverage comparison for a single application",
"method": "GET",
"baseUrl": "<FrontendBaseUrl>",
"endpoint": "/api/v1/applicants/{application_id}/account-coverage",
"headers": [],
"queryParams": [],
"pathParams": [
{
"key": "application_id",
"type": "string",
"required": true,
"description": "Applicant or application identifier"
}
],
"bodyType": "none",
"requestBody": "",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Success",
"body": "{\n \"application_id\": 123,\n \"status\": \"incomplete\",\n \"reported_accounts\": 2,\n \"detected_accounts\": 3,\n \"missing_accounts\": 1,\n \"coverage_ratio\": 0.67,\n \"details\": [\n {\n \"connection_name\": \"Example Bank\",\n \"institution_name\": \"Example Bank\",\n \"reported_accounts\": 2,\n \"detected_accounts\": 3,\n \"missing_accounts\": 1,\n \"status\": \"incomplete\"\n }\n ],\n \"errors\": []\n}"
}
}
}
[!NOTE]
backend/src/usecase/account_detection.pycomputescoverage_ratioasreported_total / detected_total, whiledocuments/account-coverage.mddescribes it as a0–1ratio. That means the implemented ratio can exceed1when reported accounts outnumber detected accounts.
Lita Consent Based Data Access and Scoring API
documents/lita-consent-data-api.md
This guide is the customer-facing specification for long-lived, consent-scoped financial-data access and scoring. It defines the partner authentication model, consent lifecycle, data snapshot storage, and the client-hosted scoring call.
The guide aligns with the implementation overview in documents/lita-implementation-overview.md, which maps these contracts to backend/src/interface/lita_endpoints.py and the repository models used by the backend.
Consent Lifecycle
Register Consent
{
"title": "Register Consent",
"description": "Creates a consent grant for consent-scoped data access",
"method": "POST",
"baseUrl": "<LitaConsentDataApiBaseUrl>",
"endpoint": "/api/lita/v1/consents",
"headers": [
{
"key": "Authorization",
"value": "Bearer <CLIENT_API_KEY>",
"required": true
},
{
"key": "X-Request-Id",
"value": "<uuid>",
"required": true
},
{
"key": "Content-Type",
"value": "application/json",
"required": true
}
],
"queryParams": [],
"pathParams": [],
"bodyType": "json",
"requestBody": "{\n \"consent_reference\": \"consent_local_001\",\n \"customer_reference\": \"customer_abc\",\n \"applicant_reference\": \"applicant_xyz\",\n \"country\": \"GB\",\n \"product_type\": \"CREDIT_CARD\",\n \"data_categories\": [\n \"balances\",\n \"transactions\"\n ],\n \"refresh_permissions\": [\n \"balances:read\",\n \"transactions:read\"\n ],\n \"expires_at\": \"2030-01-01T00:00:00Z\",\n \"refresh_allowed\": true\n}",
"formData": [],
"rawBody": "",
"responses": {
"201": {
"description": "Created",
"body": "{\n \"consent_reference\": \"consent_local_001\",\n \"customer_reference\": \"customer_abc\",\n \"applicant_reference\": \"applicant_xyz\",\n \"country\": \"GB\",\n \"product_type\": \"CREDIT_CARD\",\n \"data_categories\": [\n \"balances\",\n \"transactions\"\n ],\n \"refresh_permissions\": [\n \"balances:read\",\n \"transactions:read\"\n ],\n \"expires_at\": \"2030-01-01T00:00:00Z\",\n \"refresh_allowed\": true,\n \"revoked_at\": null\n}"
}
}
}
Fetch Consent
{
"title": "Fetch Consent",
"description": "Returns the stored consent metadata for a consent reference",
"method": "GET",
"baseUrl": "<LitaConsentDataApiBaseUrl>",
"endpoint": "/api/lita/v1/consents/{consent_reference}",
"headers": [
{
"key": "Authorization",
"value": "Bearer <CLIENT_API_KEY>",
"required": true
},
{
"key": "X-Request-Id",
"value": "<uuid>",
"required": true
}
],
"queryParams": [],
"pathParams": [
{
"key": "consent_reference",
"type": "string",
"required": true,
"description": "Consent reference"
}
],
"bodyType": "none",
"requestBody": "",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Success",
"body": "{\n \"consent_reference\": \"consent_local_001\",\n \"customer_reference\": \"customer_abc\",\n \"applicant_reference\": \"applicant_xyz\",\n \"country\": \"GB\",\n \"product_type\": \"CREDIT_CARD\",\n \"data_categories\": [\n \"balances\",\n \"transactions\"\n ],\n \"refresh_permissions\": [\n \"balances:read\",\n \"transactions:read\"\n ],\n \"expires_at\": \"2030-01-01T00:00:00Z\",\n \"refresh_allowed\": true,\n \"revoked_at\": null\n}"
}
}
}
Issue Consent Token
{
"title": "Issue Consent Token",
"description": "Creates an access token tied to a consent grant",
"method": "POST",
"baseUrl": "<LitaConsentDataApiBaseUrl>",
"endpoint": "/api/lita/v1/consents/{consent_reference}/tokens",
"headers": [
{
"key": "Authorization",
"value": "Bearer <CLIENT_API_KEY>",
"required": true
},
{
"key": "X-Request-Id",
"value": "<uuid>",
"required": true
},
{
"key": "Content-Type",
"value": "application/json",
"required": true
}
],
"queryParams": [],
"pathParams": [
{
"key": "consent_reference",
"type": "string",
"required": true,
"description": "Consent reference"
}
],
"bodyType": "json",
"requestBody": "{\n \"expires_in_days\": 30\n}",
"formData": [],
"rawBody": "",
"responses": {
"201": {
"description": "Created",
"body": "{\n \"access_token\": \"tok_demo_001\",\n \"expires_at\": \"2030-02-01T00:00:00Z\",\n \"token_type\": \"bearer\",\n \"consent_reference\": \"consent_local_001\"\n}"
}
}
}
Data Snapshots
Store Data Snapshot
{
"title": "Store Data Snapshot",
"description": "Stores a versioned JSON snapshot under a valid bearer token",
"method": "POST",
"baseUrl": "<LitaConsentDataApiBaseUrl>",
"endpoint": "/api/lita/v1/data/snapshots",
"headers": [
{
"key": "Authorization",
"value": "Bearer <ACCESS_TOKEN>",
"required": true
},
{
"key": "Content-Type",
"value": "application/json",
"required": true
}
],
"queryParams": [],
"pathParams": [],
"bodyType": "json",
"requestBody": "{\n \"version\": \"1.1\",\n \"payload\": {\n \"balances\": {\n \"available\": 1500,\n \"currency\": \"GBP\"\n },\n \"transactions\": [\n {\n \"amount\": -20,\n \"description\": \"Coffee\"\n },\n {\n \"amount\": -50,\n \"description\": \"Groceries\"\n }\n ]\n }\n}",
"formData": [],
"rawBody": "",
"responses": {
"201": {
"description": "Created",
"body": "{\n \"consent_reference\": \"consent_local_001\",\n \"version\": \"1.1\",\n \"created_at\": \"2030-01-01T12:00:00Z\"\n}"
}
}
}
Get Latest Snapshot
{
"title": "Get Latest Snapshot",
"description": "Returns the most recent data snapshot for the consent",
"method": "GET",
"baseUrl": "<LitaConsentDataApiBaseUrl>",
"endpoint": "/api/lita/v1/data/snapshots/latest",
"headers": [
{
"key": "Authorization",
"value": "Bearer <ACCESS_TOKEN>",
"required": true
}
],
"queryParams": [],
"pathParams": [],
"bodyType": "none",
"requestBody": "",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Success",
"body": "{\n \"consent_reference\": \"consent_local_001\",\n \"version\": \"1.1\",\n \"payload\": {\n \"balances\": {\n \"available\": 1500,\n \"currency\": \"GBP\"\n },\n \"transactions\": [\n {\n \"amount\": -20,\n \"description\": \"Coffee\"\n },\n {\n \"amount\": -50,\n \"description\": \"Groceries\"\n }\n ]\n },\n \"created_at\": \"2030-01-01T12:00:00Z\"\n}"
}
}
}
Scoring
Score Request
{
"title": "Score Request",
"description": "Runs the client-hosted scoring workflow against feature data",
"method": "POST",
"baseUrl": "<CustomerDomain>",
"endpoint": "/api/lita/v1/score",
"headers": [
{
"key": "Authorization",
"value": "Bearer <CLIENT_API_KEY>",
"required": true
},
{
"key": "X-Request-Id",
"value": "<uuid>",
"required": true
},
{
"key": "Content-Type",
"value": "application/json",
"required": true
}
],
"queryParams": [],
"pathParams": [],
"bodyType": "json",
"requestBody": "{\n \"version\": \"1.1\",\n \"request_id\": \"3b6e3d0e-387f-4de3-9e8a-34cfa1b65d2f\",\n \"applicant\": {\n \"applicant_reference\": \"app_123456\",\n \"country\": \"GB\"\n },\n \"context\": {\n \"product_type\": \"CREDIT_CARD\"\n },\n \"features\": {\n \"credit_utilization\": 0.65,\n \"debt_to_income_ratio\": 0.4,\n \"credit_history_months\": 30,\n \"monthly_income\": 6000\n }\n}",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Success",
"body": "{\n \"version\": \"1.1\",\n \"request_id\": \"3b6e3d0e-387f-4de3-9e8a-34cfa1b65d2f\",\n \"score\": 712,\n \"decision\": \"APPROVE\",\n \"approved_limit\": 4000,\n \"model\": {\n \"name\": \"credit_card_v2\",\n \"version\": \"2.3.1\"\n },\n \"reasons\": [\n {\n \"code\": \"HIGH_UTILIZATION\"\n },\n {\n \"code\": \"SHORT_HISTORY\"\n }\n ]\n}"
}
}
}
United States API
documents/us-api-v1.md
This guide defines the United States-specific contract for consent, token exchange, data access, feature computation, and partner webhooks. It is the canonical external contract for the US open-banking and scoring surface.
US Consent APIs
Create Consent
{
"title": "Create US Consent",
"description": "Creates a new US consent and returns a user authorization link",
"method": "POST",
"baseUrl": "<UsApiBaseUrl>",
"endpoint": "/api/v1/us/consents",
"headers": [
{
"key": "Authorization",
"value": "Bearer <PARTNER_TOKEN>",
"required": true
},
{
"key": "X-Request-Id",
"value": "<uuid>",
"required": true
},
{
"key": "Content-Type",
"value": "application/json",
"required": true
}
],
"queryParams": [],
"pathParams": [],
"bodyType": "json",
"requestBody": "{\n \"user\": {\n \"country\": \"US\"\n },\n \"purpose\": \"LENDING_UNDERWRITING\",\n \"data_categories\": [\n \"ACCOUNTS\",\n \"BALANCES\"\n ],\n \"refresh_permissions\": {\n \"enabled\": true,\n \"max_refresh_per_day\": 4\n }\n}",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Success",
"body": "{\n \"consent_id\": \"consent_123\",\n \"status\": \"PENDING_USER_ACTION\",\n \"expires_at\": \"2024-12-31T00:00:00Z\",\n \"auth\": {\n \"link_url\": \"https://link.lita.com/us/consent_123\"\n }\n}"
}
}
}
Consent Receipt
{
"title": "Consent Receipt",
"description": "Returns consent metadata for audits and compliance reviews",
"method": "GET",
"baseUrl": "<UsApiBaseUrl>",
"endpoint": "/api/v1/us/consents/{consent_id}/receipt",
"headers": [
{
"key": "Authorization",
"value": "Bearer <PARTNER_TOKEN>",
"required": true
},
{
"key": "X-Request-Id",
"value": "<uuid>",
"required": true
}
],
"queryParams": [],
"pathParams": [
{
"key": "consent_id",
"type": "string",
"required": true,
"description": "Consent identifier"
}
],
"bodyType": "none",
"requestBody": "",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Success",
"body": "{\n \"consent_id\": \"consent_123\",\n \"purpose\": \"LENDING_UNDERWRITING\",\n \"data_categories\": [\n \"ACCOUNTS\",\n \"BALANCES\"\n ],\n \"disclosure_version\": \"1.0\",\n \"timestamp\": \"2024-01-01T00:00:00Z\",\n \"status\": \"ACTIVE\"\n}"
}
}
}
Revoke Consent
{
"title": "Revoke US Consent",
"description": "Immediately revokes access tokens and active connections for a consent",
"method": "POST",
"baseUrl": "<UsApiBaseUrl>",
"endpoint": "/api/v1/us/consents/{consent_id}/revoke",
"headers": [
{
"key": "Authorization",
"value": "Bearer <PARTNER_TOKEN>",
"required": true
},
{
"key": "X-Request-Id",
"value": "<uuid>",
"required": true
}
],
"queryParams": [],
"pathParams": [
{
"key": "consent_id",
"type": "string",
"required": true,
"description": "Consent identifier"
}
],
"bodyType": "none",
"requestBody": "",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Success",
"body": "{\n \"consent_id\": \"consent_123\",\n \"status\": \"REVOKED\"\n}"
}
}
}
Token Management
Exchange Token
{
"title": "Exchange Token",
"description": "Exchanges user authorization for access and refresh credentials",
"method": "POST",
"baseUrl": "<UsApiBaseUrl>",
"endpoint": "/api/v1/us/consents/{consent_id}/token",
"headers": [
{
"key": "Authorization",
"value": "Bearer <PARTNER_TOKEN>",
"required": true
},
{
"key": "X-Request-Id",
"value": "<uuid>",
"required": true
},
{
"key": "Content-Type",
"value": "application/json",
"required": true
}
],
"queryParams": [],
"pathParams": [
{
"key": "consent_id",
"type": "string",
"required": true,
"description": "Consent identifier"
}
],
"bodyType": "json",
"requestBody": "{\n \"link_token\": \"link_abc123\"\n}",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Success",
"body": "{\n \"consent_id\": \"consent_123\",\n \"access_token\": \"access_123\",\n \"refresh_token\": \"refresh_123\",\n \"token_type\": \"bearer\",\n \"expires_at\": \"2024-01-01T01:00:00Z\"\n}"
}
}
}
Refresh Token
{
"title": "Refresh Token",
"description": "Issues a new access token within refresh limits",
"method": "POST",
"baseUrl": "<UsApiBaseUrl>",
"endpoint": "/api/v1/us/tokens/refresh",
"headers": [
{
"key": "Authorization",
"value": "Bearer <PARTNER_TOKEN>",
"required": true
},
{
"key": "X-Request-Id",
"value": "<uuid>",
"required": true
},
{
"key": "Content-Type",
"value": "application/json",
"required": true
}
],
"queryParams": [],
"pathParams": [],
"bodyType": "json",
"requestBody": "{\n \"refresh_token\": \"refresh_123\"\n}",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Success",
"body": "{\n \"access_token\": \"access_456\",\n \"refresh_token\": \"refresh_456\",\n \"token_type\": \"bearer\",\n \"expires_at\": \"2024-01-01T02:00:00Z\"\n}"
}
}
}
Token Introspection
{
"title": "Token Introspection",
"description": "Returns token validity, scope, and expiration",
"method": "POST",
"baseUrl": "<UsApiBaseUrl>",
"endpoint": "/api/v1/us/tokens/introspect",
"headers": [
{
"key": "Authorization",
"value": "Bearer <PARTNER_TOKEN>",
"required": true
},
{
"key": "X-Request-Id",
"value": "<uuid>",
"required": true
},
{
"key": "Content-Type",
"value": "application/json",
"required": true
}
],
"queryParams": [],
"pathParams": [],
"bodyType": "json",
"requestBody": "{\n \"access_token\": \"access_123\"\n}",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Success",
"body": "{\n \"active\": true,\n \"consent_id\": \"consent_123\",\n \"scope\": [\n \"ACCOUNTS\",\n \"BALANCES\"\n ],\n \"expires_at\": \"2024-01-01T01:00:00Z\"\n}"
}
}
}
Data Access APIs
Get Accounts
{
"title": "Get Accounts",
"description": "Returns tokenized bank accounts",
"method": "GET",
"baseUrl": "<UsApiBaseUrl>",
"endpoint": "/api/v1/us/data/accounts",
"headers": [
{
"key": "Authorization",
"value": "Bearer <ACCESS_TOKEN>",
"required": true
}
],
"queryParams": [],
"pathParams": [],
"bodyType": "none",
"requestBody": "",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Success",
"body": "[\n {\n \"account_id\": \"acct_1\",\n \"mask\": \"1234\",\n \"institution\": \"Example Bank\",\n \"type\": \"checking\"\n }\n]"
}
}
}
Get Balances
{
"title": "Get Balances",
"description": "Returns available and current balances",
"method": "GET",
"baseUrl": "<UsApiBaseUrl>",
"endpoint": "/api/v1/us/data/balances",
"headers": [
{
"key": "Authorization",
"value": "Bearer <ACCESS_TOKEN>",
"required": true
}
],
"queryParams": [],
"pathParams": [],
"bodyType": "none",
"requestBody": "",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Success",
"body": "[\n {\n \"account_id\": \"acct_1\",\n \"available\": 1500,\n \"current\": 1525,\n \"currency\": \"USD\"\n }\n]"
}
}
}
Get Transactions
{
"title": "Get Transactions",
"description": "Returns historical transactions in the requested range",
"method": "GET",
"baseUrl": "<UsApiBaseUrl>",
"endpoint": "/api/v1/us/data/transactions",
"headers": [
{
"key": "Authorization",
"value": "Bearer <ACCESS_TOKEN>",
"required": true
}
],
"queryParams": [],
"pathParams": [],
"bodyType": "none",
"requestBody": "",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Success",
"body": "[\n {\n \"transaction_id\": \"txn_1\",\n \"date\": \"2024-01-01\",\n \"amount\": -20,\n \"currency\": \"USD\",\n \"description\": \"Coffee\",\n \"account_id\": \"acct_1\"\n }\n]"
}
}
}
Get Transactions Sync
{
"title": "Get Transactions Sync",
"description": "Returns cursor-based incremental transaction changes",
"method": "GET",
"baseUrl": "<UsApiBaseUrl>",
"endpoint": "/api/v1/us/data/transactions/sync",
"headers": [
{
"key": "Authorization",
"value": "Bearer <ACCESS_TOKEN>",
"required": true
}
],
"queryParams": [],
"pathParams": [],
"bodyType": "none",
"requestBody": "",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Success",
"body": "{\n \"added\": [\n {\n \"transaction_id\": \"txn_2\",\n \"date\": \"2024-01-02\",\n \"amount\": -35,\n \"currency\": \"USD\",\n \"description\": \"Groceries\",\n \"account_id\": \"acct_1\"\n }\n ],\n \"modified\": [],\n \"removed\": [],\n \"next_cursor\": \"cursor_002\"\n}"
}
}
}
Get Income
{
"title": "Get Income",
"description": "Returns provider reported or inferred income and discloses the method used",
"method": "GET",
"baseUrl": "<UsApiBaseUrl>",
"endpoint": "/api/v1/us/data/income",
"headers": [
{
"key": "Authorization",
"value": "Bearer <ACCESS_TOKEN>",
"required": true
}
],
"queryParams": [],
"pathParams": [],
"bodyType": "none",
"requestBody": "",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Success",
"body": "{\n \"provider_income\": 6000,\n \"inferred_income\": 5900,\n \"method\": \"inferred\"\n}"
}
}
}
Feature Computation
Compute Features
{
"title": "Compute Features",
"description": "Computes normalized cashflow features and produces an evidence snapshot",
"method": "POST",
"baseUrl": "<UsApiBaseUrl>",
"endpoint": "/api/v1/us/features/compute",
"headers": [
{
"key": "Authorization",
"value": "Bearer <ACCESS_TOKEN>",
"required": true
},
{
"key": "Content-Type",
"value": "application/json",
"required": true
}
],
"queryParams": [],
"pathParams": [],
"bodyType": "json",
"requestBody": "{\n \"version\": \"US_CASHFLOW_V1\",\n \"data\": {\n \"balances\": [\n {\n \"account_id\": \"acct_1\",\n \"available\": 1500,\n \"current\": 1525,\n \"currency\": \"USD\"\n }\n ],\n \"transactions\": [\n {\n \"transaction_id\": \"txn_1\",\n \"date\": \"2024-01-01\",\n \"amount\": -20,\n \"currency\": \"USD\",\n \"description\": \"Coffee\",\n \"account_id\": \"acct_1\"\n }\n ]\n }\n}",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Success",
"body": "{\n \"version\": \"US_CASHFLOW_V1\",\n \"evidence_ref\": \"evidence_123\",\n \"features\": {\n \"monthly_income\": 6000,\n \"cashflow_volatility\": 0.18,\n \"average_balance\": 1525\n }\n}"
}
}
}
Decision Replay
{
"title": "Decision Replay",
"description": "Replays a scoring decision from a stored evidence reference",
"method": "POST",
"baseUrl": "<UsApiBaseUrl>",
"endpoint": "/api/v1/us/decisions/replay",
"headers": [
{
"key": "Authorization",
"value": "Bearer <ACCESS_TOKEN>",
"required": true
},
{
"key": "Content-Type",
"value": "application/json",
"required": true
}
],
"queryParams": [],
"pathParams": [],
"bodyType": "json",
"requestBody": "{\n \"evidence_ref\": \"evidence_123\"\n}",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Success",
"body": "{\n \"evidence_ref\": \"evidence_123\",\n \"score\": 712,\n \"decision\": \"APPROVE\",\n \"reasons\": [\n \"LOW_RISK\"\n ]\n}"
}
}
}
Webhooks
Register Webhook
{
"title": "Register Webhook",
"description": "Registers a webhook subscription for US events",
"method": "POST",
"baseUrl": "<UsApiBaseUrl>",
"endpoint": "/api/v1/us/webhooks",
"headers": [
{
"key": "Authorization",
"value": "Bearer <PARTNER_TOKEN>",
"required": true
},
{
"key": "X-Request-Id",
"value": "<uuid>",
"required": true
},
{
"key": "Content-Type",
"value": "application/json",
"required": true
}
],
"queryParams": [],
"pathParams": [],
"bodyType": "json",
"requestBody": "{\n \"url\": \"https://example.com/webhooks/lita\",\n \"events\": [\n \"consent_activated\",\n \"consent_revoked\"\n ]\n}",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Success",
"body": "{\n \"webhook_id\": \"wh_123\",\n \"url\": \"https://example.com/webhooks/lita\",\n \"events\": [\n \"consent_activated\",\n \"consent_revoked\"\n ],\n \"secret\": \"whsec_...\",\n \"status\": \"ACTIVE\"\n}"
}
}
}
List Webhooks
{
"title": "List Webhooks",
"description": "Returns all registered webhook subscriptions",
"method": "GET",
"baseUrl": "<UsApiBaseUrl>",
"endpoint": "/api/v1/us/webhooks",
"headers": [
{
"key": "Authorization",
"value": "Bearer <PARTNER_TOKEN>",
"required": true
},
{
"key": "X-Request-Id",
"value": "<uuid>",
"required": true
}
],
"queryParams": [],
"pathParams": [],
"bodyType": "none",
"requestBody": "",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Success",
"body": "[\n {\n \"webhook_id\": \"wh_123\",\n \"url\": \"https://example.com/webhooks/lita\",\n \"events\": [\n \"consent_activated\",\n \"consent_revoked\"\n ],\n \"secret\": \"whsec_...\",\n \"status\": \"ACTIVE\"\n }\n]"
}
}
}
Deactivate Webhook
{
"title": "Deactivate Webhook",
"description": "Disables a webhook subscription",
"method": "DELETE",
"baseUrl": "<UsApiBaseUrl>",
"endpoint": "/api/v1/us/webhooks/{webhook_id}",
"headers": [
{
"key": "Authorization",
"value": "Bearer <PARTNER_TOKEN>",
"required": true
},
{
"key": "X-Request-Id",
"value": "<uuid>",
"required": true
}
],
"queryParams": [],
"pathParams": [
{
"key": "webhook_id",
"type": "string",
"required": true,
"description": "Webhook identifier"
}
],
"bodyType": "none",
"requestBody": "",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Success",
"body": "{\n \"webhook_id\": \"wh_123\",\n \"status\": \"INACTIVE\"\n}"
}
}
}
Internal Workspace Memory
Implementation Overview
documents/lita-implementation-overview.md
This guide is the internal memory layer for the Lita consent and scoring system. It summarizes the current implementation under backend/src/interface/lita_endpoints.py with prefix /api/lita/v1, and it maps those routes to persistence through backend/src/infra/mysql/lita_repository.py.
It records the implemented behavior engineers need to preserve:
- consent creation with uniqueness enforcement on
consent_reference - token issuance and token-gated routes with revocation checks
- snapshot storage and latest-snapshot retrieval
- deterministic scoring with idempotency on
request_id - repository-backed persistence through
LitaConsentModel,LitaAccessTokenModel,LitaDataSnapshotModel, andLitaScoreDecisionModel
The guide also captures the error model used by the routes: 404 for missing resources, 409 for duplicate consent creation, and 401 or 403 for expired or revoked credentials depending on context.
Feature Availability Notes
documents/feature-availability.md
This document records user-visible behavior that is derived from backend payloads. The key note is that the dashboard derives connected-account type labels from the backend response, and when no type is present the UI falls back to account.
This is a practical compatibility note for the dashboard data contract: backend responses do not need to include a hard-coded label such as Trifecta for the UI to render a valid type.
Partner Integration Plans
Sotheby’s Agent Initiated Credit Access
documents/sothebys-agent-initiated-credit-access.md
This is a business and security playbook for staff-initiated credit pulls in Japan. It is not an implementation guide for an existing endpoint; it documents the intended workflow:
- explicit consent capture
- staff-initiated trigger from the dashboard or API
- bureau orchestration
- real-time results and audit persistence
The document also captures the compliance controls expected for APPI, including time-bound consent, operator audit trails, restricted dashboard access, and revocation handling.
Sotheby’s Open Banking Refresh Workflow
documents/sothebys-open-banking-refresh.md
This guide clarifies the operational reality of open-banking refreshes with Plaid. It records that the customer must authenticate at least once, after which staff can trigger refreshes during the active consent window.
The workflow documented here uses:
POST /open-banking/consentsPOST /open-banking/link-tokenPOST /open-banking/refresh
The purpose is to align operator expectations with provider rules and refresh limits, while keeping the customer session as close to hands-off as the provider permits.
Spinwheel Integration Plan
documents/spinwheel-integration-plan.md
This is the planning guide for a Spinwheel-like intake experience built from Equifax services. It centers on the existing /phone-application flow and the proposed backend orchestration for:
- Equifax Instant ID
- Equifax OneView Consumer Credit Report
- normalized credit profile mapping
- consent and audit capture
- rollout planning and pricing research
It is a product and technical discovery document, not an implemented contract.
Testing and Operations Runbooks
Local Development
documents/development.md
This guide describes the local developer stack and the application data flow that matters during implementation:
- start the stack with Docker Compose
- verify
GET http://localhost:3000/api/v1/applications - use
ENABLE_REMOTE_APPLICATIONSorNEXT_PUBLIC_ENABLE_REMOTE_APPLICATIONSto opt into remote data - persist local submissions through
APPLICATIONS_DATA_FILE - seed reviewer workflows with the documented realtor test accounts
It also records the roles of REALTOR_EMAILS, ADMIN_EMAILS, and DEFAULT_REALTOR_PASSWORD for local reviewer and admin testing.
Deployment
documents/deployment.md
This guide is the production runbook for the backend and frontend containers. It describes:
- GitHub Actions build and deploy flow
- Artifact Registry image publishing
- Compute Engine deployment via
docker-compose - Fastly in front of the Google Cloud HTTPS Load Balancer
- schema application through
platform/database/apply_schema.sh - pre-launch stability checks and post-deployment verification
The guide also records the deployment environment variables:
VITE_BACKEND_API_URLALLOWED_ORIGINSAPPLICATIONS_DATA_GCS_BUCKETAPPLICATIONS_DATA_GCS_OBJECT
Lita Testing Guide
documents/lita-testing-guide.md
This guide is the quickest path to verify the consent, token, snapshot, and scoring behavior locally. It includes:
pytest backend/tests/interface/test_lita_endpoints.py -q./scripts/lita_smoke_test.sh- a manual curl sequence for consent creation, token issuance, snapshot storage, snapshot retrieval, and idempotent scoring
It is the operational reference for validating the backend/src/interface/lita_endpoints.py surface against the SQLite fallback and the repository-backed behavior.
Vertex AI Verification Guide
documents/vertex_ai_verification.md
This guide is the operational reference for the TransUnion training and deployment pipeline under backend/src/vertex_ai_pipeline. It explains:
- how to set deployment-level env files
- how to authenticate to Artifact Registry
- how to build and push the training image
- how to run the orchestrator through Compose
- how to verify the runtime scoring path on the deployed Vertex endpoint
It also documents the key runtime controls used by the pipeline, including TRAIN_IMAGE_URI, PROJECT_ID, REGION, MODEL_OUTPUT_DIR, TRAIN_MACHINE_TYPE, DEPLOY_MACHINE_TYPE, VERTEX_CREDIT_ENDPOINT_NAME, and VERTEX_CREDIT_ENDPOINT_ID.
Feature Flows
Account Coverage Review Flow
sequenceDiagram
participant R as Reviewer
participant P as Frontend Proxy
participant B as Backend Coverage Route
participant U as infer_account_coverage
participant G as Plaid Gateway
participant UI as Dashboard
R->>P: Open applicant coverage view
P->>B: GET account coverage request
B->>U: infer_account_coverage
U->>G: get_account_balances token
G-->>U: detected accounts
U-->>B: AccountCoverageResult
B-->>P: coverage response
P-->>UI: render status and details
UI-->>R: show complete or incomplete coverage
The guide in documents/account-coverage.md describes the human-readable contract, while backend/src/usecase/account_detection.py performs the comparison and composes the per-connection detail.
Consent to Scoring Flow
sequenceDiagram
participant C as Customer
participant A as API Client
participant L as Lita Consent API
participant R as Repository
participant S as Score API
participant D as Data Snapshot Store
A->>L: POST consent
L->>R: persist consent record
R-->>L: consent stored
A->>L: POST consent token
L->>R: persist access token
R-->>L: token returned
A->>L: POST data snapshot
L->>D: store snapshot
D-->>L: snapshot created
A->>S: POST score request
S-->>A: score and decision
C-->>A: review result
The customer-facing contract is described in documents/lita-consent-data-api.md, and the implementation mapping is captured in documents/lita-implementation-overview.md.
Local Test and Deployment Validation Flow
sequenceDiagram
participant E as Engineer
participant T as Lita Smoke Test
participant D as Deployment Runbook
participant V as Vertex Verification
participant G as GitHub Actions
participant C as Compute Engine
E->>T: Run local smoke test
T-->>E: consent and scoring validation
E->>D: Follow deployment steps
D-->>G: Build and push images
G-->>C: Deploy containers
E->>V: Verify Vertex pipeline
V-->>E: training and runtime checks
This sequence reflects how the testing and deployment guides are used together: documents/lita-testing-guide.md validates the API surface, documents/deployment.md handles release mechanics, and documents/vertex_ai_verification.md validates the ML pipeline path.
State and Caching Notes
Contracted States
AccountCoverageResult.status:unknown,incomplete,completeAccountCoverageDetail.status:complete,incomplete,error- US connection status:
ACTIVE,REAUTH_REQUIRED,DEGRADED,DISCONNECTED - Webhook status:
ACTIVE,INACTIVE - Salt Edge v6 unsupported-country response: surfaced as
422withcode: unsupported_country
Caching and State Keys
Salt Edge customer cache
backend/src/interface/saltedge_endpoints.py maintains an in-memory customer cache:
- cache object:
_customer_cache - lock:
_customer_cache_lock - TTL:
CUSTOMER_CACHE_TTL_SECONDS = 60
The cache stores the customer list returned by Salt Edge and refreshes after the TTL elapses. The lock prevents concurrent refreshes from issuing duplicate Salt Edge calls.
Frontend local storage keys referenced by the guides
frontend/app/application/review/page.tsx uses:
CONNECTED_ACCOUNTS_STORAGE_KEYCONNECTED_ACCOUNTS_VERSION_KEYCONNECTED_ACCOUNTS_STORAGE_VERSIONSALTEDGE_CUSTOMER_STORAGE_KEYCONNECTION_CATEGORY_STORAGE_KEYUSER_FORM_DATA_STORAGE_KEYAPPLICATION_REFERENCE_STORAGE_KEY
The review flow clears these values when the stored version changes or when the connected-account payload no longer passes cleanup rules.
Integration Points
Plaidfor account detection and balance comparison in the coverage guideSalt Edgefor customer, connection, and connect-session workflowsFastAPIfor backend HTTP contracts and route implementationNext.jsAPI routes for frontend proxying and local request mediationMySQLand repository-backed persistence for Lita consent and scoring recordsGitHub Actions,Docker Compose,Artifact Registry,Compute Engine,Fastly, and theGoogle Cloud HTTPS Load Balancerfor deploymentVertex AIfor the TransUnion training, deploy, and runtime verification flow
Testing Considerations
documents/lita-testing-guide.mdis the canonical smoke-test reference for consent, token, snapshot, and scoring behavior.documents/development.mddefines the local data flow for/api/v1/applications, including JSON-file persistence and remote-data opt-in.documents/deployment.mdincludes the pre-launch stability workflow and the schema application step needed before production verification.documents/vertex_ai_verification.mddefines both the repeatable smoke check and the runtime endpoint verification for the credit-scoring path.documents/account-coverage.mdshould be checked againstbackend/src/usecase/account_detection.pywhenever coverage status or ratio behavior changes.documents/lita-implementation-overview.mdshould be treated as the source of truth for consent lifecycle, snapshot, and scoring semantics.
Key Classes Reference
| Class | Responsibility |
|---|---|
account-coverage.md |
Defines the applicant account coverage contract and response semantics |
lita-consent-data-api.md |
Defines the customer-facing consent, snapshot, and scoring API |
us-api-v1.md |
Defines the United States consent, data access, and webhook contract |
lita-implementation-overview.md |
Summarizes the implemented Lita route behavior and persistence model |
feature-availability.md |
Records UI behavior derived from backend payloads |
sothebys-agent-initiated-credit-access.md |
Documents the APPI-oriented staff initiated credit pull plan |
sothebys-open-banking-refresh.md |
Documents the Plaid refresh workflow and operator constraints |
spinwheel-integration-plan.md |
Documents the Equifax discovery and intake plan |
development.md |
Documents local setup, test accounts, and application-data behavior |
deployment.md |
Documents release, deployment, and stability procedures |
lita-testing-guide.md |
Documents local API smoke tests and regression checks |
vertex_ai_verification.md |
Documents the Vertex AI training and runtime verification workflow |