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 |
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 |
Consent, Token, and Scoring Services
Consent Service
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
Consent 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
US Data Gateway Consent Boundary
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:
POST /v1/applications
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 |