Architecture and Repository Orientation

Overview

This section maps the repository’s cross-service contract surfaces: the FastAPI routers that expose consent, data, scoring, open-banking, and Japan credit workflows; the Next.js API-route proxies that front applicant data calls; and the customer-facing documents that define the contract language for consent, tokens, snapshots, scoring, versioning, and idempotency.

The repository separates transport concerns from business rules in a way that makes the contract boundary easy to find. backend/src/interface/*.py files define the HTTP surface and model schemas, backend/src/usecase/*.py files implement the rules behind those endpoints, frontend/app/api/**/*.ts proxies and reshapes a subset of backend calls, and documents/*.md files describe the customer-facing expectations that those routes are meant to satisfy.

Architecture Overview

flowchart TB
    Client[Customer or operator client]

    subgraph ContractDocs[Contract Documents]
        LitaConsentDoc[lita consent data api]
        UsApiDoc[us api v1]
        ImplOverview[lita implementation overview]
    end

    subgraph NextJsProxy[Next.js API Routes]
        CoverageRoute[account coverage route]
        TransactionsRoute[transactions route]
    end

    subgraph FastApiBackend[FastAPI Backend]
        LitaRouter[lita endpoints router]
        OpenBankingRouter[open banking endpoints router]
        JapanCreditRouter[japan credit endpoints router]
    end

    subgraph Persistence[Persistence and External Systems]
        LitaRepo[Lita repository]
        OpenBankingRepo[Open banking repository]
        JapanCreditRepo[Japan credit repositories]
        DB[(Database)]
    end

    Client --> NextJsProxy
    Client --> FastApiBackend

    LitaConsentDoc -.-> LitaRouter
    UsApiDoc -.-> FastApiBackend
    ImplOverview -.-> LitaRouter

    CoverageRoute -->|GET account coverage| FastApiBackend
    TransactionsRoute -->|GET transactions| FastApiBackend

    LitaRouter --> LitaRepo
    OpenBankingRouter --> OpenBankingRepo
    JapanCreditRouter --> JapanCreditRepo

    LitaRepo --> DB
    OpenBankingRepo --> DB
    JapanCreditRepo --> DB

Contract Sources and Versioning

[!IMPORTANT] The contract language is split across runtime routes and documents. The implementation routes under /api/lita/v1, /open-banking, and /api/japan-credit are the live FastAPI surfaces, while documents/lita-consent-data-api.md, documents/us-api-v1.md, and documents/lita-implementation-overview.md describe the public contract terms, versioning, and idempotency rules that those surfaces follow.

The repository uses the documents under documents/ as the contract layer and the interface modules under backend/src/interface/ as the runtime layer.

Source Scope Contract rule carried by the source
documents/lita-consent-data-api.md Consent-based data access and scoring Semantic versioning, /api/v1/... contract examples, X-Request-Id idempotency for the customer-hosted scoring API
documents/us-api-v1.md US-specific consent, token, data, feature, webhook, and replay contract /api/v1/us/... namespace, semantic versioning, backward-compatible minor changes, explicit purpose and category rules
documents/lita-implementation-overview.md Implementation behavior reference Maps the public contract to the implemented /api/lita/v1 routes, database-backed consent/token/snapshot/score persistence, request-id caching
backend/src/interface/lita_endpoints.py Live Lita consent, token, data snapshot, and score endpoints Router prefix /api/lita/v1
backend/src/interface/open_banking_endpoints.py Live open-banking consent and Plaid orchestration endpoints Router prefix /open-banking
backend/src/interface/japan_credit_endpoints.py Live staff-initiated Japan credit consent endpoints Router prefix /api/japan-credit

Versioning model

  • documents/lita-consent-data-api.md declares semantic versioning and uses contract examples under /api/v1/....
  • documents/us-api-v1.md declares semantic versioning and explicitly namespaces the US contract under /api/v1/us/.
  • backend/src/interface/lita_endpoints.py implements its live router prefix as /api/lita/v1.
  • The scoring request/response contract in backend/src/interface/lita_endpoints.py carries a version field in the payload and echoes that same version in the response.
  • Idempotency is split by contract surface:
    • documents/lita-consent-data-api.md uses X-Request-Id for the customer-hosted scoring API.
    • backend/src/interface/lita_endpoints.py caches scoring decisions by request_id in the request body.

File: backend/src/interface/lita_endpoints.py

This module is the main Lita contract surface for consent creation, consent lookup, token issuance, data snapshot write/read, and scoring. The router is defined with prefix /api/lita/v1, and token-gated routes depend on _get_consent_and_token, which validates bearer credentials, token status, token expiry, consent status, and consent expiry before allowing snapshot access.

Handler methods

Method Description
register_consent Creates a consent record and maps duplicate consent references to 409 Conflict
get_consent Returns a serialized consent by consent_reference or 404 if missing
issue_token Issues a scoped access token for an existing consent
store_snapshot Stores a versioned data snapshot for the authenticated consent
read_snapshot Returns the latest stored snapshot for the authenticated consent
score_application Computes or returns a cached scoring decision keyed by request_id

Request and response models

File: backend/src/interface/lita_endpoints.py

Property Type Description
consent_reference str External consent identifier
customer_reference str Customer identifier
applicant_reference Optional[str] Optional applicant identifier
country Optional[str] Optional country code
product_type Optional[str] Optional product type
data_categories List[str] Consent-scoped data categories
refresh_permissions List[str] Consent-scoped refresh permissions
expires_at datetime Consent expiry timestamp
refresh_allowed bool Refresh permission flag

File: backend/src/interface/lita_endpoints.py

Property Type Description
consent_reference str Consent identifier
customer_reference str Customer identifier
applicant_reference Optional[str] Applicant identifier
country Optional[str] Country code
product_type Optional[str] Product type
data_categories List[str] Stored data categories
refresh_permissions List[str] Stored refresh permissions
expires_at datetime Consent expiry timestamp
refresh_allowed bool Refresh flag
revoked_at Optional[datetime] Revocation timestamp
created_at Optional[datetime] Creation timestamp
updated_at Optional[datetime] Update timestamp

Token Request

File: backend/src/interface/lita_endpoints.py

Property Type Description
expires_in_days int Token lifetime in days

Token Response

File: backend/src/interface/lita_endpoints.py

Property Type Description
consent_reference str Consent identifier
access_token str Issued bearer token
expires_at datetime Token expiry timestamp

Snapshot Request

File: backend/src/interface/lita_endpoints.py

Property Type Description
version str Snapshot contract version
payload Dict[str, Any] JSON payload persisted as the snapshot body

Snapshot Response

File: backend/src/interface/lita_endpoints.py

Property Type Description
consent_reference str Consent identifier
version str Stored snapshot version
stored_at datetime Snapshot creation timestamp
payload Dict[str, Any] Stored snapshot payload

Applicant

File: backend/src/interface/lita_endpoints.py

Property Type Description
applicant_reference str Applicant reference
country str Applicant country

Score Request

File: backend/src/interface/lita_endpoints.py

Property Type Description
version str Scoring contract version
request_id str Idempotency key for decision caching
applicant Applicant Applicant identity payload
context ScoreContext Scoring context payload
features Dict[str, Any] Feature map used by the scoring rule

Score Response

File: backend/src/interface/lita_endpoints.py

Property Type Description
version str Response version
request_id str Echoed request identifier
score int Numeric score
decision str Final decision
approved_limit int Approved limit returned by the rule
model ModelMetadata Model metadata payload
reasons List[ReasonCode] Reason code list

Endpoint details

{
    "title": "Register Consent",
    "description": "Creates a new consent record with stored categories, refresh permissions, expiry, and optional applicant metadata",
    "method": "POST",
    "baseUrl": "<LitaBackendApiBaseUrl>",
    "endpoint": "/api/lita/v1/consents",
    "headers": [
        {
            "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": "Consent 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    \"created_at\": \"2025-03-31T10:15:00Z\",\n    \"updated_at\": \"2025-03-31T10:15:00Z\"\n}"
        },
        "409": {
            "description": "Consent reference already exists",
            "body": "{\n    \"detail\": \"Consent reference already exists\"\n}"
        }
    }
}
{
    "title": "Get Consent",
    "description": "Returns stored consent metadata by consent reference",
    "method": "GET",
    "baseUrl": "<LitaBackendApiBaseUrl>",
    "endpoint": "/api/lita/v1/consents/{consent_reference}",
    "headers": [],
    "queryParams": [],
    "pathParams": [
        {
            "name": "consent_reference",
            "type": "string",
            "required": true
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Consent found",
            "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    \"created_at\": \"2025-03-31T10:15:00Z\",\n    \"updated_at\": \"2025-03-31T10:15:00Z\"\n}"
        },
        "404": {
            "description": "Consent not found",
            "body": "{\n    \"detail\": \"Consent not found\"\n}"
        }
    }
}

Issue Token

{
    "title": "Issue Token",
    "description": "Issues a bearer access token tied to an existing consent and returns its expiry",
    "method": "POST",
    "baseUrl": "<LitaBackendApiBaseUrl>",
    "endpoint": "/api/lita/v1/consents/{consent_reference}/tokens",
    "headers": [
        {
            "key": "Content-Type",
            "value": "application/json",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "name": "consent_reference",
            "type": "string",
            "required": true
        }
    ],
    "bodyType": "json",
    "requestBody": "{\n    \"expires_in_days\": 30\n}",
    "formData": [],
    "rawBody": "",
    "responses": {
        "201": {
            "description": "Token issued",
            "body": "{\n    \"consent_reference\": \"consent_local_001\",\n    \"access_token\": \"tok_5f6a4f1e9d2a4c0d\",\n    \"expires_at\": \"2025-04-30T10:15:00Z\"\n}"
        },
        "404": {
            "description": "Consent not found",
            "body": "{\n    \"detail\": \"Consent not found\"\n}"
        }
    }
}

Store Snapshot

{
    "title": "Store Snapshot",
    "description": "Stores a versioned JSON snapshot after bearer token and consent validity checks pass",
    "method": "POST",
    "baseUrl": "<LitaBackendApiBaseUrl>",
    "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": "Snapshot stored",
            "body": "{\n    \"consent_reference\": \"consent_local_001\",\n    \"version\": \"1.1\",\n    \"stored_at\": \"2025-03-31T10:20:00Z\",\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}"
        },
        "401": {
            "description": "Bearer token missing, invalid, or expired",
            "body": "{\n    \"detail\": \"Token expired\"\n}"
        },
        "403": {
            "description": "Token revoked or consent revoked or expired",
            "body": "{\n    \"detail\": \"Consent revoked\"\n}"
        },
        "404": {
            "description": "Consent not found or no token-linked consent",
            "body": "{\n    \"detail\": \"Consent not found\"\n}"
        }
    }
}

Get Latest Snapshot

{
    "title": "Get Latest Snapshot",
    "description": "Returns the latest stored snapshot for the authenticated consent",
    "method": "GET",
    "baseUrl": "<LitaBackendApiBaseUrl>",
    "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": "Latest snapshot returned",
            "body": "{\n    \"consent_reference\": \"consent_local_001\",\n    \"version\": \"1.1\",\n    \"stored_at\": \"2025-03-31T10:20:00Z\",\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}"
        },
        "401": {
            "description": "Bearer token missing, invalid, or expired",
            "body": "{\n    \"detail\": \"Invalid access token\"\n}"
        },
        "403": {
            "description": "Token revoked, consent revoked, or consent expired",
            "body": "{\n    \"detail\": \"Consent expired\"\n}"
        },
        "404": {
            "description": "No snapshot exists for the consent",
            "body": "{\n    \"detail\": \"No data available for consent\"\n}"
        }
    }
}

Score Application

{
    "title": "Score Application",
    "description": "Computes or replays a cached scoring decision using the request_id idempotency key",
    "method": "POST",
    "baseUrl": "<LitaBackendApiBaseUrl>",
    "endpoint": "/api/lita/v1/score",
    "headers": [
        {
            "key": "Content-Type",
            "value": "application/json",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [],
    "bodyType": "json",
    "requestBody": "{\n    \"version\": \"1.1\",\n    \"request_id\": \"req-lita-123\",\n    \"applicant\": {\n        \"applicant_reference\": \"app-100\",\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        \"delinquencies_last_24m\": 0,\n        \"monthly_income\": 6000\n    }\n}",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Score computed or replayed from cache",
            "body": "{\n    \"version\": \"1.1\",\n    \"request_id\": \"req-lita-123\",\n    \"score\": 712,\n    \"decision\": \"APPROVE\",\n    \"approved_limit\": 4000,\n    \"model\": {\n        \"name\": \"lita_consent_scoring\",\n        \"version\": \"1.1.0\"\n    },\n    \"reasons\": [\n        {\n            \"code\": \"HIGH_UTILIZATION\"\n        },\n        {\n            \"code\": \"SHORT_HISTORY\"\n        }\n    ]\n}"
        }
    }
}

Contract and execution notes

  • register_consent translates database uniqueness failures into 409 Conflict.
  • get_consent returns 404 when the reference is not found.
  • issue_token uses datetime.now(timezone.utc) + timedelta(days=body.expires_in_days) to compute expiry.
  • _get_consent_and_token enforces the entire credential chain before snapshot operations:
    1. bearer scheme must be present
    2. access token must exist
    3. token must not be revoked
    4. token must not be expired
    5. consent must exist
    6. consent must not be revoked
    7. consent must not be expired
  • score_application first checks repository.get_decision(body.request_id) and returns the stored payload immediately when present.
sequenceDiagram
    participant Client as Client
    participant Router as Lita Router
    participant Repo as Lita Repository
    participant DB as Database

    Client->>Router: POST /api/lita/v1/consents
    Router->>Repo: create_consent
    Repo->>DB: insert consent row
    DB-->>Repo: consent row
    Repo-->>Router: consent model
    Router-->>Client: 201 ConsentResponse

    Client->>Router: POST /api/lita/v1/consents/consent_local_001/tokens
    Router->>Repo: get_consent
    Repo->>DB: select consent row
    DB-->>Repo: consent row
    Repo-->>Router: consent model
    Router->>Repo: issue_access_token
    Repo->>DB: insert token row
    DB-->>Repo: token row
    Repo-->>Router: token model
    Router-->>Client: 201 TokenResponse

    Client->>Router: POST /api/lita/v1/data/snapshots
    Router->>Repo: get_access_token and get_consent
    Repo->>DB: read token and consent rows
    DB-->>Repo: token and consent rows
    Repo-->>Router: token and consent models
    Router->>Repo: record_snapshot
    Repo->>DB: insert snapshot row
    DB-->>Repo: snapshot row
    Repo-->>Router: snapshot model
    Router-->>Client: 201 SnapshotResponse

    Client->>Router: POST /api/lita/v1/score
    Router->>Repo: get_decision request_id
    Repo->>DB: lookup decision row
    DB-->>Repo: cached decision or none
    Repo-->>Router: cached payload or none
    alt cached decision exists
        Router-->>Client: cached ScoreResponse
    else cache miss
        Router->>Router: compute score and reasons
        Router->>Repo: save_decision request_id
        Repo->>DB: insert decision row
        DB-->>Repo: decision row
        Repo-->>Router: saved decision
        Router-->>Client: new ScoreResponse
    end

Open Banking Contract Surface

[!IMPORTANT] The scoring contract uses two different idempotency conventions in the repository: the public customer-hosted scoring spec in documents/lita-consent-data-api.md uses X-Request-Id, while the implemented backend score endpoint caches by request_id in the JSON body. They serve different integration surfaces.

File: backend/src/interface/open_banking_endpoints.py

This module exposes the open-banking consent and Plaid orchestration surface. It uses SQLOpenBankingConsentRepository for persistence, BankGateway for upstream Plaid-style token exchange, and get_current_user_email to gate access to consent operations. The router prefix is /open-banking.

Handler methods

Method Description
create_consent Creates a consent, merges operator access, and stores refresh settings
create_link_token Generates a Plaid link token for an existing consent
exchange_public_token Exchanges a public token and attaches upstream tokens to the consent
list_application_consents Lists application-linked consents visible to the current operator
sync_application_consents Synchronizes application-linked consents and filters them by operator access

Request and response models

File: backend/src/interface/open_banking_endpoints.py

Property Type Description
consent_reference str Consent identifier
customer_reference str Customer identifier
customer_name Optional[str] Customer name
scopes List[str] Granted scopes
expires_at datetime Consent expiry
allowed_operator_ids List[str] Operator allowlist
metadata Optional[Dict[str, Any]] Arbitrary metadata
auto_refresh_enabled bool Auto-refresh flag
auto_refresh_interval_minutes int Refresh interval
application_id Optional[int] Optional linked application

File: backend/src/interface/open_banking_endpoints.py

Property Type Description
consent_reference str Consent identifier
customer_reference str Customer identifier
customer_name Optional[str] Customer name
application_id Optional[int] Linked application id
scopes List[str] Granted scopes
expires_at datetime Expiry timestamp
revoked_at Optional[datetime] Revocation timestamp
allowed_operator_ids List[str] Operator allowlist
metadata Dict[str, Any] Stored metadata
plaid_item_id Optional[str] Upstream item id
auto_refresh_enabled bool Auto-refresh flag
auto_refresh_interval_minutes int Refresh interval
last_refreshed_at Optional[datetime] Last refresh timestamp
created_at Optional[datetime] Creation timestamp
updated_at Optional[datetime] Update timestamp

File: backend/src/interface/open_banking_endpoints.py

Property Type Description
consent_reference str Consent identifier

Endpoint details

{
    "title": "Create Open Banking Consent",
    "description": "Creates an open-banking consent and merges the current operator into the allowlist before persistence",
    "method": "POST",
    "baseUrl": "<OpenBankingApiBaseUrl>",
    "endpoint": "/open-banking/consents",
    "headers": [
        {
            "key": "Content-Type",
            "value": "application/json",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [],
    "bodyType": "json",
    "requestBody": "{\n    \"consent_reference\": \"ob_consent_001\",\n    \"customer_reference\": \"customer_001\",\n    \"customer_name\": \"Jane Doe\",\n    \"scopes\": [\n        \"balances:read\",\n        \"transactions:read\"\n    ],\n    \"expires_at\": \"2025-12-31T00:00:00Z\",\n    \"allowed_operator_ids\": [\n        \"[email protected]\"\n    ],\n    \"metadata\": {\n        \"source\": \"branch\",\n        \"region\": \"JP\"\n    },\n    \"auto_refresh_enabled\": true,\n    \"auto_refresh_interval_minutes\": 720,\n    \"application_id\": 101\n}",
    "formData": [],
    "rawBody": "",
    "responses": {
        "201": {
            "description": "Consent created",
            "body": "{\n    \"consent_reference\": \"ob_consent_001\",\n    \"customer_reference\": \"customer_001\",\n    \"customer_name\": \"Jane Doe\",\n    \"application_id\": 101,\n    \"scopes\": [\n        \"balances:read\",\n        \"transactions:read\"\n    ],\n    \"expires_at\": \"2025-12-31T00:00:00Z\",\n    \"revoked_at\": null,\n    \"allowed_operator_ids\": [\n        \"[email protected]\"\n    ],\n    \"metadata\": {\n        \"source\": \"branch\",\n        \"region\": \"JP\"\n    },\n    \"plaid_item_id\": null,\n    \"auto_refresh_enabled\": true,\n    \"auto_refresh_interval_minutes\": 720,\n    \"last_refreshed_at\": null,\n    \"created_at\": \"2025-03-31T10:25:00Z\",\n    \"updated_at\": \"2025-03-31T10:25:00Z\"\n}"
        },
        "409": {
            "description": "Consent reference already exists",
            "body": "{\n    \"detail\": \"Consent reference already exists\"\n}"
        }
    }
}
{
    "title": "Create Link Token",
    "description": "Creates a Plaid link token for an existing active consent and returns the upstream token payload",
    "method": "POST",
    "baseUrl": "<OpenBankingApiBaseUrl>",
    "endpoint": "/open-banking/link-token",
    "headers": [
        {
            "key": "Content-Type",
            "value": "application/json",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [],
    "bodyType": "json",
    "requestBody": "{\n    \"consent_reference\": \"ob_consent_001\"\n}",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Link token created",
            "body": "{\n    \"link_token\": \"link-token\",\n    \"expiration\": \"2099-01-01T00:00:00Z\"\n}"
        },
        "400": {
            "description": "Consent is not active",
            "body": "{\n    \"detail\": \"Consent is not active\"\n}"
        },
        "403": {
            "description": "Operator is not allowed to view the consent",
            "body": "{\n    \"detail\": \"You are not authorised to view these consents.\"\n}"
        },
        "404": {
            "description": "Consent not found",
            "body": "{\n    \"detail\": \"Consent not found\"\n}"
        },
        "502": {
            "description": "Upstream token creation failed",
            "body": "{\n    \"detail\": \"Failed to create link token\"\n}"
        }
    }
}

Exchange Public Token

{
    "title": "Exchange Public Token",
    "description": "Exchanges a public token and persists the returned access token and item id against the consent",
    "method": "POST",
    "baseUrl": "<OpenBankingApiBaseUrl>",
    "endpoint": "/open-banking/consents/{consent_reference}/exchange",
    "headers": [
        {
            "key": "Content-Type",
            "value": "application/json",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "name": "consent_reference",
            "type": "string",
            "required": true
        }
    ],
    "bodyType": "json",
    "requestBody": "{\n    \"public_token\": \"public-token\",\n    \"consent_expires_at\": \"2025-12-31T00:00:00Z\"\n}",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Public token exchanged",
            "body": "{\n    \"consent_reference\": \"ob_consent_001\",\n    \"customer_reference\": \"customer_001\",\n    \"customer_name\": \"Jane Doe\",\n    \"application_id\": 101,\n    \"scopes\": [\n        \"balances:read\",\n        \"transactions:read\"\n    ],\n    \"expires_at\": \"2025-12-31T00:00:00Z\",\n    \"revoked_at\": null,\n    \"allowed_operator_ids\": [\n        \"[email protected]\"\n    ],\n    \"metadata\": {\n        \"source\": \"branch\",\n        \"region\": \"JP\"\n    },\n    \"plaid_item_id\": \"item-123\",\n    \"auto_refresh_enabled\": true,\n    \"auto_refresh_interval_minutes\": 720,\n    \"last_refreshed_at\": null,\n    \"created_at\": \"2025-03-31T10:25:00Z\",\n    \"updated_at\": \"2025-03-31T10:26:00Z\"\n}"
        },
        "403": {
            "description": "Operator is not allowed to view the consent",
            "body": "{\n    \"detail\": \"You are not authorised to view these consents.\"\n}"
        },
        "404": {
            "description": "Consent not found",
            "body": "{\n    \"detail\": \"Consent not found\"\n}"
        },
        "502": {
            "description": "Upstream exchange failed",
            "body": "{\n    \"detail\": \"Failed to exchange public token\"\n}"
        }
    }
}

List Application Consents

{
    "title": "List Application Consents",
    "description": "Returns all consents linked to an application that are visible to the current operator",
    "method": "GET",
    "baseUrl": "<OpenBankingApiBaseUrl>",
    "endpoint": "/open-banking/applications/{application_id}/consents",
    "headers": [],
    "queryParams": [],
    "pathParams": [
        {
            "name": "application_id",
            "type": "integer",
            "required": true
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Consent list returned",
            "body": "[\n    {\n        \"consent_reference\": \"ob_consent_001\",\n        \"customer_reference\": \"customer_001\",\n        \"customer_name\": \"Jane Doe\",\n        \"application_id\": 101,\n        \"scopes\": [\n            \"balances:read\",\n            \"transactions:read\"\n        ],\n        \"expires_at\": \"2025-12-31T00:00:00Z\",\n        \"revoked_at\": null,\n        \"allowed_operator_ids\": [\n            \"[email protected]\"\n        ],\n        \"metadata\": {\n            \"source\": \"branch\",\n            \"region\": \"JP\"\n        },\n        \"plaid_item_id\": \"item-123\",\n        \"auto_refresh_enabled\": true,\n        \"auto_refresh_interval_minutes\": 720,\n        \"last_refreshed_at\": null,\n        \"created_at\": \"2025-03-31T10:25:00Z\",\n        \"updated_at\": \"2025-03-31T10:26:00Z\"\n    }\n]"
        },
        "403": {
            "description": "No consent is visible to the current operator",
            "body": "{\n    \"detail\": \"You are not authorised to view these consents.\"\n}"
        }
    }
}

Sync Application Consents

{
    "title": "Sync Application Consents",
    "description": "Synchronizes application-linked consents and returns only those visible to the current operator",
    "method": "POST",
    "baseUrl": "<OpenBankingApiBaseUrl>",
    "endpoint": "/open-banking/applications/{application_id}/consents/sync",
    "headers": [
        {
            "key": "Content-Type",
            "value": "application/json",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "name": "application_id",
            "type": "integer",
            "required": true
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Synced consent list returned",
            "body": "[\n    {\n        \"consent_reference\": \"ob_consent_001\",\n        \"customer_reference\": \"customer_001\",\n        \"customer_name\": \"Jane Doe\",\n        \"application_id\": 101,\n        \"scopes\": [\n            \"balances:read\",\n            \"transactions:read\"\n        ],\n        \"expires_at\": \"2025-12-31T00:00:00Z\",\n        \"revoked_at\": null,\n        \"allowed_operator_ids\": [\n            \"[email protected]\"\n        ],\n        \"metadata\": {\n            \"source\": \"branch\",\n            \"region\": \"JP\"\n        },\n        \"plaid_item_id\": \"item-123\",\n        \"auto_refresh_enabled\": true,\n        \"auto_refresh_interval_minutes\": 720,\n        \"last_refreshed_at\": null,\n        \"created_at\": \"2025-03-31T10:25:00Z\",\n        \"updated_at\": \"2025-03-31T10:26:00Z\"\n    }\n]"
        },
        "403": {
            "description": "No consent is visible to the current operator",
            "body": "{\n    \"detail\": \"You are not authorised to view these consents.\"\n}"
        }
    }
}

Contract and execution notes

  • create_consent appends current_user_email to the allowed operators before persistence and de-duplicates the final list.
  • create_link_token fails fast when the consent is missing, inactive, or not visible to the current operator.
  • exchange_public_token persists both the upstream access token and the item id through attach_plaid_tokens.
  • list_application_consents and sync_application_consents filter the repository result set by consent.ensure_operator_allowed(current_user_email) and return 403 when nothing remains visible.

Japan Credit Staff Pull Surface

File: backend/src/interface/japan_credit_endpoints.py

This module exposes the Japan staff-initiated credit consent contract. It uses SQLJapanCreditConsentRepository for persistence, perform_staff_credit_pull and related use cases for workflow orchestration, and returns JapanCreditConsentResponse from the shared schema module.

Handler methods

Method Description
create_consent Registers a staff-initiated credit consent
revoke_consent Revokes a staff-initiated credit consent
credit_pulls Endpoint is declared and routed for staff credit pulls

Request and response models

File: backend/src/interface/schemas.py

Property Type Description
id int Internal identifier
consent_reference str Consent reference
customer_reference str Customer reference
customer_name str Customer name
permissible_purpose str Bureau purpose string
expires_at datetime Consent expiry
revoked_at Optional[datetime] Revocation timestamp
allowed_operator_ids List[str] Operator allowlist
created_at Optional[datetime] Creation timestamp
updated_at Optional[datetime] Update timestamp

Endpoint details

{
    "title": "Create Japan Credit Consent",
    "description": "Registers a staff-initiated credit consent for Japan bureau workflows",
    "method": "POST",
    "baseUrl": "<JapanCreditApiBaseUrl>",
    "endpoint": "/api/japan-credit/consents",
    "headers": [
        {
            "key": "Content-Type",
            "value": "application/json",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [],
    "bodyType": "json",
    "requestBody": "{\n    \"consent_reference\": \"jp_consent_001\",\n    \"customer_reference\": \"customer_001\",\n    \"customer_name\": \"Yuki Tanaka\",\n    \"permissible_purpose\": \"TENANCY_SCREENING\",\n    \"expires_at\": \"2025-12-31T00:00:00Z\",\n    \"allowed_operator_ids\": [\n        \"[email protected]\"\n    ],\n    \"customer_profile\": {\n        \"country\": \"JP\",\n        \"branch\": \"Tokyo\"\n    },\n    \"metadata\": {\n        \"source\": \"branch\",\n        \"channel\": \"dashboard\"\n    }\n}",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Consent created",
            "body": "{\n    \"id\": 123,\n    \"consent_reference\": \"jp_consent_001\",\n    \"customer_reference\": \"customer_001\",\n    \"customer_name\": \"Yuki Tanaka\",\n    \"permissible_purpose\": \"TENANCY_SCREENING\",\n    \"expires_at\": \"2025-12-31T00:00:00Z\",\n    \"revoked_at\": null,\n    \"allowed_operator_ids\": [\n        \"[email protected]\"\n    ],\n    \"created_at\": \"2025-03-31T10:30:00Z\",\n    \"updated_at\": \"2025-03-31T10:30:00Z\"\n}"
        }
    }
}
{
    "title": "Revoke Japan Credit Consent",
    "description": "Revokes a Japan credit consent and returns the updated consent record",
    "method": "POST",
    "baseUrl": "<JapanCreditApiBaseUrl>",
    "endpoint": "/api/japan-credit/consents/{consent_reference}/revoke",
    "headers": [
        {
            "key": "Content-Type",
            "value": "application/json",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "name": "consent_reference",
            "type": "string",
            "required": true
        }
    ],
    "bodyType": "json",
    "requestBody": "{\n    \"revoked_at\": \"2025-03-31T10:45:00Z\"\n}",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Consent revoked",
            "body": "{\n    \"id\": 123,\n    \"consent_reference\": \"jp_consent_001\",\n    \"customer_reference\": \"customer_001\",\n    \"customer_name\": \"Yuki Tanaka\",\n    \"permissible_purpose\": \"TENANCY_SCREENING\",\n    \"expires_at\": \"2025-12-31T00:00:00Z\",\n    \"revoked_at\": \"2025-03-31T10:45:00Z\",\n    \"allowed_operator_ids\": [\n        \"[email protected]\"\n    ],\n    \"created_at\": \"2025-03-31T10:30:00Z\",\n    \"updated_at\": \"2025-03-31T10:45:00Z\"\n}"
        },
        "404": {
            "description": "Consent not found",
            "body": "{\n    \"detail\": \"Consent not found\"\n}"
        }
    }
}

Contract and execution notes

  • create_consent normalizes expires_at to timezone-aware UTC before calling register_staff_credit_consent.
  • revoke_consent accepts an optional revoked_at field and normalizes it to UTC when provided.
  • The file declares the /credit-pulls route for staff credit pulls, aligning the router prefix with the operator-led workflow described in the Japan credit documentation set.

Next.js Applicant API Route Proxies

The frontend app/api routes are transport adapters. They do not own the business rules for account coverage or transaction history; instead, they fan out to backend APIs, merge backend and locally stored application data when needed, and return a browser-friendly payload.

Account Coverage Proxy

File: frontend/app/api/v1/applicants/[id]/account-coverage/route.ts

This route validates the applicant id, resolves candidate backend base URLs from the request headers, and calls the backend applicant account-coverage endpoint with cache: "no-store". If one backend candidate returns 404, the route continues to the next candidate; backend request failures are translated into a Next.js JSON error response.

Handler method

Method Description
GET Proxies the account coverage request to the backend and returns the first successful result

Response shape

The route relays the backend schema documented in documents/account-coverage.md:

Property Type Description
application_id int Application id
status string complete, incomplete, or unknown
reported_accounts int Submitted accounts
detected_accounts int Detected accounts
missing_accounts int Missing accounts
coverage_ratio `float \ null`
details list Per-connection results
errors list Errors raised while detecting coverage

Endpoint details

{
    "title": "Get Applicant Account Coverage",
    "description": "Frontend proxy that forwards account coverage requests to the backend applicant endpoint",
    "method": "GET",
    "baseUrl": "<FrontendAppBaseUrl>",
    "endpoint": "/api/v1/applicants/{id}/account-coverage",
    "headers": [],
    "queryParams": [],
    "pathParams": [
        {
            "name": "id",
            "type": "string",
            "required": true
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Coverage result returned from backend",
            "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}"
        },
        "400": {
            "description": "Invalid applicant id",
            "body": "{\n    \"detail\": \"Invalid applicant id.\"\n}"
        },
        "500": {
            "description": "Backend API URL is not configured",
            "body": "{\n    \"detail\": \"Backend API URL is not configured. Set NEXT_PUBLIC_BACKEND_API_URL or BACKEND_API_URL.\"\n}"
        },
        "502": {
            "description": "Backend API could not be reached",
            "body": "{\n    \"detail\": \"Failed to reach backend API. ...\"\n}"
        }
    }
}

Transactions Proxy

File: frontend/app/api/v1/applicants/[id]/transactions/route.ts

This route is the most opinionated proxy in the frontend API layer. It validates the applicant id and optional date range, tries a direct backend fetch, falls back to the backend list endpoint, then merges local stored applications and extracts transactions from metadata and connected_accounts. The final response is filtered by start_date and end_date and returned only when at least one transaction exists.

Handler method

Method Description
GET Collects transactions from backend and stored sources, filters them by date, and returns the result set

Response shape

The route returns a transaction bundle with these fields:

Property Type Description
applicant_id `int \ string`
start_date `string \ null`
end_date `string \ null`
transactions PaymentHistoryTransactionSummary[] Sorted transaction summaries

A PaymentHistoryTransactionSummary entry is constructed from the fields the parser accepts:

Property Type Description
amount number Numeric transaction amount
date string Transaction date string
currency_code `string \ null`
status `string \ null`
account_name `string \ null`
connection_name `string \ null`
description `string \ null`
categories `string[] \ null`
provider `string \ null`
metadata Record<string, unknown> Original parsed record

Endpoint details

{
    "title": "Get Applicant Transactions",
    "description": "Frontend route that merges backend, stored, and connected-account transactions for an applicant",
    "method": "GET",
    "baseUrl": "<FrontendAppBaseUrl>",
    "endpoint": "/api/v1/applicants/{id}/transactions",
    "headers": [],
    "queryParams": [
        {
            "name": "start_date",
            "type": "string",
            "required": false
        },
        {
            "name": "end_date",
            "type": "string",
            "required": false
        }
    ],
    "pathParams": [
        {
            "name": "id",
            "type": "string",
            "required": true
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Transaction list returned",
            "body": "{\n    \"applicant_id\": 123,\n    \"start_date\": \"2025-01-01\",\n    \"end_date\": \"2025-01-31\",\n    \"transactions\": [\n        {\n            \"amount\": -20,\n            \"date\": \"2025-01-15\",\n            \"currency_code\": \"GBP\",\n            \"status\": \"booked\",\n            \"account_name\": \"Primary checking\",\n            \"connection_name\": \"Example Bank\",\n            \"description\": \"Coffee\",\n            \"categories\": [\n                \"food\",\n                \"housing\"\n            ],\n            \"provider\": \"plaid\",\n            \"metadata\": {\n                \"amount\": -20,\n                \"date\": \"2025-01-15\",\n                \"description\": \"Coffee\"\n            }\n        }\n    ]\n}"
        },
        "400": {
            "description": "Invalid applicant id or invalid query parameters",
            "body": "{\n    \"detail\": \"Invalid query parameters.\"\n}"
        },
        "404": {
            "description": "Application not found or no transaction history available",
            "body": "{\n    \"detail\": \"Application not found.\"\n}"
        },
        "502": {
            "description": "Backend lookup failed",
            "body": "{\n    \"detail\": \"Failed to reach backend API. ...\"\n}"
        }
    }
}

Proxy execution notes

  • The route uses cache: "no-store" on backend fetches.
  • It accepts an applicant id from the URL, normalizes it with zod, and rejects invalid identifiers with 400.
  • It first tries a direct backend lookup, then a backend list lookup, then local stored data, and finally matches by collectApplicationIdentifiers.
  • If no transactions remain after date filtering, it returns 404 with a message that the applicant has no history yet.

Transaction proxy flow

sequenceDiagram
    participant Browser as Browser
    participant Route as Next Js Route
    participant Backend as Backend API
    participant Store as Local Stored Applications

    Browser->>Route: GET /api/v1/applicants/id/transactions
    Route->>Route: validate id and query params
    Route->>Backend: direct applicant fetch
    alt direct match found
        Backend-->>Route: application
    else direct match missing
        Backend-->>Route: 404 or 422
    end

    Route->>Backend: list applicants
    Backend-->>Route: applications list

    Route->>Store: read stored applications
    Store-->>Route: stored records

    Route->>Route: collect identifiers and extract transactions
    alt transactions found
        Route-->>Browser: 200 transaction bundle
    else no transactions found
        Route-->>Browser: 404 no history
    end

Internal Documentation Sources

The repository’s documentation files are not just guides; they are the contract source for the API surface.

documents/lita-consent-data-api.md

  • Defines the consent-based data access and scoring contract.
  • States that all data access requires explicit user consent.
  • Describes customer-issued access credentials tied to a consent grant.
  • Declares semantic versioning.
  • Uses X-Request-Id for scoring idempotency on the customer-hosted scoring API.
  • Shows the customer-hosted scoring request and response shape with version, request_id, score, decision, approved_limit, model, and reasons.

documents/us-api-v1.md

  • Defines the US-specific consent, connection, token, data, feature, replay, and webhook contract.
  • Namespaces the live contract under /api/v1/us/.
  • Describes consent purpose enforcement, data-category restrictions, and connection states.
  • States that backward-compatible changes increment minor versions.
  • Requires Authorization: Bearer <PARTNER_TOKEN> and X-Request-Id in the partner-to-Lita header contract shown in the document.
  • Defines error-code expectations such as PURPOSE_NOT_ALLOWED, CATEGORY_NOT_ALLOWED, CONSENT_REVOKED, and REAUTH_REQUIRED.

documents/lita-implementation-overview.md

  • Bridges the public contract to the current implementation.
  • Confirms that the live routes are mounted under /api/lita/v1.
  • Describes the persistence model names:
    • LitaConsentModel
    • LitaAccessTokenModel
    • LitaDataSnapshotModel
    • LitaScoreDecisionModel
  • States that token-gated routes enforce bearer authentication and revocation checks.
  • Confirms idempotent scoring by request_id.
  • Confirms that snapshots store JSON payloads with a version value.

Contract-to-code mapping

Document Runtime file it maps to What the mapping controls
documents/lita-consent-data-api.md backend/src/interface/lita_endpoints.py Consent lifecycle, data snapshots, scoring payload expectations
documents/lita-implementation-overview.md backend/src/interface/lita_endpoints.py Actual route prefix, revocation checks, cached scoring behavior
documents/us-api-v1.md backend/src/interface/open_banking_endpoints.py and the broader US contract layer Versioning, consent scope, data access, replay and webhook expectations

State and Validation Semantics

  • Consent records are accepted only when consent_reference is unique.
  • Tokens are accepted only when present, not revoked, and not expired.
  • Consent-linked data snapshots are accepted only when both the token and the consent are valid.
  • Snapshot retrieval returns the most recent snapshot for the consent.

Scoring state

  • request_id is the cache key for prior decisions.
  • A cached decision is returned as-is without recomputing score or reasons.
  • A new score is saved after computation so future identical request_id submissions replay the same payload.

Open banking state

  • Consents are filtered by operator allowlist before being returned.
  • Consent linkage to a housing application is preserved through the repository and use-case layer.
  • The Plaid token exchange path writes the returned access token and item id back onto the consent record.

Japan credit state

  • Consent creation normalizes expiry timestamps.
  • Consent revocation writes the revocation timestamp back into the stored response model.
  • The operator allowlist is preserved in the response payload.

Error Handling

The API surfaces use explicit HTTP responses rather than silent fallthrough.

Surface Condition Response
Lita consent creation Duplicate consent_reference 409 Conflict
Lita consent lookup Missing consent 404 Not Found
Lita token-gated routes Missing, invalid, revoked, or expired token 401 or 403 depending on the failure point
Lita token-gated routes Missing, revoked, or expired consent 403 or 404 depending on the failure point
Lita snapshot read No snapshot exists 404 Not Found
Open banking consent creation Duplicate consent reference 409 Conflict
Open banking link token / exchange Missing consent, unauthorized operator, inactive consent, or upstream failure 404, 403, 400, or 502
Japan credit revoke Missing consent 404 Not Found
Frontend account coverage proxy Invalid id or backend URL misconfiguration 400 or 500
Frontend transactions proxy Invalid id, missing history, or backend failure 400, 404, or 502

Testing Considerations

The repository includes tests and smoke flows that exercise the same contract boundaries documented above.

  • backend/tests/interface/test_lita_endpoints.py
    • consent creation
    • token issuance
    • snapshot write/read
    • scoring idempotency
  • backend/tests/interface/test_open_banking_endpoints.py
    • open banking consent creation
    • Plaid link token creation
    • public token exchange
    • auto refresh and manual refresh flows
  • documents/lita-testing-guide.md
    • manual curl flow for consent, token, snapshot, and score
    • repeated score call to confirm idempotency
  • documents/account-coverage.md
    • account coverage endpoint contract and response shape

Integration Points

  • backend/src/main.py registers the interface routers that expose the public HTTP surfaces.
  • backend/src/interface/lita_endpoints.py depends on src.infra.mysql.lita_repository.LitaRepository.
  • backend/src/interface/open_banking_endpoints.py depends on BankGateway and SQLOpenBankingConsentRepository.
  • backend/src/interface/japan_credit_endpoints.py depends on Japan credit repositories and the shared schema module.
  • frontend/app/api/v1/applicants/[id]/account-coverage/route.ts and frontend/app/api/v1/applicants/[id]/transactions/route.ts proxy browser requests to backend APIs and merge backend and stored data where needed.

Key Classes Reference

Class Responsibility
backend/src/interface/lita_endpoints.py Lita consent, token, snapshot, and scoring contract models and handlers
backend/src/interface/open_banking_endpoints.py Open banking consent and Plaid orchestration contract models and handlers
backend/src/interface/japan_credit_endpoints.py Japan staff-initiated credit consent handlers
backend/src/interface/schemas.py Shared Japan credit response schema
frontend/app/api/v1/applicants/[id]/account-coverage/route.ts Account coverage proxy route
frontend/app/api/v1/applicants/[id]/transactions/route.ts Transaction aggregation proxy route
documents/lita-consent-data-api.md Customer-facing consent and scoring contract
documents/us-api-v1.md US-specific customer-facing contract
documents/lita-implementation-overview.md Implementation-oriented contract reference