Deployment, Operations, and Observability - Service-specific deployment readiness gaps and ownership boundaries

Overview

This page separates the repo into deployment surfaces that do not share the same promotion path. The key boundary is between the main application stack, the US consent/data services, and the smaller support runtimes that are deployed and operated with different expectations.

The clearest split in the repo is between services/us-api and services/us-data-gateway: the US API owns consent, token, scoring, analytics, and audit logging; the Go data gateway owns a narrower consent-scoped data read boundary with Redis-backed token verification and its own rollout concerns. The section also treats platform/housing-label-service as a separate Node/Prisma runtime with its own tests, so operators do not assume it follows the same promotion path as the main compose-managed services.

Architecture Overview

flowchart TB
    subgraph MainStack[Main Application Stack]
        Frontend[frontend Next.js routes]
        Backend[backend Python support scripts]
        UsApi[services us-api Fastify runtime]
    end

    subgraph ConsentBoundary[Consent Scoped Data Boundary]
        UsDataGateway[services us-data-gateway Go runtime]
        RedisCache[Redis session cache]
        PgxDb[Postgres data store]
    end

    subgraph OpsSurface[Operations and Observability]
        AuditLogger[auditLogger middleware]
        RequestId[requestId middleware]
        Jobs[US API jobs]
    end

    subgraph SeparateRuntime[Separate Service Runtime]
        HousingLabel[platform housing-label-service]
        HousingTests[service tests]
    end

    Frontend --> UsApi
    UsApi --> PgxDb
    UsApi --> AuditLogger
    UsApi --> RequestId
    UsApi --> Jobs
    UsDataGateway --> RedisCache
    UsDataGateway --> PgxDb
    HousingLabel --> HousingTests

Service Readiness Snapshot

Surface Runtime and Entry Point Readiness Signal in Repo Ownership Boundary Operational Note
platform/housing-label-service Node and Prisma runtime with its own tests Explicitly separated service runtime Own deployment lane Do not promote as part of the main compose stack
services/us-api Fastify service with jobs, middleware, Prisma, and pg-backed analytics Dev and prod Docker patterns are well-formed, but production deployment configuration is still called out as incomplete Owns consent, scoring, model governance, and audit logging Promotion includes operational jobs and analytics state
services/us-data-gateway Go HTTP service with pgx, Redis, and JWT verification Smaller consent-scoped boundary with its own runtime wiring Owns data read access for consent-scoped endpoints Requires separate rollout sequencing from the main stack
backend Python utility surface Used as a client-side validation and smoke helper Consumer of application APIs Not a service promotion target in this section
frontend Next.js routes and user-facing orchestration Acts as a proxy and UI boundary Owns browser-facing route handlers and fallback persistence Route updates can fail independently of backend/service rollouts

Deployment Ownership Boundaries

Boundary What It Owns What Operators Should Not Assume
US API Consent lifecycle, token issuance, replay, scoring, analytics jobs, audit logging That it is promoted with the same cadence as the Go gateway or the housing-label service
US Data Gateway Consent-scoped read APIs, JWT verification, Redis session lookup, consent validation That it shares the main compose promotion path or the same runtime dependencies as Fastify services
Frontend Browser-facing orchestration and route-level fallbacks That route proxies imply ownership of backend data state
Backend support scripts API smoke tooling and application validation That script execution is equivalent to service deployment
Housing label service Its own Node/Prisma runtime and tests That it is part of the main stack’s rollout unit

US API Runtime, Jobs, and Operational Controls

Middleware and Request Enforcement

Access Claims

[!IMPORTANT] services/us-api already expresses operational behavior in code through jobs, auth middleware, and audit hooks, but the repo also calls out that it still lacks a fully defined production deployment configuration. The deployment story is therefore service-specific, not uniform. [!NOTE] In services/us-data-gateway/cmd/us-data-gateway/main.go, both the case "mock" and the default branch select provider.MockProvider{}. The PROVIDER setting does not switch the active data provider away from the mock implementation in this binary.

services/us-api/src/middleware/accessToken.ts

Property Type Description
consent_id string Consent identifier extracted from the JWT payload
purpose Purpose Consent purpose claim
data_categories DataCategory[] Allowed data categories claim
jti string JWT identifier used for token correlation

Public Methods

