Consent Management Domain

Overview

The consent-data API in this repo is the customer-facing entry point for Lita’s consent lifecycle, token issuance, consent-scoped snapshot persistence, and scoring idempotency. The FastAPI router in backend/src/interface/lita_endpoints.py exposes the full flow under /api/lita/v1, while backend/src/models/consent.py keeps the legacy ConsentGrantModel import path available for consent-related code.

For a customer, the flow is simple: create a consent, exchange that consent for an access token, store and later read a versioned data snapshot, and submit score requests that are deduplicated by request_id. The local verification guide ties those pieces together with pytest, uvicorn, curl, and the SQLite fallback used when DATABASE_URL is not set.

Architecture Overview

flowchart TB
    subgraph APILayer[API Layer]
        Router[Lita endpoints router]
        ConsentCreate[register_consent]
        ConsentRead[get_consent]
        TokenIssue[issue_token]
        SnapshotWrite[store_snapshot]
        SnapshotRead[read_snapshot]
        ScoreRun[score_application]
        Guard[_get_consent_and_token]
        Serialise[_serialise_consent]
    end

    subgraph BusinessRules[Request Lifecycle Rules]
        ConsentUTC[Consent expiry UTC normalisation]
        TokenUTC[Token expiry UTC validation]
        SnapshotVersion[Versioned snapshot write]
        DecisionCache[Decision cache by request_id]
    end

    subgraph PersistenceLayer[Persistence Layer]
        Repo[LitaRepository]
        DB[(SQLite or MySQL)]
    end

    subgraph LocalVerification[Local Verification]
        Pytest[pytest backend tests]
        Uvicorn[uvicorn src.main app]
        Curl[curl smoke flow]
        Smoke[scripts lita_smoke_test.sh]
    end

    Router --> ConsentCreate
    Router --> ConsentRead
    Router --> TokenIssue
    Router --> SnapshotWrite
    Router --> SnapshotRead
    Router --> ScoreRun

    ConsentCreate --> ConsentUTC
    TokenIssue --> ConsentUTC
    SnapshotWrite --> Guard
    SnapshotRead --> Guard
    SnapshotWrite --> SnapshotVersion
    SnapshotRead --> SnapshotVersion
    ScoreRun --> DecisionCache

    ConsentCreate --> Repo
    ConsentRead --> Repo
    TokenIssue --> Repo
    Guard --> Repo
    SnapshotWrite --> Repo
    SnapshotRead --> Repo
    ScoreRun --> Repo
    Repo --> DB

    Pytest --> Router
    Uvicorn --> Router
    Curl --> Router
    Smoke --> Pytest
    Smoke --> Uvicorn
    Smoke --> Curl

Component Structure

1. API Layer

backend/src/interface/lita_endpoints.py

This file contains the router, request and response models, the bearer-token guard, and the endpoint handlers for consent creation, token issuance, snapshot persistence, snapshot retrieval, and scoring.

Public methods
Method Description
register_consent Creates a consent record and returns the serialised consent response.
get_consent Fetches a consent by consent_reference and serialises it for the API response.
issue_token Issues an access token for an existing consent.
store_snapshot Persists a versioned data snapshot under an authenticated consent.
read_snapshot Reads the latest snapshot for an authenticated consent.
score_application Computes or reuses a score decision keyed by request_id.
Request and response helpers
Method Description
_serialise_consent Converts a repository model into ConsentResponse, decoding JSON text fields for data_categories and refresh_permissions.
_get_consent_and_token Validates the bearer token, resolves the linked consent, and enforces token and consent expiry and revocation checks.
get_repository Builds a LitaRepository from the injected SQLAlchemy session.
Dependency injection and runtime guards
Type Description
get_db Supplies the SQLAlchemy Session used to build LitaRepository.
LitaRepository Handles consent, token, snapshot, and score persistence.
HTTPBearer Extracts the bearer token for snapshot write and read endpoints.
IntegrityError Converts duplicate consent creation into 409 Conflict.

2. Request and Response Models

ConsentRequest

backend/src/interface/lita_endpoints.py

