Credit Scoring and Decisions Domain - Credit Profile Ingestion and Decision Persistence APIs

Overview

This domain exposes the tenant-scoped API surface for ingesting credit profiles and persisting credit decisions. The routes are registered under /v1 and operate as Fastify plugins that validate payloads with zod, call @lita/core domain functions, and write audit events after successful persistence.

The credit profile endpoints support upsert and lookup by tenant, while the decision endpoints evaluate a credit profile through runDecision, persist the result with createDecision, and expose retrieval by decision ID. The API is built for auditability: credit_profile.upsert and decision.create are both logged with tenant-associated metadata immediately after the core write completes.

Architecture Overview

flowchart TB
    Client[API Client] --> V1Routes[registerV1Routes]

    subgraph V1Surface[API Surface]
        CreditProfiles[creditProfilesRoutes]
        Decisions[decisionsRoutes]
    end

    subgraph CoreDomain[Core Domain]
        UpsertCreditProfile[upsertCreditProfile]
        GetCreditProfile[getCreditProfile]
        RunDecision[runDecision]
        CreateDecision[createDecision]
        GetDecision[getDecision]
    end

    subgraph AuditTrail[Audit Trail]
        AuditEvent[request.logAuditEvent]
    end

    V1Routes --> CreditProfiles
    V1Routes --> Decisions

    CreditProfiles --> UpsertCreditProfile
    CreditProfiles --> GetCreditProfile
    CreditProfiles --> AuditEvent

    Decisions --> RunDecision
    Decisions --> CreateDecision
    Decisions --> GetDecision
    Decisions --> AuditEvent

Route Registration

registerV1Routes

File: apps/api/src/routes/v1/index.ts

registerV1Routes mounts the v1 route groups used by this domain. The credit profile and decision routes are registered under their dedicated prefixes, so the handlers in the child plugins resolve to the /v1/... paths documented below.

Method Description
registerV1Routes Registers the v1 route plugins, including creditProfilesRoutes at /v1/credit-profiles and decisionsRoutes at /v1/decisions.

Credit Profile Ingestion

Request and response models

creditProfileSchema

File: apps/api/src/routes/v1/credit-profiles.ts

Property Type Description
externalUserId string Tenant-local external user identifier. Must be at least 1 character.
data Record<string, unknown> Arbitrary credit profile payload persisted as JSON.

Credit profile response shape

File: apps/api/src/routes/v1/credit-profiles.ts

Property Type Description
id string Persisted profile identifier.
externalUserId string External user identifier associated with the profile.
dataJson any Opaque JSON representation of the credit profile data.

creditProfilesRoutes

File: apps/api/src/routes/v1/credit-profiles.ts

Method Description
creditProfilesRoutes Exposes tenant-scoped credit profile upsert and lookup endpoints.

Upsert Credit Profile

{
    "title": "Upsert Credit Profile",
    "description": "Creates or updates a tenant-scoped credit profile and writes an audit event after persistence.",
    "method": "POST",
    "baseUrl": "<ApiBaseUrl>",
    "endpoint": "/v1/credit-profiles",
    "headers": [
        {
            "key": "Content-Type",
            "value": "application/json",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [],
    "bodyType": "json",
    "requestBody": "{\n    \"externalUserId\": \"user_48291\",\n    \"data\": {\n        \"bureauScore\": 742,\n        \"utilization\": 0.31,\n        \"delinquencies30d\": 0,\n        \"incomeMonthly\": 8200,\n        \"employmentStatus\": \"EMPLOYED\"\n    }\n}",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Success",
            "body": "{\n    \"id\": \"cp_8f2d9c7f1a\",\n    \"externalUserId\": \"user_48291\",\n    \"dataJson\": {\n        \"bureauScore\": 742,\n        \"utilization\": 0.31,\n        \"delinquencies30d\": 0,\n        \"incomeMonthly\": 8200,\n        \"employmentStatus\": \"EMPLOYED\"\n    }\n}"
        }
    }
}

