Deployment, Operations, and Observability - Production topology, edge routing, and traffic segmentation

documents/deployment.md · platform/deployment/prod/docker-compose.yml · platform/deployment/prod/Caddyfile

Overview

This production setup places Fastly and the Google Cloud HTTPS Load Balancer in front of a Docker Compose runtime that hosts the frontend, backend, and supporting services on a Compute Engine instance. The deployment guide defines the public edge, the origin split, and the service ports that receive browser traffic: frontend UI traffic is exposed separately from backend API traffic, and Fastly is configured to cache static assets while bypassing API paths.

The important operational detail in this repository is that request handling is split twice. First, the public edge separates browser page traffic from API traffic. Second, the production Caddy layer inside the Compose stack separates traffic between the frontend app on frontend:3000 and the backend API on backend:8000, which is how the live request flow reaches the route handlers in frontend/app/api/... and the FastAPI endpoints in backend/src/interface/....

Production Topology

[!NOTE] documents/deployment.md describes the frontend as React with Vite and uses VITE_BACKEND_API_URL, but the checked-in runtime route handlers live under frontend/app/... and use Next.js App Router APIs such as NextRequest, NextResponse, and next/headers. For production operations, the live path follows the Next.js container and its route handlers. [!NOTE] The documented Google Cloud HTTPS Load Balancer rule sends external /api/* traffic to mvp-backend-api on port 8000. The frontend-owned route handlers under frontend/app/api/... therefore serve internal same-origin calls or direct origin hits, not the external /api/* path that the load balancer forwards to backend.

The production topology is defined by three layers:

  1. Fastly fronts app.joinlita.com, terminates TLS at the edge, and caches static assets.
  2. Google Cloud HTTPS Load Balancer receives Fastly origin traffic and splits requests by path.
  3. Docker Compose on Compute Engine runs the frontend, backend, and support services behind Caddy and the internal service ports.

Edge and origin responsibilities

Layer Responsibility Evidence in repo
Fastly Public edge, TLS termination, static asset caching, API bypass documents/deployment.md
Google Cloud HTTPS Load Balancer Path-based origin routing to frontend or backend service documents/deployment.md
Caddy Internal HTTP reverse proxy between frontend:3000 and backend:8000 platform/deployment/prod/Caddyfile
Frontend service Next.js page routes and frontend-owned API handlers frontend/app/...
Backend service FastAPI API routes, external integrations, batch ingestion backend/src/interface/...
MySQL Persistent application and ingestion storage platform/deployment/prod/docker-compose.yml

Documented path split

Request family Public edge handling Runtime owner Notes
Static assets Cached by Fastly Frontend Build outputs are eligible for caching
Page routes Sent through the frontend origin frontend:3000 Browser page traffic stays in the frontend stack
GET /api/v1/applicants/{id}/account-coverage Routed through the production API path Frontend route handler, then backend API Frontend handler proxies to backend and relays the JSON payload
GET /api/v1/applicants/{id}/transactions Routed through the production API path Frontend route handler Frontend handler aggregates backend data and stored submissions
POST /api/transunion/batch-ingestions Routed through the production API path Backend API Ingests and summarizes TransUnion batch rows
/api/saltedge/* Routed through the API path family Backend API with frontend proxy entrypoints Frontend proxy routes exist, while backend handlers own the provider logic

Architecture Overview

flowchart TB
    subgraph EdgeLayer[Public Edge]
        Fastly[Fastly]
        GCLB[Google Cloud HTTPS Load Balancer]
    end

    subgraph ProdHost[Compute Engine Production Host]
        Caddy[Caddy]
        subgraph FrontendRuntime[Frontend Service]
            Frontend3000[frontend port 3000]
            FrontendApi[frontend api routes]
        end
        subgraph BackendRuntime[Backend Service]
            Backend8000[backend port 8000]
            BackendApi[FastAPI routes]
        end
        MySQL[MySQL]
    end

    Fastly -->|static assets and browser traffic| GCLB
    GCLB -->|page routes| Caddy
    GCLB -->|api routes| Backend8000
    Caddy -->|browser pages| Frontend3000
    Caddy -->|same origin api calls| Backend8000
    FrontendApi -->|fetch backend data| Backend8000
    BackendApi -->|persistence and integrations| MySQL

Request Routing and Traffic Segmentation

The production deployment separates request responsibilities by path and by service boundary. Fastly is the outer cache and TLS layer, the load balancer makes the initial path split, and Caddy is the internal reverse proxy that keeps the frontend and backend services isolated inside Compose.

Path or surface Owner Runtime path Operational role
/ and application pages Frontend Fastly → GCLB → Caddy → frontend:3000 Browser-rendered UI
/api/v1/applicants/{id}/account-coverage Frontend route handler and backend API Browser → frontend route handler → backend API Coverage lookup and proxying
/api/v1/applicants/{id}/transactions Frontend route handler Browser → frontend route handler → backend fetches and local storage Applicant transaction history
/api/transunion/batch-ingestions Backend Browser or client → backend API Batch ingestion and sanitization
/api/saltedge/* Backend plus frontend proxy routes Browser or frontend proxy → provider-facing logic Salt Edge connection and account flows

Feature Flows

1. Page request path

sequenceDiagram
    participant U as Browser
    participant F as Fastly
    participant L as Google Cloud HTTPS Load Balancer
    participant C as Caddy
    participant N as Frontend service on 3000

    U->>F: Request page route
    F->>L: Forward origin request
    L->>C: Route non api page traffic
    C->>N: Serve Next.js page
    N-->>C: HTML and client assets
    C-->>L: Response
    L-->>F: Response
    F-->>U: Rendered page

2. Account coverage request path

sequenceDiagram
    participant U as Browser
    participant F as Frontend route handler
    participant B as Backend API
    participant P as Plaid gateway

    U->>F: GET /api/v1/applicants/id/account-coverage
    F->>B: GET /api/v1/applicants/id/account-coverage
    B->>P: get_account_balances token
    P-->>B: Detected accounts
    B-->>F: AccountCoverageResponse JSON
    F-->>U: JSON payload

3. Transaction history request path

sequenceDiagram
    participant U as Browser
    participant F as Frontend route handler
    participant B as Backend API
    participant S as Stored submissions file

    U->>F: GET /api/v1/applicants/id/transactions
    F->>B: Fetch applicant and application list
    F->>S: Read stored applications
    F->>F: Merge backend and stored records
    F-->>U: Transaction list JSON or 404

4. Submit application from the review page

The review page posts the completed payload to /api/v1/applications using a same-origin fetch with JSON headers. The public edge rule for /api/* is what makes that POST land on the API origin in production, not the frontend page origin.

sequenceDiagram
    participant U as Browser
    participant R as Review page
    participant L as Load Balancer
    participant A as Application API

    U->>R: Submit application
    R->>L: POST /api/v1/applications
    L->>A: Forward API request
    A-->>L: Created response
    L-->>R: JSON with identifier and timestamp

Component Structure

Fastly and Google Cloud HTTPS Load Balancer

These are the public edge boundaries for the production system. Fastly handles the app.joinlita.com frontage and the HTTPS origin behavior described in documents/deployment.md, while the load balancer applies the /api/* versus non-API path split.

Component Responsibility
Fastly Public TLS entrypoint and static asset cache
Google Cloud HTTPS Load Balancer Path-based origin routing to frontend or backend service
DNS Maps app.joinlita.com to the Fastly service domain and the GCP origin setup

Caddy and the production Compose runtime

Caddy is the internal request router inside the production host. The Compose stack keeps the frontend app on frontend:3000 and the backend API on backend:8000, and Caddy is the layer that separates those service targets for live traffic inside the host.

Component Responsibility
Caddy Internal reverse proxy and request splitter
frontend:3000 Next.js page rendering and frontend API route handlers
backend:8000 FastAPI business and integration endpoints
MySQL Persistent backing store for application and ingestion records

Observability and Runtime Operations

The documented operational checks in documents/deployment.md focus on the load balancer, container logs, and direct SSH access to the Compute Engine host.

Signal What it verifies Where to check
Load balancer health checks Backend and frontend origin health GCP Console, Load Balancer section
Frontend container logs Page and frontend API handler errors docker-compose -f platform/deployment/prod/docker-compose.yml logs frontend
Backend container logs API errors and integration failures docker-compose -f platform/deployment/prod/docker-compose.yml logs backend
SSH access Host-level rollout and runtime inspection gcloud compute ssh instance-20250206-052936

The runtime also emits route-level diagnostics in the handler code:

  • frontend/app/api/v1/applicants/[id]/transactions/route.ts logs warnings when backend lookup or stored-application hydration fails.
  • backend/src/interface/saltedge_endpoints.py logs cache hits, config failures, Salt Edge API failures, and unexpected exceptions.
  • backend/src/interface/transunion_batch_endpoints.py returns structured 400 and 201 responses for batch ingestion validation and completion.

CORS, TLS, and forwarded request context

[!IMPORTANT] The /api/* split at the load balancer means browser traffic that reaches the backend path never enters the frontend route handlers for those same external paths. When debugging a production request, trace whether it is served by frontend:3000 or backend:8000 before looking at the handler logs.

The deployment guide defines the only explicit origin allowlist in the provided material:

  • ALLOWED_ORIGINS=https://app.joinlita.com
  • VITE_BACKEND_API_URL=https://app.joinlita.com

TLS is handled at the edge through Fastly and the Google Cloud HTTPS Load Balancer. The frontend route handlers shown in this repository use same-origin JSON fetches and explicit Accept and Content-Type headers when they submit or proxy requests.

State Management and Cache Behavior

Salt Edge customer cache

backend/src/interface/saltedge_endpoints.py keeps a module-level cache for Salt Edge customers.

Property Type Description
data Any Cached customer list returned from the Salt Edge client
expires float Unix timestamp when the cache entry expires
Mechanism Behavior
Cache key Single global customer-list cache
TTL 60 seconds
Lock asyncio.Lock serializes refreshes
Invalidation Cache is refreshed when time.time() reaches expires

The cache is read before any remote customer-list call, and the lock prevents duplicate refreshes when multiple requests arrive together.

TransUnion ingestion states

backend/src/usecase/transunion_batch.py drives a simple ingestion lifecycle.

State Meaning
received Ingestion row accepted and persisted
processing Rows are being parsed and sanitized
completed Final summary and issue set have been written

Account coverage states

backend/src/usecase/account_detection.py returns a coverage result with status values that drive the application review workflow.

State Meaning
unknown No Plaid connections were evaluated or no detected accounts were returned
incomplete At least one detected account was missing from the submitted set
complete All detected accounts were present in the submitted set

API Surface

Frontend-owned request handlers

Get Applicant Account Coverage Proxy

{
    "title": "Get Applicant Account Coverage Proxy",
    "description": "Forwards a coverage lookup for an applicant to the backend API and returns the backend payload unchanged when the backend responds successfully.",
    "method": "GET",
    "baseUrl": "<FrontendBaseUrl>",
    "endpoint": "/api/v1/applicants/{id}/account-coverage",
    "headers": [],
    "queryParams": [],
    "pathParams": [
        {
            "name": "id",
            "type": "string",
            "required": true
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Success",
            "body": "{\n    \"application_id\": 123,\n    \"status\": \"incomplete\",\n    \"reported_accounts\": 2,\n    \"detected_accounts\": 3,\n    \"missing_accounts\": 1,\n    \"coverage_ratio\": 0.67,\n    \"details\": [\n        {\n            \"connection_name\": \"Example Bank\",\n            \"institution_name\": \"Example Bank\",\n            \"reported_accounts\": 2,\n            \"detected_accounts\": 3,\n            \"missing_accounts\": 1,\n            \"status\": \"incomplete\"\n        }\n    ],\n    \"errors\": []\n}"
        }
    }
}

Get Applicant Transactions

{
    "title": "Get Applicant Transactions",
    "description": "Aggregates transaction history for an applicant from backend data and stored submissions, then filters the combined history by date range when requested.",
    "method": "GET",
    "baseUrl": "<FrontendBaseUrl>",
    "endpoint": "/api/v1/applicants/{id}/transactions",
    "headers": [],
    "queryParams": [
        {
            "name": "start_date",
            "type": "string",
            "required": false
        },
        {
            "name": "end_date",
            "type": "string",
            "required": false
        }
    ],
    "pathParams": [
        {
            "name": "id",
            "type": "string",
            "required": true
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Success",
            "body": "{\n    \"applicant_id\": 123,\n    \"start_date\": \"2024-01-01\",\n    \"end_date\": \"2024-01-31\",\n    \"transactions\": [\n        {\n            \"amount\": -50.25,\n            \"date\": \"2024-01-31\",\n            \"currency_code\": \"USD\",\n            \"status\": \"posted\",\n            \"account_name\": \"Checking\",\n            \"connection_name\": \"Example Bank\",\n            \"description\": \"Groceries\",\n            \"categories\": [\n                \"Food and Drink\"\n            ],\n            \"provider\": \"plaid\",\n            \"metadata\": {\n                \"transaction_id\": \"tx_001\"\n            }\n        }\n    ]\n}"
        }
    }
}

Backend API handlers

Get Application Account Coverage

{
    "title": "Get Application Account Coverage",
    "description": "Evaluates whether the applicant submitted all Plaid-detected accounts for the application and returns the coverage result.",
    "method": "GET",
    "baseUrl": "<BackendBaseUrl>",
    "endpoint": "/api/v1/applicants/{application_id}/account-coverage",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <token>",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "name": "application_id",
            "type": "int",
            "required": true
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Success",
            "body": "{\n    \"application_id\": 123,\n    \"status\": \"incomplete\",\n    \"reported_accounts\": 2,\n    \"detected_accounts\": 3,\n    \"missing_accounts\": 1,\n    \"coverage_ratio\": 0.67,\n    \"details\": [\n        {\n            \"connection_name\": \"Example Bank\",\n            \"institution_name\": \"Example Bank\",\n            \"reported_accounts\": 2,\n            \"detected_accounts\": 3,\n            \"missing_accounts\": 1,\n            \"status\": \"incomplete\"\n        }\n    ],\n    \"errors\": []\n}"
        }
    }
}

Create TransUnion Batch Ingestion

{
    "title": "Create TransUnion Batch Ingestion",
    "description": "Parses a TransUnion batch file, persists the ingestion, stores sanitized rows and issues, and returns a completed ingestion summary.",
    "method": "POST",
    "baseUrl": "<BackendBaseUrl>",
    "endpoint": "/api/transunion/batch-ingestions",
    "headers": [
        {
            "key": "Content-Type",
            "value": "application/json",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [],
    "bodyType": "json",
    "requestBody": "{\n    \"file_name\": \"transunion_batch_2024_01_31.txt\",\n    \"checksum\": \"4f1d9d6a8fd7b8c1b2a3f4d5e6a7b8c9d\",\n    \"rows\": [\n        \"0001...batch line one...\",\n        \"0002...batch line two...\"\n    ],\n    \"credit_as_of_date\": \"2024-01-31\",\n    \"metadata\": {\n        \"source\": \"production-upload\",\n        \"region\": \"us\"\n    },\n    \"layout\": [\n        {\n            \"key\": \"vantage_score\",\n            \"start\": 1,\n            \"end\": 3,\n            \"normalised_key\": \"vantage_score\",\n            \"data_type\": \"integer\",\n            \"description\": \"Vantage score field\",\n            \"data_group\": \"scores\",\n            \"field_name\": \"VantageScore\",\n            \"length\": 3\n        }\n    ]\n}",
    "formData": [],
    "rawBody": "",
    "responses": {
        "201": {
            "description": "Created",
            "body": "{\n    \"ingestion_id\": 101,\n    \"status\": \"completed\",\n    \"total_rows\": 2,\n    \"processed_rows\": 2,\n    \"error_count\": 0,\n    \"credit_as_of_date\": \"2024-01-31\",\n    \"summary\": {\n        \"dataSource\": \"transunion_batch\",\n        \"totalRows\": 2,\n        \"creditModel\": \"VantageScore 4.0\",\n        \"averageCreditScore\": 712,\n        \"minCreditScore\": 705,\n        \"maxCreditScore\": 719,\n        \"creditScore\": 719,\n        \"truVisionNewAccountScore\": 840\n    },\n    \"sanitized_rows\": [\n        {\n            \"creditAsOfDate\": \"2024-01-31\",\n            \"permId\": \"***1234\",\n            \"consumerId\": \"***9876\",\n            \"sequenceNumber\": 1,\n            \"metrics\": {\n                \"vantage_score\": 719\n            }\n        }\n    ],\n    \"issues\": []\n}"
        }
    }
}

Get Salt Edge Connect URL

{
    "title": "Get Salt Edge Connect URL",
    "description": "Generates a Salt Edge connect URL for the authenticated user and returns the provider session metadata.",
    "method": "POST",
    "baseUrl": "<BackendBaseUrl>",
    "endpoint": "/api/saltedge/connect-url",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <token>",
            "required": true
        },
        {
            "key": "Content-Type",
            "value": "application/json",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [],
    "bodyType": "json",
    "requestBody": "{\n    \"return_to\": \"https://app.joinlita.com/dashboard\"\n}",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Success",
            "body": "{\n    \"connect_url\": \"https://example.saltedge.com/connect/session\",\n    \"expires_at\": \"2024-02-01T12:00:00Z\",\n    \"customer_id\": \"cust_123\"\n}"
        }
    }
}

List Salt Edge Customers

{
    "title": "List Salt Edge Customers",
    "description": "Returns the cached Salt Edge customer list when available, otherwise refreshes it from the provider.",
    "method": "GET",
    "baseUrl": "<BackendBaseUrl>",
    "endpoint": "/api/saltedge/customers",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <token>",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Success",
            "body": "{\n    \"data\": [\n        {\n            \"customer_id\": \"cust_123\",\n            \"identifier\": \"[email protected]\",\n            \"created_at\": \"2024-01-31T10:15:00Z\"\n        }\n    ]\n}"
        }
    }
}

List Salt Edge Connections

{
    "title": "List Salt Edge Connections",
    "description": "Returns the Salt Edge connections for a customer.",
    "method": "GET",
    "baseUrl": "<BackendBaseUrl>",
    "endpoint": "/api/saltedge/connections",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <token>",
            "required": true
        }
    ],
    "queryParams": [
        {
            "name": "customer_id",
            "type": "string",
            "required": true
        }
    ],
    "pathParams": [],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Success",
            "body": "{\n    \"data\": [\n        {\n            \"id\": \"conn_123\",\n            \"provider_name\": \"Example Bank\"\n        }\n    ]\n}"
        }
    }
}

List Salt Edge Accounts

{
    "title": "List Salt Edge Accounts",
    "description": "Returns the accounts for a specific Salt Edge customer and connection.",
    "method": "GET",
    "baseUrl": "<BackendBaseUrl>",
    "endpoint": "/api/saltedge/accounts",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <token>",
            "required": true
        }
    ],
    "queryParams": [
        {
            "name": "customer_id",
            "type": "string",
            "required": true
        },
        {
            "name": "connection_id",
            "type": "string",
            "required": true
        }
    ],
    "pathParams": [],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Success",
            "body": "{\n    \"data\": [\n        {\n            \"id\": \"acct_123\",\n            \"connection_id\": \"conn_123\",\n            \"name\": \"Checking\",\n            \"nature\": \"checking\",\n            \"balance\": 1200.5,\n            \"currency_code\": \"USD\",\n            \"extra\": {\n                \"iban\": null\n            },\n            \"created_at\": \"2024-01-31T10:15:00Z\",\n            \"updated_at\": \"2024-01-31T10:20:00Z\"\n        }\n    ]\n}"
        }
    }
}

Initiate Enduser Salt Edge Connection

{
    "title": "Initiate Enduser Salt Edge Connection",
    "description": "Starts a Salt Edge connect flow for the supplied email address and optional return URL.",
    "method": "POST",
    "baseUrl": "<BackendBaseUrl>",
    "endpoint": "/api/saltedge/initiate-enduser-connection",
    "headers": [
        {
            "key": "Content-Type",
            "value": "application/json",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [],
    "bodyType": "json",
    "requestBody": "{\n    \"email\": \"[email protected]\",\n    \"return_to\": \"https://app.joinlita.com/application/review\"\n}",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Success",
            "body": "{\n    \"connect_url\": \"https://example.saltedge.com/connect/session\",\n    \"expires_at\": \"2024-02-01T12:00:00Z\",\n    \"customer_id\": \"cust_123\"\n}"
        }
    }
}

Create or Get Salt Edge V6 Customer

{
    "title": "Create or Get Salt Edge V6 Customer",
    "description": "Creates a Salt Edge customer by email or returns the existing customer identifier when the provider reports a duplicate.",
    "method": "POST",
    "baseUrl": "<BackendBaseUrl>",
    "endpoint": "/api/saltedge/v6/customer",
    "headers": [
        {
            "key": "Content-Type",
            "value": "application/json",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [],
    "bodyType": "json",
    "requestBody": "{\n    \"email\": \"[email protected]\"\n}",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Success",
            "body": "{\n    \"customer_id\": \"cust_123\"\n}"
        }
    }
}

Create Salt Edge V6 Connect Session

{
    "title": "Create Salt Edge V6 Connect Session",
    "description": "Creates a Salt Edge connect session and returns the widget URL and expiry time.",
    "method": "POST",
    "baseUrl": "<BackendBaseUrl>",
    "endpoint": "/api/saltedge/v6/connect-session",
    "headers": [
        {
            "key": "Content-Type",
            "value": "application/json",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [],
    "bodyType": "json",
    "requestBody": "{\n    \"customer_id\": \"cust_123\",\n    \"return_to\": \"https://app.joinlita.com/application/review\",\n    \"consent_scopes\": [\n        \"accounts\",\n        \"transactions\",\n        \"holder_info\"\n    ],\n    \"categorization\": \"personal\"\n}",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Success",
            "body": "{\n    \"connect_url\": \"https://example.saltedge.com/connect/session\",\n    \"expires_at\": \"2024-02-01T12:00:00Z\"\n}"
        }
    }
}

Get Connections for Customer

{
    "title": "Get Connections for Customer",
    "description": "Returns all Salt Edge connections for a customer and enriches each connection with its accounts.",
    "method": "GET",
    "baseUrl": "<BackendBaseUrl>",
    "endpoint": "/api/saltedge/customer/{customer_id}/connections",
    "headers": [],
    "queryParams": [],
    "pathParams": [
        {
            "name": "customer_id",
            "type": "string",
            "required": true
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Success",
            "body": "{\n    \"connections\": [\n        {\n            \"id\": \"conn_123\",\n            \"provider_name\": \"Example Bank\",\n            \"categorization\": \"personal\",\n            \"accounts\": [\n                {\n                    \"id\": \"acct_123\",\n                    \"connection_id\": \"conn_123\",\n                    \"name\": \"Checking\",\n                    \"nature\": \"checking\",\n                    \"balance\": 1200.5,\n                    \"currency_code\": \"USD\",\n                    \"extra\": [],\n                    \"created_at\": \"2024-01-31T10:15:00Z\",\n                    \"updated_at\": \"2024-01-31T10:20:00Z\"\n                }\n            ]\n        }\n    ]\n}"
        }
    }
}

Get Salt Edge Connection

{
    "title": "Get Salt Edge Connection",
    "description": "Returns a single Salt Edge connection with its customer identifier and accounts when available.",
    "method": "GET",
    "baseUrl": "<BackendBaseUrl>",
    "endpoint": "/api/saltedge/connection/{connection_id}",
    "headers": [],
    "queryParams": [],
    "pathParams": [
        {
            "name": "connection_id",
            "type": "string",
            "required": true
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Success",
            "body": "{\n    \"id\": \"conn_123\",\n    \"customer_id\": \"cust_123\",\n    \"provider_name\": \"Example Bank\",\n    \"categorization\": \"personal\",\n    \"status\": \"active\",\n    \"accounts\": [\n        {\n            \"id\": \"acct_123\",\n            \"connection_id\": \"conn_123\",\n            \"name\": \"Checking\",\n            \"nature\": \"checking\",\n            \"balance\": 1200.5,\n            \"currency_code\": \"USD\",\n            \"extra\": [],\n            \"created_at\": \"2024-01-31T10:15:00Z\",\n            \"updated_at\": \"2024-01-31T10:20:00Z\"\n        }\n    ]\n}"
        }
    }
}

Response and request model properties

Salt Edge customer and connection models

SaltEdgeCustomerData

backend/src/interface/saltedge_endpoints.py

Property Type Description
customer_id str Salt Edge customer identifier
identifier str User identifier used to create or match the customer
created_at str Provider creation timestamp
SaltEdgeCustomerListResponse

backend/src/interface/saltedge_endpoints.py

Property Type Description
data List[SaltEdgeCustomerData] List of Salt Edge customers
SaltEdgeConnectionData

backend/src/interface/saltedge_endpoints.py

Property Type Description
id str Salt Edge connection identifier
provider_name str Institution or provider name
SaltEdgeConnectionListResponse

backend/src/interface/saltedge_endpoints.py

Property Type Description
data List[SaltEdgeConnectionData] List of Salt Edge connections
SaltEdgeAccountData

backend/src/interface/saltedge_endpoints.py

Property Type Description
id str Account identifier
connection_id str Owning connection identifier
name str Display name
nature str Account nature
balance float Current account balance
currency_code str Account currency
extra Dict[str, Any] Additional provider fields
created_at str Creation timestamp
updated_at str Update timestamp
SaltEdgeAccountListResponse

backend/src/interface/saltedge_endpoints.py

Property Type Description
data List[SaltEdgeAccountData] List of Salt Edge accounts
SaltEdgeInitiateEnduserConnectionRequest

backend/src/interface/saltedge_endpoints.py

Property Type Description
email str Email used as the Salt Edge customer identifier
return_to Optional[str] Optional redirect URL after widget completion
SaltEdgeV6CustomerRequest

backend/src/interface/saltedge_endpoints.py

Property Type Description
email str Email used to create or look up a customer
SaltEdgeV6CustomerResponse

backend/src/interface/saltedge_endpoints.py

Property Type Description
customer_id str Salt Edge customer identifier
SaltEdgeV6ConnectSessionRequest

backend/src/interface/saltedge_endpoints.py

Property Type Description
customer_id str Existing Salt Edge customer identifier
return_to str Redirect URL after the session
consent_scopes List[str] Requested scopes, default ["accounts", "transactions", "holder_info"]
categorization str Requested categorization mode, default personal
SaltEdgeV6ConnectSessionResponse

backend/src/interface/saltedge_endpoints.py

Property Type Description
connect_url str Salt Edge widget URL
expires_at Optional[str] Expiration time for the connect session
SaltEdgeConnectionWithAccountsData

backend/src/interface/saltedge_endpoints.py

Property Type Description
id str Connection identifier
provider_name Optional[str] Provider name when available
categorization Optional[str] Connection categorization
accounts List[Dict[str, Any]] Enriched account list, default empty list
SaltEdgeConnectionsForCustomerResponse

backend/src/interface/saltedge_endpoints.py

Property Type Description
connections List[SaltEdgeConnectionWithAccountsData] All connections for the customer
SaltEdgeSingleConnectionResponse

backend/src/interface/saltedge_endpoints.py

Property Type Description
id str Connection identifier
customer_id Optional[str] Owning customer identifier
provider_name Optional[str] Provider name when available
categorization Optional[str] Connection categorization
status Optional[str] Connection status
accounts List[Dict[str, Any]] Enriched account list, default empty list

Account coverage and batch ingestion models

AccountCoverageResult

backend/src/usecase/account_detection.py

Property Type Description
status str Coverage status, unknown, incomplete, or complete
reported_accounts int Accounts submitted by the applicant
detected_accounts int Accounts detected from Plaid
missing_accounts int Detected accounts not found in the submission
coverage_ratio Optional[float] Ratio value or None
details list[dict[str, Any]] Per-connection coverage details
errors list[str] Errors captured while evaluating connections
ProcessTransUnionBatchResult

backend/src/usecase/transunion_batch.py

Property Type Description
ingestion TransUnionBatchIngestion Final ingestion record
summary Dict[str, object] Aggregated score and row summary
sanitized_rows List[Dict[str, object]] Redacted row data returned to callers
issues List[TransUnionBatchRowIssue] Parsing and validation issues

Service and Use Case Methods

backend/src/usecase/account_detection.py

Method Description
infer_account_coverage Compares submitted connected accounts to Plaid-detected accounts and returns the coverage result

backend/src/usecase/transunion_batch.py

Method Description
process_transunion_batch Parses, persists, and summarizes a TransUnion batch file

backend/src/usecase/saltedge_usecase.py

Method Description
get_or_create_saltedge_customer Creates a Salt Edge customer mapping for the supplied user identifier
generate_saltedge_connect_url Opens a Salt Edge connect session and returns the URL, expiry, and customer identifier

backend/src/interface/saltedge_endpoints.py

Method Description
get_saltedge_connect_url Authenticated Salt Edge connect URL generator
list_saltedge_customers Cached customer-list endpoint
list_saltedge_connections Lists connections for a customer
list_saltedge_accounts Lists accounts for a customer connection
initiate_enduser_saltedge_connection Open Salt Edge connect URL generator for an email address
create_or_get_saltedge_v6_customer Creates or reuses a Salt Edge v6 customer
create_saltedge_v6_connect_session Creates a Salt Edge v6 widget session
get_connections_for_customer Returns connections enriched with accounts
get_saltedge_connection Returns a single connection with account enrichment

backend/src/interface/transunion_batch_endpoints.py

Method Description
create_transunion_batch_ingestion Validates input rows, converts layout definitions, and invokes batch processing

Error Handling

The production handlers surface errors in ways that are directly visible to operators:

  • backend/src/interface/saltedge_endpoints.py
    • SaltEdgeConfigurationError becomes HTTP 503 for unconfigured environments.
    • SaltEdgeAPIError preserves the upstream status code when available.
    • create_saltedge_v6_connect_session translates unsupported_country into HTTP 422 with a structured JSON detail object.
  • frontend/app/api/v1/applicants/[id]/account-coverage/route.ts
    • Invalid applicant IDs return HTTP 400.
    • Missing backend configuration returns HTTP 500.
    • Backend 404 is skipped and the next backend URL candidate is tried.
  • frontend/app/api/v1/applicants/[id]/transactions/route.ts
    • Invalid IDs and invalid query parameters return HTTP 400.
    • Missing transaction history returns HTTP 404 with the message that bank accounts must be connected and synced first.
  • backend/src/interface/transunion_batch_endpoints.py
    • Empty batch uploads return HTTP 400.

Dependencies

Dependency Role
Fastly Public edge and TLS termination
Google Cloud HTTPS Load Balancer Origin routing and health checks
Caddy Internal request split between frontend:3000 and backend:8000
Next.js App Router Frontend page routes and frontend API routes
FastAPI Backend API routes
MySQL Persistent storage for application and ingestion data
Salt Edge client Provider integration for customer, connection, and account flows
Plaid gateway Coverage comparison in the account-coverage flow

Testing Considerations

The code paths in this section are best validated with route-level and host-level checks:

  • Confirm the load balancer sends /api/* traffic to the backend service and page routes to the frontend service.
  • Verify the frontend route handlers return the same JSON the backend returns for account coverage.
  • Exercise the transaction route with and without transaction history to verify the 404 branch.
  • Confirm Salt Edge customer-list requests hit the cache on repeated calls within 60 seconds.
  • Validate that unsupported_country errors from Salt Edge return the structured 422 response.
  • Check that production log output shows route-level errors in the frontend container and backend container separately.

Key Classes Reference

Class Responsibility
documents/deployment.md Documents the edge and host deployment path
docker-compose.yml Defines the production service boundary and container runtime
Caddyfile Splits frontend and backend request paths inside the production host
route.ts Implements the frontend-owned applicant API handlers
saltedge_endpoints.py Exposes Salt Edge request and response routes
transunion_batch_endpoints.py Exposes batch ingestion for TransUnion files
account_detection.py Computes applicant account coverage
transunion_batch.py Parses and summarizes batch ingestion payloads
saltedge_usecase.py Builds Salt Edge connect sessions and customer mappings