Property Type Description
consent_reference str Unique consent identifier supplied by the caller.
customer_reference str Customer-side reference for the consent.
applicant_reference Optional[str] Optional applicant reference.
country Optional[str] Optional country code attached to the consent.
product_type Optional[str] Optional product type associated with the consent.
data_categories List[str] Declared data categories to persist with the consent.
refresh_permissions List[str] Refresh permissions stored with the consent.
expires_at datetime Consent expiry timestamp.
refresh_allowed bool Flag controlling whether refresh is allowed.

ConsentResponse

backend/src/interface/lita_endpoints.py

Property Type Description
consent_reference str Consent identifier returned to the caller.
customer_reference str Customer-side consent reference.
applicant_reference Optional[str] Applicant reference echoed from storage.
country Optional[str] Country associated with the consent.
product_type Optional[str] Product type associated with the consent.
data_categories List[str] Decoded consent data categories.
refresh_permissions List[str] Decoded refresh permissions.
expires_at datetime Stored consent expiry timestamp.
refresh_allowed bool Refresh permission flag.
revoked_at Optional[datetime] Revocation timestamp when present.
created_at Optional[datetime] Creation timestamp when present.
updated_at Optional[datetime] Last update timestamp when present.

TokenRequest

backend/src/interface/lita_endpoints.py

Property Type Description
expires_in_days int Lifetime requested for the issued access token.

TokenResponse

backend/src/interface/lita_endpoints.py

Property Type Description
consent_reference str Consent reference used for issuance.
access_token str Issued access token value.
expires_at datetime Token expiry timestamp.

SnapshotRequest

backend/src/interface/lita_endpoints.py

Property Type Description
version str Snapshot version label, defaults to 1.1.
payload Dict[str, Any] Arbitrary consent-scoped snapshot payload.

SnapshotResponse

backend/src/interface/lita_endpoints.py

Property Type Description
consent_reference str Consent reference that owns the snapshot.
version str Snapshot version label.
stored_at datetime Timestamp returned from persistence.
payload Dict[str, Any] Snapshot payload returned from storage or request echo.

Applicant

backend/src/interface/lita_endpoints.py

Property Type Description
applicant_reference str Applicant reference supplied with the score request.
country str Applicant country.

ScoreContext

backend/src/interface/lita_endpoints.py

Property Type Description
product_type str Product type used by scoring logic.

ModelMetadata

backend/src/interface/lita_endpoints.py

Property Type Description
name str Model name returned in the score response.
version str Model version returned in the score response.

ScoreRequest

backend/src/interface/lita_endpoints.py

Property Type Description
version str Request version.
request_id str Idempotency key used by the scoring repository cache.
applicant Applicant Applicant identity payload.
context ScoreContext Scoring context payload.
features Dict[str, Any] Feature map used by _compute_score.

ScoreResponse

backend/src/interface/lita_endpoints.py

Property Type Description
version str Response version.
request_id str Echoed request id.
score int Computed numeric score.
decision str Final decision string.
approved_limit int Approved limit returned by the score logic.
model ModelMetadata Model metadata for the response.
reasons List[ReasonCode] Score reason codes returned by the scorer.

ReasonCode

The implementation uses ReasonCode in ScoreResponse.reasons. The response examples and testing flow show reason objects with a code field such as HIGH_UTILIZATION and SHORT_HISTORY.

3. Persistence and Model Alias

backend/src/models/consent.py

This module preserves the legacy consent model import path.

Export Description
ConsentGrantModel Alias imported from src.infra.mysql.models.ConsentGrantModel.

4. Endpoint Integration

{
    "title": "Register Consent",
    "description": "Creates a consent record with data categories, refresh permissions, and expiry. Duplicate consent_reference values return 409.",
    "method": "POST",
    "baseUrl": "<LitaConsentApiBaseUrl>",
    "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\": \"2026-04-26T12:00:00Z\",\n    \"updated_at\": \"2026-04-26T12:00:00Z\"\n}"
        },
        "409": {
            "description": "Consent reference already exists",
            "body": "{\n    \"detail\": \"Consent reference already exists\"\n}"
        }
    }
}
{
    "title": "Get Consent",
    "description": "Fetches a stored consent by consent_reference and returns the serialised consent state.",
    "method": "GET",
    "baseUrl": "<LitaConsentApiBaseUrl>",
    "endpoint": "/api/lita/v1/consents/{consent_reference}",
    "headers": [],
    "queryParams": [],
    "pathParams": [
        {
            "key": "consent_reference",
            "value": "consent_local_001",
            "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\": \"2026-04-26T12:00:00Z\",\n    \"updated_at\": \"2026-04-26T12:00:00Z\"\n}"
        },
        "404": {
            "description": "Consent not found",
            "body": "{\n    \"detail\": \"Consent not found\"\n}"
        }
    }
}