Execution path

  1. Fastify validates the body with creditProfileSchema.
  2. The handler checks request.tenantId and throws Error("missing tenant") if the request is not tenant-scoped.
  3. The handler casts the body to the inferred schema type.
  4. upsertCreditProfile(request.tenantId, body.externalUserId, body.data) is awaited.
  5. request.logAuditEvent records credit_profile.upsert with:
    • targetType: "CreditProfile"
    • targetId: profile.id
    • metadata.externalUserId
  6. The persisted profile is returned to the caller.

Get Credit Profile

{
    "title": "Get Credit Profile",
    "description": "Fetches a tenant-scoped credit profile by ID.",
    "method": "GET",
    "baseUrl": "<ApiBaseUrl>",
    "endpoint": "/v1/credit-profiles/:id",
    "headers": [],
    "queryParams": [],
    "pathParams": [
        {
            "key": "id",
            "required": true,
            "type": "string",
            "description": "Credit profile UUID"
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Success",
            "body": "{\n    \"id\": \"cp_8f2d9c7f1a\",\n    \"externalUserId\": \"user_48291\",\n    \"dataJson\": {\n        \"bureauScore\": 742,\n        \"utilization\": 0.31,\n        \"delinquencies30d\": 0,\n        \"incomeMonthly\": 8200,\n        \"employmentStatus\": \"EMPLOYED\"\n    }\n}"
        },
        "404": {
            "description": "Not Found",
            "body": "{\n    \"error\": \"not_found\"\n}"
        }
    }
}

Execution path

  1. Fastify validates params.id as a UUID.
  2. The handler checks request.tenantId and throws Error("missing tenant") if the request is not tenant-scoped.
  3. The handler calls getCreditProfile(request.tenantId, params.id).
  4. When the lookup returns null or undefined, the reply code is set to 404 and the body is { error: "not_found" }.
  5. When a profile is found, it is returned directly.

Tenant scoping behavior

Note: The route schema only declares a 200 response, but the handler returns a 404 body of { error: "not_found" } when the profile is missing. Clients generated strictly from the declared schema will not see that error shape.

Both credit profile handlers require request.tenantId before calling @lita/core. The tenant value is used as the partition key for all reads and writes in this domain, so a profile created for one tenant cannot be fetched through another tenant context.

Decision Persistence

Request and response models

decisionInputSchema

File: apps/api/src/routes/v1/decisions.ts

Property Type Description
creditProfileId string UUID of the credit profile used as decision input.

Decision response shape

File: apps/api/src/routes/v1/decisions.ts

Property Type Description
id string Persisted decision identifier.
outcome string Decision outcome returned by the core flow.
reasonCodesJson any Opaque JSON reason code payload.
scoreJson any Opaque JSON score payload.

decisionsRoutes

File: apps/api/src/routes/v1/decisions.ts

Method Description
decisionsRoutes Exposes tenant-scoped decision creation and lookup endpoints.

Create Decision