Method Description
requireAccessToken Accepts a bearer token, x-access-token, or access_token query value; verifies RS256 signatures and populates request.accessClaims
requirePartnerAuth Accepts a bearer token, x-partner-token, x-api-key, or partner_token query value; validates against configured partner API keys and sets request.partnerId
requireInternalAuth Accepts x-internal-token or bearer token; validates against the configured internal API token
ensureRequestId Reuses x-request-id or generates one, writes it back to the request and the X-Request-Id response header
errorHandler Serializes ApiError responses and wraps unexpected errors as a PROVIDER_UNAVAILABLE failure

Request Carrier Rules

Middleware Accepted Token Carriers Runtime Effect
requireAccessToken Authorization: Bearer, x-access-token, access_token query Fills request.accessClaims
requirePartnerAuth Authorization: Bearer, x-partner-token, x-api-key, partner_token query Fills request.partnerId
requireInternalAuth x-internal-token, Authorization: Bearer Allows internal analytics routes
ensureRequestId x-request-id or generated UUID Normalizes correlation headers for logs and responses

Audit Logging

Audit Logger

services/us-api/src/middleware/auditLogger.ts

Property Type Description
auditLoggingEnabled boolean Process-wide switch that disables audit writes after a Prisma initialization failure
auditLoggingDisabledLogged boolean Guards the one-time warning emitted when audit logging is disabled
Method Description
registerAuditLogger Registers an onResponse hook that writes access log rows through Prisma

The hook records:

  • 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

Error Shaping

Error Handler

[!CAUTION] When Prisma throws PrismaClientInitializationError during access log creation, the hook turns off audit logging for the rest of the process and logs a warning once.

services/us-api/src/middleware/errorHandler.ts

Method Description
errorHandler Returns structured JSON for ApiError instances and a 500-level fallback for unexpected failures

Operational response shape:

{
  "error": {
    "code": "INVALID_TOKEN",
    "message": "Invalid token",
    "details": null
  },
  "request_id": "req_123"
}

Operational Jobs

Public Methods

Method Description
runDailyPsuConsentMetricsJob Refreshes daily PSU consent metrics for a computed lookback window and run date
runDailyFeatureDriftCheck Runs drift detection for US_CASHFLOW_V1 with the global schema version
runPsuConsentTimeoutWatchdog Scans consent sessions and emits timeout events for stale sessions
evaluateRetrainingForModel Delegates retraining trigger evaluation to model governance

Job Inputs and Runtime Controls

Job Environment Inputs Behavior
runDailyPsuConsentMetricsJob LOOKBACK_DAYS, RUN_DATE Uses refreshDailyMetricsForRange with a date window
runPsuConsentTimeoutWatchdog PROVIDER_TIMEOUT_MINUTES, DEFAULT_TIMEOUT_MINUTES Computes per-provider deadlines and applies consent_timeout events
runDailyFeatureDriftCheck none in the job wrapper Uses the global feature schema version and sampleLimit: 500
evaluateRetrainingForModel thresholds can be passed into evaluateRetrainingTriggers Evaluates AUC and drift thresholds

services/us-api/src/services/consentService.ts

Method Description
createConsent Creates a consent row, writes a CREATED consent log entry, and derives expiresAt from explicit or duration-based payload fields
revokeConsent Marks consent as REVOKED, revokes tokens, disconnects connections, writes a REVOKED log entry, and dispatches a webhook
getConsentReceipt Returns consent receipt data from the persisted consent row
ensureConsentActive Rejects revoked or expired consents with CONSENT_REVOKED

Token Service

services/us-api/src/services/tokenService.ts

Method Description
exchangeToken Validates the link token when present, activates pending consent, issues access and refresh tokens, and dispatches a consent_activated webhook
refreshToken Validates the stored refresh token hash, enforces refresh limits, and issues a new token pair
introspectToken Verifies JWT claims and token state, then returns active or inactive introspection metadata

Scoring Service

services/us-api/src/services/scoringService.ts

Method Description
validateDecision Enforces deny reason allowlist rules for DENY decisions
storeDecision Persists a decision, stores model lineage when supplied, and resolves the schema version from the payload or evidence
replayDecision Replays a stored decision through the configured scoring callback when present, or returns the persisted decision and audit bundle

Feature Service

services/us-api/src/services/featureService.ts

Method Description
computeCashflow Derives cashflow features from the mock provider, migrates them to the global schema, persists an evidence snapshot, and returns the normalized feature set
fetchEvidence Loads an evidence snapshot by reference

Connection Service

services/us-api/src/services/connectionService.ts