Issue Token

{
    "title": "Issue Access Token",
    "description": "Creates an access token for an existing consent and returns its expiry timestamp.",
    "method": "POST",
    "baseUrl": "<LitaConsentApiBaseUrl>",
    "endpoint": "/api/lita/v1/consents/{consent_reference}/tokens",
    "headers": [
        {
            "key": "Content-Type",
            "value": "application/json",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "key": "consent_reference",
            "value": "consent_local_001",
            "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\": \"6a9f6b39-3c77-4f14-9b4a-5e37ff5d4c4a\",\n    \"expires_at\": \"2030-02-01T00:00:00Z\"\n}"
        },
        "404": {
            "description": "Consent not found",
            "body": "{\n    \"detail\": \"Consent not found\"\n}"
        }
    }
}

Store Snapshot

{
    "title": "Store Snapshot",
    "description": "Persists a versioned payload for the consent identified by the bearer token and returns the stored payload echo.",
    "method": "POST",
    "baseUrl": "<LitaConsentApiBaseUrl>",
    "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\": \"2026-04-26T12:00: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": "Missing, invalid, or expired bearer token",
            "body": "{\n    \"detail\": \"Bearer token required\"\n}"
        },
        "403": {
            "description": "Token revoked, consent revoked, or consent expired",
            "body": "{\n    \"detail\": \"Token revoked\"\n}"
        },
        "404": {
            "description": "Token consent relationship missing or consent not found",
            "body": "{\n    \"detail\": \"Consent not found\"\n}"
        }
    }
}

Get Latest Snapshot

{
    "title": "Get Latest Snapshot",
    "description": "Returns the most recent versioned snapshot for the consent identified by the bearer token.",
    "method": "GET",
    "baseUrl": "<LitaConsentApiBaseUrl>",
    "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\": \"2026-04-26T12:00: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": "Missing, invalid, or expired bearer token",
            "body": "{\n    \"detail\": \"Bearer token required\"\n}"
        },
        "403": {
            "description": "Token revoked, consent revoked, or consent expired",
            "body": "{\n    \"detail\": \"Consent revoked\"\n}"
        },
        "404": {
            "description": "No snapshot stored for this consent",
            "body": "{\n    \"detail\": \"No data available for consent\"\n}"
        }
    }
}

Score Application

{
    "title": "Score Application",
    "description": "Computes a score for the supplied request_id or returns the cached decision for that request_id. The implementation caches by ScoreRequest.request_id, not by request header.",
    "method": "POST",
    "baseUrl": "<LitaConsentApiBaseUrl>",
    "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        \"monthly_income\": 6000,\n        \"delinquencies_last_24m\": 0\n    }\n}",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Score returned",
            "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}"
        }
    }
}

Feature Flows

sequenceDiagram
    participant C as Customer
    participant API as Lita router
    participant R as LitaRepository
    participant DB as Database

    C->>API: POST /api/lita/v1/consents
    API->>API: register_consent
    API->>API: normalise expires_at to UTC
    API->>R: create_consent
    R->>DB: insert consent row
    DB-->>R: stored consent model
    R-->>API: consent model
    API->>API: _serialise_consent
    API-->>C: 201 ConsentResponse

2. Access Token Issuance

sequenceDiagram
    participant C as Customer
    participant API as Lita router
    participant R as LitaRepository
    participant DB as Database

    C->>API: POST /api/lita/v1/consents/{consent_reference}/tokens
    API->>R: get_consent
    R->>DB: fetch consent by reference
    DB-->>R: consent or null
    R-->>API: consent
    API->>API: compute expires_at from expires_in_days
    API->>R: issue_access_token
    R->>DB: insert access token row
    DB-->>R: token model
    R-->>API: token model
    API-->>C: 201 TokenResponse

3. Snapshot Write and Read

