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.
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

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).

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

evaluateRetrainingForModel

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

DriftInput

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.

PerformanceThresholds

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.
{
    "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.