Method Description
ensureConnectionsReady Reads consent-linked connections and returns ACTIVE, DEGRADED, or throws REAUTH_REQUIRED based on stored connection status
recordConnectionRefresh Marks all consent-linked connections as ACTIVE and updates their refresh time

Model Governance

Global Feature Schema and Migration Results

services/us-api/src/models/creditFeatureSchema.ts

Type Property Type Description
GlobalCreditFeatureSchemaV1 schema_version typeof GLOBAL_CREDIT_FEATURE_SCHEMA_VERSION Canonical schema version
GlobalCreditFeatureSchemaV1 income_monthly_avg_usd number Monthly income average
GlobalCreditFeatureSchemaV1 income_stability_index number Income stability score
GlobalCreditFeatureSchemaV1 nsf_overdraft_count_180d number NSF and overdraft count
GlobalCreditFeatureSchemaV1 balance_min_30d_usd number Minimum 30-day balance
GlobalCreditFeatureSchemaV1 rent_payment_detected boolean Rent payment indicator
GlobalCreditFeatureSchemaV1 debt_payment_ratio_est number Estimated debt payment ratio
FeatureMigrationResult schema_version typeof GLOBAL_CREDIT_FEATURE_SCHEMA_VERSION Output schema version
FeatureMigrationResult features GlobalCreditFeatureSchemaV1 Migrated feature payload
FeatureMigrationResult migration_notes string[] Defaulting and compatibility notes

Public Methods

Method Description
ensureFeatureSchemaVersion Ensures the featureSchemaVersion row for global-credit-v1 exists
runFeatureDriftDetection Loads a baseline, computes live distribution statistics from evidence snapshots, and persists a drift report
evaluateRetrainingTriggers Evaluates model performance and drift thresholds, and creates a pending retraining trigger when needed
recordModelLineage Persists a model artifact and marks a deployment as ACTIVE with decision-ingest metadata

Thresholds Used by Retraining Evaluation

Threshold Value Purpose
aucMin 0.72 Minimum acceptable AUC
driftScoreMax 0.3 Maximum acceptable drift score

Webhook Delivery

Webhook Event

services/us-api/src/webhooks/webhookService.ts

Property Type Description
event string Event type dispatched to partner webhooks
payload Record<string, unknown> Event body sent to subscribers

Public Methods

Method Description
dispatchWebhook Finds active partner webhook endpoints, creates delivery records, signs payloads, and posts the event body
signPayload Creates the X-Webhook-Signature HMAC for the outgoing payload

Delivery Fields Written by dispatchWebhook

  • Delivery ID prefix: whd_
  • status: PENDING, then DELIVERED or FAILED
  • Headers sent: Content-Type, X-Webhook-Signature, Idempotency-Key

US API Operational State

stateDiagram-v2
    [*] --> PENDING_USER_ACTION : createConsent
    PENDING_USER_ACTION --> ACTIVE : exchangeToken
    ACTIVE --> REVOKED : revokeConsent
    ACTIVE --> REVOKED : expired
    REVOKED --> [*]

Connection Readiness State

Status Meaning in Code
ACTIVE Connections are usable and refreshed
REAUTH_REQUIRED A stored connection requires reauthentication and ensureConnectionsReady throws REAUTH_REQUIRED
DEGRADED At least one connection is degraded
DISCONNECTED Used when consent revocation disconnects all linked connections

US API Operational Flow

sequenceDiagram
    participant Client as Client
    participant Fastify as Fastify Route
    participant ReqId as ensureRequestId
    participant Auth as requirePartnerAuth or requireAccessToken
    participant Service as Consent or Token Service
    participant DB as Prisma
    participant Audit as registerAuditLogger

    Client->>Fastify: HTTP request
    Fastify->>ReqId: on request
    ReqId-->>Fastify: x-request-id set
    Fastify->>Auth: preHandler
    Auth-->>Fastify: claims or partner id stored
    Fastify->>Service: business action
    Service->>DB: read or write
    DB-->>Service: rows
    Service-->>Fastify: response body
    Fastify->>Audit: onResponse
    Audit->>DB: accessLog create
    DB-->>Audit: write result
    Fastify-->>Client: JSON response

Configuration

Config

services/us-data-gateway/internal/config/config.go

Property Type Description
Port string HTTP listen port, default 8084
DatabaseURL string Postgres connection string
RedisURL string Redis endpoint used by the token verifier
JWTPublicKey string RSA public key for token verification
Provider string Provider selector, default mock

Auth and Session Verification

Claims

services/us-data-gateway/internal/auth/auth.go

