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
- Fastify validates the body with
creditProfileSchema. - The handler checks
request.tenantIdand throwsError("missing tenant")if the request is not tenant-scoped. - The handler casts the body to the inferred schema type.
upsertCreditProfile(request.tenantId, body.externalUserId, body.data)is awaited.request.logAuditEventrecordscredit_profile.upsertwith:targetType: "CreditProfile"targetId: profile.idmetadata.externalUserId
- 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
- Fastify validates
params.idas a UUID. - The handler checks
request.tenantIdand throwsError("missing tenant")if the request is not tenant-scoped. - The handler calls
getCreditProfile(request.tenantId, params.id). - When the lookup returns
nullorundefined, the reply code is set to404and the body is{ error: "not_found" }. - When a profile is found, it is returned directly.
Tenant scoping behavior
Note: The route schema only declares a
200response, but the handler returns a404body 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
- Fastify validates the body with
decisionInputSchema. - The handler checks
request.tenantIdand throwsError("missing tenant")if the request is not tenant-scoped. - The handler casts the body to the inferred schema type.
runDecision(request.tenantId, body.creditProfileId)is awaited first.- The computed result is persisted with
createDecision(request.tenantId, body.creditProfileId, decisionResult). request.logAuditEventrecordsdecision.createwith:targetType: "Decision"targetId: decision.idmetadata.outcome
- The response code is explicitly set to
201. - 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
- Fastify validates
params.idas a UUID. - The handler checks
request.tenantIdand throwsError("missing tenant")if the request is not tenant-scoped. getDecision(request.tenantId, params.id)is awaited.- When the lookup returns no result, the reply code is set to
404and the body is{ error: "not_found" }. - When a decision is found, it is returned directly.
@lita/core decision flow
Note: The route schema only declares a
200response, but the handler returns a404body 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:
runDecision(request.tenantId, body.creditProfileId)computes the decision result from the stored credit profile.createDecision(request.tenantId, body.creditProfileId, decisionResult)persists the evaluated decision.- 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
404with{ 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. |