Deployment, Operations, and Observability - US API runtime packaging, security posture, and deployment readiness
Overview
The US API runtime is a TypeScript service that handles consent lifecycle actions, token issuance and validation, evidence capture, model governance, and internal analytics ingestion. The visible source centers on a Fastify-based HTTP layer, Prisma-backed persistence, PostgreSQL pools for analytics jobs and routes, and a set of operational entrypoints that can run as standalone processes.
Operationally, the service is built around environment-driven configuration for JWT material, partner API keys, and internal tokens. Observability is implemented through request IDs, post-response access logging, explicit error serialization, and background jobs that print success or failure to the console before exiting with a process code.
Architecture Overview
flowchart TD
subgraph Runtime [US API Runtime]
Server[Fastify Server]
ReqId[ensureRequestId]
PartnerAuth[requirePartnerAuth]
AccessAuth[requireAccessToken]
InternalAuth[requireInternalAuth]
Audit[registerAuditLogger]
ErrHandler[errorHandler]
Routes[registerInternalAnalyticsRoutes]
ConsentSvc[consentService]
TokenSvc[tokenService]
ConnSvc[connectionService]
FeatureSvc[featureService]
ScoreSvc[scoringService]
GovSvc[modelGovernanceService]
WebhookSvc[webhookService]
Jobs[dailyPsuConsentMetrics psuConsentTimeoutWatchdog featureDriftJob retrainTriggerJob]
Config[config]
end
subgraph Data [Data and External Systems]
Prisma[(Prisma)]
PgPool[(Postgres Pool)]
ExternalJwt[JWT Key Material]
Callback[Scoring Callback URL]
PartnerHooks[Partner Webhook Endpoints]
end
Server --> ReqId
Server --> PartnerAuth
Server --> AccessAuth
Server --> InternalAuth
Server --> Audit
Server --> Routes
Routes --> PgPool
Routes --> ConsentSvc
Routes --> InternalAuth
ConsentSvc --> Prisma
ConsentSvc --> WebhookSvc
TokenSvc --> Prisma
TokenSvc --> Config
TokenSvc --> AccessAuth
ConnSvc --> Prisma
FeatureSvc --> Prisma
FeatureSvc --> GovSvc
ScoreSvc --> Prisma
ScoreSvc --> FeatureSvc
ScoreSvc --> GovSvc
ScoreSvc --> Config
WebhookSvc --> Prisma
WebhookSvc --> PartnerHooks
GovSvc --> Prisma
Jobs --> PgPool
Jobs --> GovSvc
Jobs --> FeatureSvc
Config --> ExternalJwt
Config --> Callback
Runtime Packaging and Execution Model
The visible runtime packaging is TypeScript-first and compiles src into dist with ES2022 modules.
| File |
Runtime Role |
Notes |
services/us-api/tsconfig.json |
Production compile settings |
target and module are both ES2022, outDir is dist, and rootDir is src. |
services/us-api/tsconfig.test.json |
Test compile settings |
Extends the main config and switches to CommonJS and Node module resolution for Jest. |
services/us-api/src/jobs/dailyPsuConsentMetrics.ts |
Standalone job entrypoint |
Runs automatically when process.argv[1] contains dailyPsuConsentMetrics. |
services/us-api/src/jobs/psuConsentTimeoutWatchdog.ts |
Standalone job entrypoint |
Runs automatically when process.argv[1] contains psuConsentTimeoutWatchdog. |
services/us-api/src/jobs/featureDriftJob.ts |
Exported job function |
Callable from an external scheduler or runner. |
services/us-api/src/jobs/retrainTriggerJob.ts |
Exported job function |
Callable from an external scheduler or runner. |
dailyPsuConsentMetrics.ts and psuConsentTimeoutWatchdog.ts both support optional Pool injection, which allows the job logic to run against the shared pool or a test-specific pool override.
Job Entrypoint Behavior
runDailyPsuConsentMetricsJob
- Resolves
lookbackDays from LOOKBACK_DAYS, defaulting to 7.
- Resolves
runDate from RUN_DATE, defaulting to the current date.
- Calls
refreshDailyMetricsForRange(poolOverride ?? pool, runDate, lookbackDays).
- On direct execution, logs completion or failure and exits with code
0 or 1.
runPsuConsentTimeoutWatchdog
- Parses
PROVIDER_TIMEOUT_MINUTES as JSON into a provider-specific timeout map.
- Resolves
DEFAULT_TIMEOUT_MINUTES, defaulting to 15.
- Queries
analytics.psu_consent_sessions for rows with final_status IS NULL and started_at IS NOT NULL.
- Applies
consent_timeout events to stale sessions through applyConsentEvent.
- On direct execution, logs completion or failure and exits with code
0 or 1.
Configuration Surface
The runtime reads security and operational settings from the imported config object and job-specific environment variables.
Config Values Referenced in Source
| Config Value |
Type |
Used By |
Purpose |
jwtPublicKey |
string |
requireAccessToken, introspectToken |
Verifies RS256 access tokens. |
jwtPrivateKey |
string |
issueTokens |
Signs RS256 access tokens. |
internalApiToken |
string |
requireInternalAuth |
Protects internal routes and admin-style operations. |
partnerApiKeys |
string[] |
requirePartnerAuth |
Authorizes partner-facing requests. |
tokenTtlSeconds |
number |
issueTokens |
Sets access token lifetime and token record expiry. |
scoringCallbackUrl |
string |
replayDecision |
Optional outbound decision replay endpoint. |
Job Environment Variables
| Variable |
Type |
Used By |
Purpose |
LOOKBACK_DAYS |
number |
resolveLookbackDays |
Controls the PSU consent metrics backfill window. |
RUN_DATE |
YYYY-MM-DD |
resolveRunDate |
Overrides the job execution date. |
PROVIDER_TIMEOUT_MINUTES |
JSON object |
parseProviderTimeoutMap |
Sets provider-specific timeout overrides. |
DEFAULT_TIMEOUT_MINUTES |
number |
resolveDefaultTimeoutMinutes |
Sets the fallback timeout window for consent sessions. |
Security Posture
Security is enforced at multiple layers: transport-adjacent headers, JWT verification, internal token checks, partner token checks, consent state guards, and refresh throttling.
Request Context Augmentations
AccessClaims
| Property |
Type |
Description |
consent_id |
string |
Consent identifier extracted from verified access tokens. |
purpose |
Purpose |
Consent purpose claim. |
data_categories |
DataCategory[] |
Allowed data categories carried by the token. |
jti |
string |
JWT identifier used for token record lookup. |
requireAccessToken stores this object on FastifyRequest.accessClaims.
partnerId Request Field
| Property |
Type |
Description |
partnerId |
string \ |
undefined |
Partner Authentication
requirePartnerAuth
| Method |
Description |
requirePartnerAuth |
Accepts partner credentials from Authorization: Bearer, x-partner-token, x-api-key, or the partner_token query parameter, then checks the token against config.partnerApiKeys. |
Behavior:
- Throws
403 PARTNER_AUTH_REQUIRED when no token is supplied.
- Throws
403 PARTNER_AUTH_REQUIRED when the token is not present in config.partnerApiKeys.
- Writes the validated token value into
request.partnerId.
Internal Authentication
requireInternalAuth
| Method |
Description |
requireInternalAuth |
Validates internal-only calls using x-internal-token or a Bearer token in Authorization, and compares the token to config.internalApiToken. |
Behavior:
- Throws
403 FORBIDDEN with message Internal API token required. when the token is missing or mismatched.
Access Token Verification
requireAccessToken
| Method |
Description |
requireAccessToken |
Verifies access tokens with jsonwebtoken using config.jwtPublicKey and RS256, then hydrates request.accessClaims. |
Behavior:
- Accepts tokens from
Authorization: Bearer, x-access-token, or access_token query parameter.
- Throws
403 TOKEN_REQUIRED when no token is provided.
- Throws
403 INVALID_TOKEN when the JWT is invalid, the payload is not an object, or required claims are missing.
- Requires
consent_id, purpose, data_categories, and jti in the payload.
Consent and Connection State Enforcement
Consent State
| State |
Meaning |
PENDING_USER_ACTION |
Created by createConsent before exchange. |
ACTIVE |
Required by ensureConsentActive; created by exchangeToken when a pending consent is exchanged. |
REVOKED |
Set by revokeConsent; blocks token refresh and data access. |
Connection State
| State |
Meaning |
ACTIVE |
Returned when no blocking connection issue is present. |
REAUTH_REQUIRED |
Throws 409 REAUTH_REQUIRED and surfaces reauth_link from the matching connection. |
DEGRADED |
Returned when a degraded connection exists. |
DISCONNECTED |
Set during consent revocation. |
connectionService
| Method |
Description |
ensureConnectionsReady |
Reads connections for a consent and either returns readiness state or throws a re-authentication error. |
recordConnectionRefresh |
Marks all consent connections as refreshed and active. |
consentService
| Method |
Description |
createConsent |
Creates a consent in PENDING_USER_ACTION, writes a consent log entry, and computes an expiry date. |
revokeConsent |
Revokes a consent, revokes active tokens, disconnects linked connections, writes a log entry, and attempts webhook delivery. |
getConsentReceipt |
Returns a serializable consent receipt. |
ensureConsentActive |
Rejects non-active or expired consents with 409 CONSENT_REVOKED. |
Token Issuance and Refresh Controls
TokenPair
| Property |
Type |
Description |
access_token |
string |
Signed RS256 access token. |
refresh_token |
string |
Random refresh token string with rtk_us_ prefix. |
expires_in |
number |
Lifetime in seconds. |
scope |
object |
Purpose and allowed categories carried by the token pair. |
TokenPair.scope
| Property |
Type |
Description |
purpose |
Purpose |
Token purpose scope. |
data_categories |
DataCategory[] |
Token category scope. |
tokenService
| Method |
Description |
exchangeToken |
Validates an optional link token, activates pending consents, issues tokens, and dispatches a consent_activated webhook when applicable. |
refreshToken |
Validates a refresh token hash, checks consent state and expiry, enforces daily refresh limits, then issues a new pair. |
introspectToken |
Verifies access token validity and looks up the persisted token record by jti. |
Behavior details:
exchangeToken expects linkToken to equal linktok_${consentId} when present.
refreshToken rejects revoked or expired consents with 409 CONSENT_REVOKED.
refreshToken enforces daily refresh limits when refreshEnabled is true.
introspectToken returns { active: false } on any invalid token condition or missing token record.
Refresh Limit State
| State |
Meaning |
enabled: false |
Refresh throttling is bypassed. |
enabled: true and count below limit |
A refreshEvent row is recorded and the refresh proceeds. |
enabled: true and count at or above limit |
Throws 429 REFRESH_LIMIT_EXCEEDED. |
Deny Reason Validation
DenyReasonsAllowlist
INSUFFICIENT_INCOME, INCOME_INSTABILITY, RECENT_OVERDRAFTS, LOW_MIN_BALANCE, HIGH_CASHFLOW_VOLATILITY, INSUFFICIENT_HISTORY, UNVERIFIED_ACCOUNT, INCONSISTENT_IDENTITY_SIGNALS, HIGH_RISK_DEVICE_SIGNAL
scoringService
| Method |
Description |
validateDecision |
Enforces that DENY decisions include at least one allowlisted reason. |
storeDecision |
Persists a decision, records model lineage when present, and links the decision to evidence and schema version. |
replayDecision |
Replays a decision from evidence, optionally calls an external scoring callback, and stores the returned decision. |
Observability and Audit Logging
Observability in the visible code is centered on request IDs, response logging, and structured error payloads.
Request ID Propagation
ensureRequestId
| Method |
Description |
ensureRequestId |
Reads x-request-id when present or generates a UUID, writes it back to the request and response, and keeps it available for downstream logging. |
Behavior:
- Sets
request.headers['x-request-id'].
- Sets the response header
X-Request-Id.
Access Log Writes
registerAuditLogger
| Method |
Description |
registerAuditLogger |
Registers an onResponse hook that writes an accessLog row after each response. |
Captured fields:
requestId from x-request-id
partnerId from request.partnerId
consentId from request.accessClaims?.consent_id
route from request.routeOptions?.url or request.raw.url
statusCode from the final response
Module state:
auditLoggingEnabled gates the hook after database initialization failures.
auditLoggingDisabledLogged suppresses repeated warnings after logging has been disabled once.
If Prisma initialization fails while writing access logs:
- Audit logging is disabled globally.
- A single warning is emitted through
app.log.warn.
Error Serialization
errorHandler
| Method |
Description |
errorHandler |
Converts ApiError instances into structured JSON and converts unexpected errors into a generic 500 response. |
Response shapes:
ApiError:
error.code
error.message
error.details
request_id
- Unexpected error:
error.code = PROVIDER_UNAVAILABLE
error.message = Unexpected error
request_id
Outbound Webhook Dispatch
Webhooks are part of the consent activation and revocation flows. They are delivered asynchronously and persisted in delivery tables before the outbound HTTP call.
WebhookEvent
| Property |
Type |
Description |
event |
string |
Outbound event name. |
payload |
Record<string, unknown> |
Event body sent to webhook consumers. |
webhookService
| Method |
Description |
dispatchWebhook |
Loads active endpoints for a partner and event, creates delivery rows, signs the payload, sends the webhook, and updates delivery status. |
signPayload |
Produces an HMAC SHA256 signature over the JSON payload. |
Outbound request behavior:
Content-Type: application/json
X-Webhook-Signature
Idempotency-Key
Delivery flow:
- Matching endpoints are fetched with
active: true and event membership.
- A
webhookDelivery row is created in PENDING.
- Delivery status becomes
DELIVERED or FAILED.
- Fetch failures throw
502 PROVIDER_UNAVAILABLE.
Operational Jobs and Background Processing
PSU Consent Metrics Backfill
runDailyPsuConsentMetricsJob
| Method |
Description |
runDailyPsuConsentMetricsJob |
Resolves the job window and refreshes daily PSU consent metrics over a date range. |
Inputs:
lookbackDays from options or LOOKBACK_DAYS
runDate from options or RUN_DATE
Behavior:
- Defaults
LOOKBACK_DAYS to 7.
- Defaults
RUN_DATE to the current date.
- Throws
RUN_DATE must be YYYY-MM-DD when the override string is not a valid date.
- Uses
refreshDailyMetricsForRange(poolOverride ?? pool, runDate, lookbackDays).
PSU Consent Timeout Watchdog
runPsuConsentTimeoutWatchdog
| Method |
Description |
runPsuConsentTimeoutWatchdog |
Finds stale consent sessions and emits timeout events. |
Inputs:
PROVIDER_TIMEOUT_MINUTES JSON map
DEFAULT_TIMEOUT_MINUTES fallback value
Behavior:
- Reads
analytics.psu_consent_sessions.
- Skips rows with no
started_at.
- Compares
started_at + timeoutMinutes to now.
- Emits
consent_timeout with failure_reason: timeout.
Feature Drift Check
runDailyFeatureDriftCheck
| Method |
Description |
runDailyFeatureDriftCheck |
Runs feature drift detection for US_CASHFLOW_V1 using the global credit schema version. |
Hard-coded invocation parameters:
featureSet: US_CASHFLOW_V1
schemaVersion: GLOBAL_CREDIT_FEATURE_SCHEMA_VERSION
sampleLimit: 500
baselineLabel: training-baseline
Retraining Trigger Evaluation
| Method |
Description |
evaluateRetrainingForModel |
Delegates to evaluateRetrainingTriggers for a given model artifact. |
Analytics and Governance Services
Feature Schema Migration
GLOBAL_CREDIT_FEATURE_SCHEMA_VERSION
global-credit-v1
GlobalCreditFeatureSchemaV1
| Property |
Type |
Description |
schema_version |
literal global-credit-v1 |
Schema version identifier. |
income_monthly_avg_usd |
number |
Average income in USD. |
income_stability_index |
number |
Stabilized income score. |
nsf_overdraft_count_180d |
number |
Overdraft count over 180 days. |
balance_min_30d_usd |
number |
Minimum balance over 30 days. |
rent_payment_detected |
boolean |
Indicates whether rent payment activity was detected. |
debt_payment_ratio_est |
number |
Estimated debt-payment-to-income ratio. |
FeatureMigrationResult
| Property |
Type |
Description |
schema_version |
literal global-credit-v1 |
Result schema version. |
features |
GlobalCreditFeatureSchemaV1 |
Normalized feature payload. |
migration_notes |
string[] |
Notes about defaults or unsupported source sets. |
migrateToGlobalCreditSchemaV1
| Method |
Description |
migrateToGlobalCreditSchemaV1 |
Normalizes arbitrary feature input to the global credit schema, applies defaults, and records migration notes. |
Behavior:
- If
feature_set is not US_CASHFLOW_V1, a note is added and defaults are applied.
- Any missing fields are defaulted from
defaultFeatureValues.
- Notes are added for missing defaulted fields.
Cashflow Feature Generation
computeCashflow
| Method |
Description |
computeCashflow |
Generates cashflow features from synthetic provider data, writes an evidence snapshot, and returns the normalized feature payload. |
Flow:
- Reads accounts, balances, transactions, and income from
mockProvider.
- Computes:
income_monthly_avg_usd
income_stability_index
nsf_overdraft_count_180d
balance_min_30d_usd
rent_payment_detected
debt_payment_ratio_est
- Creates an
evidenceSnapshot row with:
featureSet
features
inputsDigest
lookbackDays
schemaVersion
metadata
Evidence Fetching
fetchEvidence
| Method |
Description |
fetchEvidence |
Retrieves an evidence snapshot by ID or throws 404 NOT_FOUND. |
Feature Drift Detection
| Property |
Type |
Description |
featureSet |
string |
Feature set to evaluate. |
schemaVersion |
string |
Schema version used to find the baseline. |
sampleLimit |
number |
Optional snapshot count limit. |
baselineLabel |
string |
Optional baseline label. |
| Property |
Type |
Description |
aucMin |
number |
Lower bound for AUC before retraining is considered. |
driftScoreMax |
number |
Upper bound for drift score before retraining is considered. |
modelGovernanceService
| Method |
Description |
ensureFeatureSchemaVersion |
Ensures the global credit feature schema row exists in the database. |
runFeatureDriftDetection |
Compares live evidence snapshots against a baseline distribution and writes a drift report. |
evaluateRetrainingTriggers |
Checks latest model performance and latest drift to decide whether a retraining trigger should be created. |
recordModelLineage |
Creates model artifact and deployment records when a new lineage entry does not already exist. |
Behavior details:
ensureFeatureSchemaVersion writes a schema definition and migration rules for US_CASHFLOW_V1.
runFeatureDriftDetection flags features with absolute z-score greater than or equal to 2.
evaluateRetrainingTriggers uses defaults aucMin: 0.72 and driftScoreMax: 0.3.
recordModelLineage creates a modelDeployment row with status: ACTIVE and metadata.source: decision-ingest.
Decision Replay and Storage
DecisionPayload
| Property |
Type |
Description |
applicant_reference |
string \ |
undefined |
purpose |
string |
Decision purpose. |
product_type |
string \ |
undefined |
score |
number \ |
undefined |
decision |
string |
Final decision value. |
approved_limit |
number \ |
undefined |
model |
object \ |
undefined |
reasons |
`{ code: string; description?: string }[] \ |
undefined` |
evidence_ref |
string |
Evidence snapshot reference. |
consent_id |
string |
Consent identifier. |
consent_text_version |
string |
Consent text version. |
connection_status |
string |
Connection readiness value. |
features |
Record<string, unknown> |
Feature payload used for the decision. |
DecisionPayload.model
| Property |
Type |
Description |
name |
string \ |
undefined |
version |
string \ |
undefined |
schema_version |
string \ |
undefined |
training_snapshot_ref |
string \ |
undefined |
hyperparameters |
`Record<string, unknown> \ |
undefined` |
metrics |
`Record<string, unknown> \ |
undefined` |
scoringService
| Method |
Description |
validateDecision |
Rejects DENY decisions without allowlisted reasons. |
storeDecision |
Persists a decision record and optionally persists model lineage. |
replayDecision |
Replays a decision from evidence or fetches an existing decision when no callback URL is configured. |
Behavior details:
storeDecision resolves schemaVersion from the payload model, the evidence snapshot, or GLOBAL_CREDIT_FEATURE_SCHEMA_VERSION.
replayDecision posts to config.scoringCallbackUrl with Content-Type: application/json when the callback URL is configured.
- If the callback responds with a non-OK status,
replayDecision throws 502 PROVIDER_UNAVAILABLE.
Synthetic Cashflow Provider
mockProvider
| Method |
Description |
accounts |
Returns deterministic account data for a consent ID. |
balances |
Returns deterministic balances for a consent ID. |
transactions |
Returns deterministic transactions for a consent ID. |
transactionsSync |
Returns a deterministic sync payload with added, modified, removed, and next cursor values. |
income |
Returns a deterministic provider-style income response. |
Account
| Property |
Type |
Description |
account_token |
string |
Synthetic account token. |
name |
string |
Account display name. |
type |
string |
Account type. |
mask |
string |
Account mask. |
Balance
| Property |
Type |
Description |
account_token |
string |
Account token. |
available |
number |
Available balance. |
current |
number |
Current balance. |
currency |
string |
Currency code. |
Transaction
| Property |
Type |
Description |
transaction_id |
string |
Transaction identifier. |
account_token |
string |
Related account token. |
amount |
number |
Transaction amount. |
currency |
string |
Currency code. |
posted_at |
string |
Posting timestamp. |
merchant_name |
string |
Merchant name. |
merchant_category |
string |
Merchant category. |
TransactionSync
| Property |
Type |
Description |
added |
Transaction[] |
Added transactions. |
modified |
Transaction[] |
Modified transactions. |
removed |
{ transaction_id: string }[] |
Removed transaction identifiers. |
next_cursor |
string |
Sync cursor for the next request. |
Income
| Property |
Type |
Description |
income_id |
string |
Income record identifier. |
amount |
number |
Income amount. |
currency |
string |
Currency code. |
pay_date |
string |
Payment date. |
IncomeResponse
| Property |
Type |
Description |
method |
`'provider' |
'inferred'` |
income |
Income[] |
Income records. |
Internal Analytics API
registerInternalAnalyticsRoutes
| Method |
Description |
registerInternalAnalyticsRoutes |
Registers internal analytics ingestion and metrics endpoints under the Fastify instance. |
The route module validates input with Zod and guards both endpoints with requireInternalAuth.
Note:
metricsQuerySchema is written with ^\\d{4}-\\d{2}-\\d{2}$, so the literal regex expects escaped \d characters instead of digits. Valid YYYY-MM-DD values are rejected at validation time, which prevents the metrics handler from executing with ordinary date inputs.
Internal Analytics Event Ingest
{
"title": "Ingest Consent Analytics Event",
"description": "Accepts a PSU consent analytics event and applies it to the analytics store after internal authentication",
"method": "POST",
"baseUrl": "<UsApiBaseUrl>",
"endpoint": "/internal/analytics/events",
"headers": [
{
"key": "x-internal-token",
"value": "<internal token>",
"required": true
},
{
"key": "Authorization",
"value": "Bearer <internal token>",
"required": false
},
{
"key": "Content-Type",
"value": "application/json",
"required": true
}
],
"queryParams": [],
"pathParams": [],
"bodyType": "json",
"requestBody": "{\n \"psu_id\": \"psu_123\",\n \"consent_session_id\": \"sess_123\",\n \"product\": \"product_a\",\n \"country\": \"US\",\n \"provider\": \"provider_a\",\n \"institution_id\": \"inst_123\",\n \"timestamp\": \"2024-01-01T00:00:00.000Z\",\n \"failure_reason\": null,\n \"event_name\": \"consent_start\"\n}",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Event applied",
"body": "{\n \"status\": \"applied\"\n}"
},
"409": {
"description": "Dimension mismatch",
"body": "{\n \"status\": \"dimension_mismatch\"\n}"
},
"400": {
"description": "Invalid body",
"body": "{\n \"error\": {\n \"code\": \"INVALID_BODY\",\n \"message\": \"Invalid body payload\",\n \"details\": \"Validation failed\"\n },\n \"request_id\": \"req_123\"\n}"
}
}
}
Route behavior:
- Validates the body against
eventSchema.
- Calls
applyConsentEvent(pool, parsed.data).
- Returns
409 with { status: 'dimension_mismatch' } when the store reports a dimension mismatch.
- Returns
{ status: result.status } for normal success.
Internal PSU Consent Metrics
{
"title": "Get PSU Consent Metrics",
"description": "Fetches daily, funnel, failure, and latency analytics for a date range after internal authentication",
"method": "GET",
"baseUrl": "<UsApiBaseUrl>",
"endpoint": "/internal/analytics/psu-consent/metrics",
"headers": [
{
"key": "x-internal-token",
"value": "<internal token>",
"required": true
},
{
"key": "Authorization",
"value": "Bearer <internal token>",
"required": false
}
],
"queryParams": [
{
"key": "start_date",
"value": "2024-01-01",
"required": true
},
{
"key": "end_date",
"value": "2024-01-07",
"required": true
},
{
"key": "product",
"value": "product_a",
"required": false
},
{
"key": "country",
"value": "US",
"required": false
},
{
"key": "provider",
"value": "provider_a",
"required": false
},
{
"key": "institution_id",
"value": "inst_123",
"required": false
}
],
"pathParams": [],
"bodyType": "none",
"requestBody": "",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Metrics fetched",
"body": "{\n \"daily\": [],\n \"funnel\": [],\n \"failures\": [],\n \"latency\": []\n}"
},
"400": {
"description": "Invalid query",
"body": "{\n \"error\": {\n \"code\": \"INVALID_QUERY\",\n \"message\": \"start_date must be <= end_date\",\n \"details\": \"Validation failed\"\n },\n \"request_id\": \"req_123\"\n}"
}
}
}
Route behavior:
- Validates the query with
metricsQuerySchema.
- Normalizes
start_date and end_date to UTC midnight.
- Rejects inverted ranges where
start_date > end_date.
- Executes
fetchDailyMetrics, fetchFunnelMetrics, fetchFailureBreakdown, and fetchLatencyMetrics in parallel with Promise.all.
- Returns a single object with
daily, funnel, failures, and latency.
Local Postgres Wiring and Test Harness
The operational code is designed to run against a shared Postgres pool while allowing test-specific pool injection.
| File |
Wiring Detail |
services/us-api/src/jobs/dailyPsuConsentMetrics.ts |
Accepts poolOverride?: Pool and falls back to the shared pool. |
services/us-api/src/jobs/psuConsentTimeoutWatchdog.ts |
Accepts poolOverride?: Pool and falls back to the shared pool. |
services/us-api/src/routes/internalAnalytics.ts |
Uses the shared pool for event ingestion and metrics queries. |
services/us-api/test/psuConsentAnalytics.test.ts |
Uses pg-mem to create a PostgreSQL-compatible test pool and applies ../migrations/001_create_psu_consent_analytics.sql. |
The tests exercise:
- Idempotent event ingestion
- Terminal-state precedence
- First-write-wins behavior on timestamps
- Daily metric aggregation
- Timeout watchdog behavior
Error Handling
The codebase uses explicit API errors for expected control flow and a single global error handler for serialization.
Error Codes Observed in Source
TOKEN_REQUIRED, INVALID_TOKEN, PARTNER_AUTH_REQUIRED, FORBIDDEN, REAUTH_REQUIRED, CONSENT_REVOKED, REFRESH_LIMIT_EXCEEDED, LEGAL_RESTRICTION, NOT_FOUND, INVALID_BODY, INVALID_QUERY, PROVIDER_UNAVAILABLE
Service and Middleware Error Behavior
| Component |
Behavior |
requireAccessToken |
Converts any token verification failure into 403 INVALID_TOKEN. |
requirePartnerAuth |
Converts missing or invalid partner tokens into 403 PARTNER_AUTH_REQUIRED. |
requireInternalAuth |
Returns 403 FORBIDDEN when the internal token is not valid. |
ensureConsentActive |
Rejects inactive or expired consent with 409 CONSENT_REVOKED. |
refreshToken |
Rejects invalid refresh tokens with 403 LEGAL_RESTRICTION and blocked refresh windows with 429 REFRESH_LIMIT_EXCEEDED. |
dispatchWebhook |
Converts outbound delivery failures into 502 PROVIDER_UNAVAILABLE. |
errorHandler |
Serializes ApiError instances and maps unexpected errors to a generic 500 response. |
Deployment Readiness Notes
The visible runtime wiring shows a service that depends on:
- Environment-delivered JWT key material
- Partner API key material
- An internal API token
- A PostgreSQL-backed Prisma data layer
- Scheduled execution for background jobs
- An optional external scoring callback
- Outbound webhook endpoints for consent lifecycle events
The operational code also exposes clear boundaries between runtime paths:
- Request-time auth and consent checks happen before data access.
- Observability is added after the response through the audit hook.
- Background jobs can be invoked as direct Node processes or through an external scheduler.
- Metrics and governance flows depend on Postgres tables and materialized state rather than ephemeral in-memory state.
Dependencies
Runtime Packages Referenced in Source
fastify
jsonwebtoken
@prisma/client
pg
zod
crypto
fetch via the runtime
Operational and Data Dependencies
- PostgreSQL via
pg.Pool and Prisma
- JWT private and public keys
- Partner API keys
- Internal API token
- Optional scoring callback URL
- Outbound partner webhook endpoints
Key Classes Reference
| Class |
Responsibility |
config.ts |
Centralized runtime configuration for JWT, partner auth, internal auth, TTLs, and callback URLs. |
accessToken.ts |
Verifies access tokens and injects consent claims into the request context. |
partnerAuth.ts |
Authorizes partner requests using partner API keys and records the resolved partner token. |
internalAuth.ts |
Protects internal routes with a shared internal token. |
requestId.ts |
Ensures request ID propagation across request and response contexts. |
auditLogger.ts |
Writes response access logs and disables itself on database initialization failure. |
errorHandler.ts |
Serializes API and unexpected errors into structured JSON. |
consentService.ts |
Creates, revokes, and reads consent state while enforcing active consent rules. |
tokenService.ts |
Issues, refreshes, and introspects JWT-backed token pairs. |
connectionService.ts |
Evaluates connection readiness and refreshes connection timestamps and status. |
featureService.ts |
Computes cashflow features and persists evidence snapshots. |
creditFeatureSchema.ts |
Defines the global credit feature schema and migration behavior. |
modelGovernanceService.ts |
Manages feature schema registration, drift detection, retraining triggers, and model lineage. |
scoringService.ts |
Validates, stores, and replays decisions. |
webhookService.ts |
Signs and dispatches outbound webhook events. |
internalAnalytics.ts |
Registers internal analytics ingestion and metrics endpoints. |
dailyPsuConsentMetrics.ts |
Runs daily consent metrics backfill jobs. |
psuConsentTimeoutWatchdog.ts |
Detects and marks stale PSU consent sessions. |
featureDriftJob.ts |
Runs the daily feature drift check. |
retrainTriggerJob.ts |
Evaluates retraining triggers for a model artifact. |
mockProvider.ts |
Supplies deterministic synthetic account, balance, transaction, and income data for feature computation. |