Property Type Description
ConsentID string Consent identifier stored in the JWT cid claim
Purpose string JWT pur claim
Categories []string JWT cat claim
RegisteredClaims jwt.RegisteredClaims Embedded JWT metadata, including ID used for Redis session lookup

Public Methods

Method Description
Verify Verifies the JWT signature, checks the Redis session record at session:<claims.ID>, and rejects revoked sessions

Handler Wiring

Handler

services/us-data-gateway/internal/handlers/handlers.go

Property Type Description
DB *pgxpool.Pool Postgres pool used for consent lookups
Provider provider.Provider Data provider abstraction
Auth auth.TokenVerifier JWT and Redis-backed token verifier

Public Methods

Method Description
Accounts Returns consent-scoped accounts after auth, category, and consent checks
Balances Returns consent-scoped balances after auth, category, and consent checks
Transactions Returns consent-scoped transactions after auth, category, and consent checks
TransactionsSync Returns consent-scoped transaction sync data after auth, category, and consent checks
Income Returns consent-scoped income after auth, category, and consent checks

Data Models

Account

services/us-data-gateway/internal/provider/provider.go

Property Type Description
AccountToken string Provider account token
Name string Account display name
Type string Account type
Mask string Account mask

Balance

Property Type Description
AccountToken string Provider account token
Available float64 Available balance
Current float64 Current balance
Currency string Currency code

Transaction

Property Type Description
TransactionID string Transaction identifier
AccountToken string Provider account token
Amount float64 Transaction amount
Currency string Currency code
PostedAt string ISO timestamp
MerchantName string Merchant name
MerchantCategory string Merchant category

TransactionRemoval

Property Type Description
TransactionID string Removed transaction identifier

TransactionSync

Property Type Description
Added []Transaction Newly added transactions
Modified []Transaction Modified transactions
Removed []TransactionRemoval Removed transactions
NextCursor string Sync cursor to continue the stream

Income

Property Type Description
IncomeID string Income item identifier
Amount float64 Income amount
Currency string Currency code
PayDate string ISO pay date

Provider Interface

services/us-data-gateway/internal/provider/provider.go

Method Description
FetchAccounts Returns accounts for a consent ID
FetchBalances Returns balances for a consent ID
FetchTransactions Returns transactions for a consent ID and date range
FetchTransactionsSync Returns sync data for a consent ID and cursor
FetchIncome Returns income records for a consent ID and lookback window

MockProvider

services/us-data-gateway/internal/provider/mock.go

Method Description
FetchAccounts Returns two mock depository accounts
FetchBalances Returns mock balances for the two accounts
FetchTransactions Returns mock rent and debt transactions
FetchTransactionsSync Returns mock sync deltas and a next cursor
FetchIncome Returns mock income history

US Data Gateway API Endpoints

Get Accounts

{
    "title": "Get Accounts",
    "description": "Returns consent-scoped accounts after JWT, Redis session, and consent checks",
    "method": "GET",
    "baseUrl": "<UsDataGatewayBaseUrl>",
    "endpoint": "/api/v1/us/data/accounts",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <token>",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Success",
            "body": "{\n    \"accounts\": [\n        {\n            \"account_token\": \"acct_tok_1\",\n            \"name\": \"Checking\",\n            \"type\": \"depository\",\n            \"mask\": \"1234\"\n        }\n    ]\n}"
        },
        "403": {
            "description": "Forbidden",
            "body": "{\n    \"error\": \"TOKEN_REQUIRED\"\n}"
        },
        "409": {
            "description": "Consent revoked",
            "body": "{\n    \"error\": \"CONSENT_REVOKED\"\n}"
        }
    }
}

Get Balances

{
    "title": "Get Balances",
    "description": "Returns consent-scoped balances after JWT, Redis session, and consent checks",
    "method": "GET",
    "baseUrl": "<UsDataGatewayBaseUrl>",
    "endpoint": "/api/v1/us/data/balances",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <token>",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Success",
            "body": "{\n    \"balances\": [\n        {\n            \"account_token\": \"acct_tok_1\",\n            \"available\": 1200,\n            \"current\": 1500,\n            \"currency\": \"USD\"\n        }\n    ]\n}"
        },
        "403": {
            "description": "Forbidden",
            "body": "{\n    \"error\": \"TOKEN_REQUIRED\"\n}"
        },
        "409": {
            "description": "Consent revoked",
            "body": "{\n    \"error\": \"CONSENT_REVOKED\"\n}"
        }
    }
}

