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.py computes coverage_ratio as reported_total / detected_total, while documents/account-coverage.md describes it as a 0–1 ratio. That means the implemented ratio can exceed 1 when reported accounts outnumber detected accounts.


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.

{
    "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}"
        }
    }
}
{
    "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}"
        }
    }
}
{
    "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.

{
    "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}"
        }
    }
}
{
    "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}"
        }
    }
}
{
    "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, and LitaScoreDecisionModel

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/consents
  • POST /open-banking/link-token
  • POST /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_APPLICATIONS or NEXT_PUBLIC_ENABLE_REMOTE_APPLICATIONS to 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_URL
  • ALLOWED_ORIGINS
  • APPLICATIONS_DATA_GCS_BUCKET
  • APPLICATIONS_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.

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, complete
  • AccountCoverageDetail.status: complete, incomplete, error
  • US connection status: ACTIVE, REAUTH_REQUIRED, DEGRADED, DISCONNECTED
  • Webhook status: ACTIVE, INACTIVE
  • Salt Edge v6 unsupported-country response: surfaced as 422 with code: 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_KEY
  • CONNECTED_ACCOUNTS_VERSION_KEY
  • CONNECTED_ACCOUNTS_STORAGE_VERSION
  • SALTEDGE_CUSTOMER_STORAGE_KEY
  • CONNECTION_CATEGORY_STORAGE_KEY
  • USER_FORM_DATA_STORAGE_KEY
  • APPLICATION_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

  • Plaid for account detection and balance comparison in the coverage guide
  • Salt Edge for customer, connection, and connect-session workflows
  • FastAPI for backend HTTP contracts and route implementation
  • Next.js API routes for frontend proxying and local request mediation
  • MySQL and repository-backed persistence for Lita consent and scoring records
  • GitHub Actions, Docker Compose, Artifact Registry, Compute Engine, Fastly, and the Google Cloud HTTPS Load Balancer for deployment
  • Vertex AI for the TransUnion training, deploy, and runtime verification flow

Testing Considerations

  • documents/lita-testing-guide.md is the canonical smoke-test reference for consent, token, snapshot, and scoring behavior.
  • documents/development.md defines the local data flow for /api/v1/applications, including JSON-file persistence and remote-data opt-in.
  • documents/deployment.md includes the pre-launch stability workflow and the schema application step needed before production verification.
  • documents/vertex_ai_verification.md defines both the repeatable smoke check and the runtime endpoint verification for the credit-scoring path.
  • documents/account-coverage.md should be checked against backend/src/usecase/account_detection.py whenever coverage status or ratio behavior changes.
  • documents/lita-implementation-overview.md should 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