sequenceDiagram
    participant C as Customer
    participant API as Lita router
    participant Guard as _get_consent_and_token
    participant R as LitaRepository
    participant DB as Database

    C->>API: POST /api/lita/v1/data/snapshots
    API->>Guard: Depends on bearer token
    Guard->>R: get_access_token
    R->>DB: fetch token by value
    DB-->>R: token or null
    R-->>Guard: token record
    Guard->>R: get_consent_by_id
    R->>DB: fetch consent by id
    DB-->>R: consent or null
    R-->>Guard: consent
    Guard-->>API: consent and token
    API->>R: record_snapshot
    R->>DB: insert snapshot row
    DB-->>R: snapshot model
    R-->>API: snapshot model
    API-->>C: 201 SnapshotResponse

    C->>API: GET /api/lita/v1/data/snapshots/latest
    API->>Guard: Depends on bearer token
    Guard->>R: get_access_token
    R->>DB: fetch token by value
    DB-->>R: token or null
    R-->>Guard: token record
    Guard->>R: get_consent_by_id
    R->>DB: fetch consent by id
    DB-->>R: consent or null
    R-->>Guard: consent
    Guard-->>API: consent and token
    API->>R: latest_snapshot
    R->>DB: fetch newest snapshot for consent
    DB-->>R: snapshot model or null
    R-->>API: snapshot model
    API-->>C: 200 SnapshotResponse

4. Score Idempotency

sequenceDiagram
    participant C as Customer
    participant API as Lita router
    participant R as LitaRepository
    participant DB as Database

    C->>API: POST /api/lita/v1/score
    API->>R: get_decision(request_id)
    R->>DB: fetch cached decision
    DB-->>R: cached payload or null
    alt cache hit
        R-->>API: cached payload
        API-->>C: 200 ScoreResponse
    else cache miss
        API->>API: _compute_score
        API->>API: derive decision and reasons
        API->>R: save_decision(request_id, payload)
        R->>DB: insert decision row
        DB-->>R: saved decision
        R-->>API: saved decision
        API-->>C: 200 ScoreResponse
    end

State Management

State Description
active Consent or token can be used while within expiry and not revoked.
revoked revoked_at is populated and access is rejected.
expired expires_at is earlier than the current UTC time.
missing Repository lookup returns no consent, token, or snapshot.

Score decision reuse

State Description
uncached No stored decision exists for the supplied request_id.
cached A stored decision is returned directly from repository.get_decision.

Snapshot versioning

State Description
written record_snapshot has stored a consent-scoped snapshot row.
latest latest_snapshot returns the newest stored row for the consent.

Error Handling

[!NOTE] documents/lita-consent-data-api.md describes idempotency using X-Request-Id, but the implemented score_application handler reads ScoreRequest.request_id from the JSON body and caches with repository.get_decision(body.request_id).

The route handlers convert repository and validation failures into explicit HTTP responses. register_consent normalises naive expiry timestamps to UTC and returns 409 Conflict when the repository raises IntegrityError for an existing consent_reference.

try:
    consent = repository.create_consent(...)
except IntegrityError:
    raise HTTPException(
        status_code=status.HTTP_409_CONFLICT,
        detail="Consent reference already exists",
    )

The bearer-token guard performs the full access chain before a snapshot handler runs:

  • 401 Unauthorized when the bearer header is missing or not a Bearer scheme.
  • 401 Unauthorized when the access token cannot be resolved.
  • 403 Forbidden when the token is revoked.
  • 401 Unauthorized when the token is expired.
  • 404 Not Found when the consent is missing.
  • 403 Forbidden when the consent is revoked.
  • 403 Forbidden when the consent is expired.

For snapshots, a missing latest record produces 404 Not Found with No data available for consent.

Persistence Expectations

documents/lita-implementation-overview.md describes the storage contract behind this API:

  • LitaConsentModel stores consent metadata, expiry, and revocation timestamp.
  • LitaAccessTokenModel stores issued tokens scoped to a consent, with expiry and optional revocation.
  • LitaDataSnapshotModel stores versioned JSON payloads per consent.
  • LitaScoreDecisionModel stores cached scoring decisions keyed by request_id.

The same overview also states that JSON-like fields are persisted as text and reconstructed with json.dumps and json.loads. That matches the router’s _serialise_consent helper, which decodes data_categories and refresh_permissions with json.loads, and read_snapshot, which decodes snapshot.payload with json.loads.

Local Verification Flow

Quick verification commands

  1. Create and activate a virtual environment, then install backend dependencies.