Get Transactions

{
    "title": "Get Transactions",
    "description": "Returns consent-scoped transactions after JWT, Redis session, and consent checks",
    "method": "GET",
    "baseUrl": "<UsDataGatewayBaseUrl>",
    "endpoint": "/api/v1/us/data/transactions",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <token>",
            "required": true
        }
    ],
    "queryParams": [
        {
            "name": "from",
            "required": false,
            "description": "Start date passed to the provider"
        },
        {
            "name": "to",
            "required": false,
            "description": "End date passed to the provider"
        }
    ],
    "pathParams": [],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Success",
            "body": "{\n    \"transactions\": [\n        {\n            \"transaction_id\": \"txn_1\",\n            \"account_token\": \"acct_tok_1\",\n            \"amount\": 1200,\n            \"currency\": \"USD\",\n            \"posted_at\": \"2024-10-01T00:00:00Z\",\n            \"merchant_name\": \"Rent Co\",\n            \"merchant_category\": \"RENT\"\n        }\n    ]\n}"
        },
        "403": {
            "description": "Forbidden",
            "body": "{\n    \"error\": \"TOKEN_REQUIRED\"\n}"
        },
        "409": {
            "description": "Consent revoked",
            "body": "{\n    \"error\": \"CONSENT_REVOKED\"\n}"
        }
    }
}

Get Transaction Sync

{
    "title": "Get Transaction Sync",
    "description": "Returns sync deltas after JWT, Redis session, and consent checks",
    "method": "GET",
    "baseUrl": "<UsDataGatewayBaseUrl>",
    "endpoint": "/api/v1/us/data/transactions/sync",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <token>",
            "required": true
        }
    ],
    "queryParams": [
        {
            "name": "cursor",
            "required": false,
            "description": "Provider sync cursor"
        }
    ],
    "pathParams": [],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Success",
            "body": "{\n    \"added\": [\n        {\n            \"transaction_id\": \"txn_3\",\n            \"account_token\": \"acct_tok_2\",\n            \"amount\": 45,\n            \"currency\": \"USD\",\n            \"posted_at\": \"2024-10-03T00:00:00Z\",\n            \"merchant_name\": \"Coffee\",\n            \"merchant_category\": \"FOOD\"\n        }\n    ],\n    \"modified\": [\n        {\n            \"transaction_id\": \"txn_2\",\n            \"account_token\": \"acct_tok_1\",\n            \"amount\": 90,\n            \"currency\": \"USD\",\n            \"posted_at\": \"2024-10-02T00:00:00Z\",\n            \"merchant_name\": \"Card\",\n            \"merchant_category\": \"DEBT\"\n        }\n    ],\n    \"removed\": [\n        {\n            \"transaction_id\": \"txn_4\"\n        }\n    ],\n    \"next_cursor\": \"cursor_next_1\"\n}"
        },
        "403": {
            "description": "Forbidden",
            "body": "{\n    \"error\": \"TOKEN_REQUIRED\"\n}"
        },
        "409": {
            "description": "Consent revoked",
            "body": "{\n    \"error\": \"CONSENT_REVOKED\"\n}"
        }
    }
}

Get Income

{
    "title": "Get Income",
    "description": "Returns consent-scoped income after JWT, Redis session, and consent checks",
    "method": "GET",
    "baseUrl": "<UsDataGatewayBaseUrl>",
    "endpoint": "/api/v1/us/data/income",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <token>",
            "required": true
        }
    ],
    "queryParams": [
        {
            "name": "lookback_days",
            "required": false,
            "description": "Lookback window passed to the provider"
        }
    ],
    "pathParams": [],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Success",
            "body": "{\n    \"income\": [\n        {\n            \"income_id\": \"inc_1\",\n            \"amount\": 5100,\n            \"currency\": \"USD\",\n            \"pay_date\": \"2024-09-30T00:00:00Z\"\n        }\n    ]\n}"
        },
        "403": {
            "description": "Forbidden",
            "body": "{\n    \"error\": \"TOKEN_REQUIRED\"\n}"
        },
        "409": {
            "description": "Consent revoked",
            "body": "{\n    \"error\": \"CONSENT_REVOKED\"\n}"
        }
    }
}

US Data Gateway Request Flow