{
    "title": "Create Decision",
    "description": "Evaluates a credit profile through @lita/core, persists the decision, and records an audit event.",
    "method": "POST",
    "baseUrl": "<ApiBaseUrl>",
    "endpoint": "/v1/decisions",
    "headers": [
        {
            "key": "Content-Type",
            "value": "application/json",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [],
    "bodyType": "json",
    "requestBody": "{\n    \"creditProfileId\": \"9f4a7b4a-2d55-4e74-9d07-3d2f95b66c1a\"\n}",
    "formData": [],
    "rawBody": "",
    "responses": {
        "201": {
            "description": "Created",
            "body": "{\n    \"id\": \"dec_7d1d0d4d2d\",\n    \"outcome\": \"APPROVE\",\n    \"reasonCodesJson\": [\n        \"LOW_UTILIZATION\",\n        \"STABLE_INCOME\"\n    ],\n    \"scoreJson\": {\n        \"score\": 742,\n        \"modelVersion\": \"core-1.0.0\"\n    }\n}"
        }
    }
}

Execution path

  1. Fastify validates the body with decisionInputSchema.
  2. The handler checks request.tenantId and throws Error("missing tenant") if the request is not tenant-scoped.
  3. The handler casts the body to the inferred schema type.
  4. runDecision(request.tenantId, body.creditProfileId) is awaited first.
  5. The computed result is persisted with createDecision(request.tenantId, body.creditProfileId, decisionResult).
  6. request.logAuditEvent records decision.create with:
    • targetType: "Decision"
    • targetId: decision.id
    • metadata.outcome
  7. The response code is explicitly set to 201.
  8. The persisted decision is returned.

Get Decision

{
    "title": "Get Decision",
    "description": "Fetches a tenant-scoped decision by ID.",
    "method": "GET",
    "baseUrl": "<ApiBaseUrl>",
    "endpoint": "/v1/decisions/:id",
    "headers": [],
    "queryParams": [],
    "pathParams": [
        {
            "key": "id",
            "required": true,
            "type": "string",
            "description": "Decision UUID"
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Success",
            "body": "{\n    \"id\": \"dec_7d1d0d4d2d\",\n    \"outcome\": \"APPROVE\",\n    \"reasonCodesJson\": [\n        \"LOW_UTILIZATION\",\n        \"STABLE_INCOME\"\n    ],\n    \"scoreJson\": {\n        \"score\": 742,\n        \"modelVersion\": \"core-1.0.0\"\n    }\n}"
        },
        "404": {
            "description": "Not Found",
            "body": "{\n    \"error\": \"not_found\"\n}"
        }
    }
}

Execution path

  1. Fastify validates params.id as a UUID.
  2. The handler checks request.tenantId and throws Error("missing tenant") if the request is not tenant-scoped.
  3. getDecision(request.tenantId, params.id) is awaited.
  4. When the lookup returns no result, the reply code is set to 404 and the body is { error: "not_found" }.
  5. When a decision is found, it is returned directly.

@lita/core decision flow

Note: The route schema only declares a 200 response, but the handler returns a 404 body of { error: "not_found" } when the decision is missing. Clients generated strictly from the declared schema will not see that error shape.

The decision creation path exposes the core evaluation pipeline in two distinct steps:

  1. runDecision(request.tenantId, body.creditProfileId) computes the decision result from the stored credit profile.
  2. createDecision(request.tenantId, body.creditProfileId, decisionResult) persists the evaluated decision.
  3. The persisted record is then audit-logged and returned to the client.

This means the API does not persist the raw evaluation output directly; it persists the result of the core evaluation flow as a tenant-scoped decision record.

Audit Logging and Tenant Scoping

Both write endpoints emit audit events after the core persistence call succeeds and before the HTTP response is returned. The audit payloads are narrow and action-specific.

Action Target Type Target ID Metadata
credit_profile.upsert CreditProfile profile.id { externalUserId: body.externalUserId }
decision.create Decision decision.id { outcome: decision.outcome }

The audit call is awaited in both handlers, so the request does not complete until the audit write finishes. This keeps the persisted entity and its audit record in the same request lifecycle.

Error Handling

The route handlers use a small set of explicit failure modes:

  • Missing tenant context: both create and lookup handlers throw Error("missing tenant").
  • Missing profile or decision: both lookup handlers return a 404 with { error: "not_found" }.
  • Validation failures: Fastify schema validation rejects invalid UUIDs and malformed bodies before the handler body executes.

The decision create path also sets reply.code(201) explicitly before returning the persisted record, which makes the created resource semantics visible at the HTTP layer.

Key Classes Reference

Class Responsibility
index.ts Registers the v1 route plugins and mounts the credit profile and decision APIs under /v1.
credit-profiles.ts Implements tenant-scoped credit profile upsert and lookup, plus credit_profile.upsert audit logging.
decisions.ts Implements tenant-scoped decision creation and lookup, plus decision.create audit logging.