python -m venv .venv
source .venv/bin/activate
pip install -r backend/requirements.txt
  1. Start the FastAPI app.
cd backend
uvicorn src.main:app --host 0.0.0.0 --reload --port 8000
  1. Create a consent.
curl -X POST http://localhost:8000/api/lita/v1/consents \
  -H "Content-Type: application/json" \
  -d '{
    "consent_reference": "consent_local_001",
    "customer_reference": "customer_abc",
    "applicant_reference": "applicant_xyz",
    "country": "GB",
    "product_type": "CREDIT_CARD",
    "data_categories": ["balances", "transactions"],
    "refresh_permissions": ["balances:read", "transactions:read"],
    "expires_at": "2030-01-01T00:00:00Z",
    "refresh_allowed": true
  }'
  1. Issue an access token.
curl -X POST http://localhost:8000/api/lita/v1/consents/consent_local_001/tokens \
  -H "Content-Type: application/json" \
  -d '{"expires_in_days": 30}'
  1. Store a snapshot.
curl -X POST http://localhost:8000/api/lita/v1/data/snapshots \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "version": "1.1",
    "payload": {
      "balances": {"available": 1500, "currency": "GBP"},
      "transactions": [
        {"amount": -20, "description": "Coffee"},
        {"amount": -50, "description": "Groceries"}
      ]
    }
  }'
  1. Read the latest snapshot.
curl -X GET http://localhost:8000/api/lita/v1/data/snapshots/latest \
  -H "Authorization: Bearer <ACCESS_TOKEN>"
  1. Call the score endpoint twice with the same request_id.
curl -X POST http://localhost:8000/api/lita/v1/score \
  -H "Content-Type: application/json" \
  -d '{
    "version": "1.1",
    "request_id": "req-demo-001",
    "applicant": {"applicant_reference": "app-100", "country": "GB"},
    "context": {"product_type": "CREDIT_CARD"},
    "features": {
      "credit_utilization": 0.65,
      "debt_to_income_ratio": 0.4,
      "credit_history_months": 30,
      "monthly_income": 6000
    }
  }'

SQLite fallback behavior

documents/lita-testing-guide.md states that local runs use sqlite:///./app.db when DATABASE_URL is not set. The same guide’s smoke-test script runs the consent, token, snapshot, and scoring flow against that fallback, so local verification does not require MySQL for the basic path.

Targeted regression test

pytest backend/tests/interface/test_lita_endpoints.py -q

That test module covers:

  • consent registration
  • access token issuance
  • snapshot round-trip persistence
  • score idempotency with repeated request_id

One-shot smoke test

./scripts/lita_smoke_test.sh

The script:

  • runs the targeted pytest module
  • starts uvicorn against the SQLite fallback
  • creates a consent
  • issues a token
  • stores and reads a snapshot
  • exercises scoring twice to confirm idempotency

If dependencies are missing, the script bootstraps them from backend/requirements.txt. Set LITA_BOOTSTRAP_DEPS=0 to disable that install step.

Testing Considerations

Scenario Expected result
Duplicate consent_reference 409 Conflict from consent creation.
Missing bearer token on snapshot routes 401 Unauthorized.
Revoked or expired token 403 Forbidden or 401 Unauthorized depending on the failure stage.
Missing consent for token 404 Not Found.
Missing latest snapshot 404 Not Found.
Repeated score request with same request_id Identical ScoreResponse from the repository cache.
No DATABASE_URL locally SQLite file at sqlite:///./app.db.

Dependencies

Dependency Role in this domain
fastapi Router, dependency injection, HTTP exceptions, and bearer auth extraction.
pydantic Request and response model definitions.
sqlalchemy Session injection and IntegrityError handling.
json Consent and snapshot payload decoding.
datetime, timedelta, timezone Consent, token, and snapshot timestamp handling.
LitaRepository Persistence and score decision caching.
get_db SQLAlchemy session provider used by get_repository.

Key Classes Reference

Class Responsibility
lita_endpoints.py FastAPI router, consent/token/snapshot/score handlers, and API models.
consent.py Compatibility alias for ConsentGrantModel.
lita-consent-data-api.md Customer-facing consent-data API contract and persistence expectations.
lita-testing-guide.md Local verification steps, SQLite fallback usage, and smoke-test flow.