sequenceDiagram
    participant Client as Client
    participant Mux as HTTP ServeMux
    participant H as Handler
    participant Auth as TokenVerifier
    participant Redis as Redis
    participant DB as Postgres
    participant Provider as MockProvider

    Client->>Mux: GET /api/v1/us/data/transactions
    Mux->>H: Transactions
    H->>Auth: Verify
    Auth->>Redis: HGetAll session claims id
    Redis-->>Auth: session state
    Auth-->>H: claims
    H->>DB: SELECT consent row
    DB-->>H: consent status and expiry
    H->>Provider: FetchTransactions
    Provider-->>H: transactions
    H-->>Client: JSON response

Observability Services

Request ID Propagation

Public Method

Method Description
ensureRequestId Normalizes or generates correlation IDs and echoes them back as X-Request-Id

The same request ID is later used by:

  • errorHandler in error responses
  • registerAuditLogger in access log rows
  • US data gateway logs via request.Header.Get("X-Request-Id")

Audit Log Persistence

Data Flow

Step Effect
Request completes registerAuditLogger runs on onResponse
Request metadata is collected x-request-id, partnerId, consentId, route, status code
Prisma write prisma.accessLog.create writes the row
Failure mode Prisma init errors disable logging; other errors are warned and skipped

Redis Session Cache

TokenVerifier Cache Contract

Key Pattern Value Shape Purpose
session:<claims.ID> Redis hash Stores session state for JWT verification
revoked string flag Determines whether the token is rejected
Method Description
Verify Reads the session hash for the token’s JWT ID and rejects revoked sessions

Peripheral Deployment and Verification Surfaces

Backend Smoke Script

backend/src/scripts/create_test_application.py

This script is a deployment validation helper rather than a service runtime. It uses:

  • APPLICATIONS_API_BASE_URL
  • APPLICATIONS_API_TOKEN

It performs:

  1. POST /v1/applications
  2. GET /v1/applications/{application_id}

The script prints:

  • application_id
  • credit_score
  • login_credentials
  • detail_url

Frontend Route Boundary

The frontend exposes route-level orchestration that can update application status and proxy backend data requests. The important deployment boundary is that these handlers can fall back to local storage or backend retry logic independently of service rollout state.

Testing and Verification

US API Tests

File Verified Behavior
services/us-api/test/flows.test.ts Consent creation, revocation, refresh limit enforcement, and category-based authorization failures
services/us-api/test/psuConsentAnalytics.test.ts Analytics idempotency, first-terminal-wins behavior, first-write-wins timestamps, daily metric aggregation, and timeout watchdog emission

US Data Gateway Tests

File Verified Behavior
services/us-data-gateway/internal/handlers/handlers_test.go CATEGORY_NOT_ALLOWED returns 403 and CONSENT_REVOKED returns 409 in JSON form

Deployment-Relevant Scenarios

  • runPsuConsentTimeoutWatchdog against stale sessions and provider-specific timeout maps
  • registerAuditLogger behavior when Prisma initialization fails
  • TokenVerifier.Verify against revoked Redis sessions
  • dispatchWebhook failure handling for partner callback delivery

Dependencies

  • pg / Pool in US API job runners
  • Prisma client in US API consent, scoring, governance, webhook, and audit paths
  • pgxpool in the Go data gateway
  • Redis in the Go data gateway token verifier
  • RS256 JWT signing and verification in both services
  • fetch for webhook delivery and scoring callback replay
  • Next.js route handlers in the frontend boundary
  • Python urllib in the backend validation script

Key Classes Reference

Class Location Responsibility
TokenVerifier auth.go Verifies JWTs and consults Redis session state
Handler handlers.go Serves consent-scoped US data endpoints
Config config.go Loads Go gateway runtime configuration
Claims auth.go Holds gateway JWT claims
Account provider.go Represents a gateway account payload
Balance provider.go Represents a gateway balance payload
Transaction provider.go Represents a gateway transaction payload
TransactionSync provider.go Represents sync deltas and cursor state
Income provider.go Represents a gateway income payload
AccessClaims accessToken.ts Holds US API access-token claims
GlobalCreditFeatureSchemaV1 creditFeatureSchema.ts Canonical US credit feature schema
FeatureMigrationResult creditFeatureSchema.ts Result of schema migration
DecisionPayload scoringService.ts Stored and replayed decision payload
TokenPair tokenService.ts Access and refresh token pair
CreateConsentPayload consentService.ts Consent creation input
WebhookEvent webhookService.ts Webhook event envelope
AccountCoverageResult account_detection.py Coverage inference output
create_test_application.py create_test_application.py Backend smoke and validation helper