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.mddescribes the frontend as React with Vite and usesVITE_BACKEND_API_URL, but the checked-in runtime route handlers live underfrontend/app/...and use Next.js App Router APIs such asNextRequest,NextResponse, andnext/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 tomvp-backend-apion port8000. The frontend-owned route handlers underfrontend/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:
- Fastly fronts
app.joinlita.com, terminates TLS at the edge, and caches static assets. - Google Cloud HTTPS Load Balancer receives Fastly origin traffic and splits requests by path.
- 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.tslogs warnings when backend lookup or stored-application hydration fails.backend/src/interface/saltedge_endpoints.pylogs cache hits, config failures, Salt Edge API failures, and unexpected exceptions.backend/src/interface/transunion_batch_endpoints.pyreturns 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 byfrontend:3000orbackend:8000before looking at the handler logs.
The deployment guide defines the only explicit origin allowlist in the provided material:
ALLOWED_ORIGINS=https://app.joinlita.comVITE_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.pySaltEdgeConfigurationErrorbecomes HTTP503for unconfigured environments.SaltEdgeAPIErrorpreserves the upstream status code when available.create_saltedge_v6_connect_sessiontranslatesunsupported_countryinto HTTP422with 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
404is skipped and the next backend URL candidate is tried.
- Invalid applicant IDs return HTTP
frontend/app/api/v1/applicants/[id]/transactions/route.ts- Invalid IDs and invalid query parameters return HTTP
400. - Missing transaction history returns HTTP
404with the message that bank accounts must be connected and synced first.
- Invalid IDs and invalid query parameters return HTTP
backend/src/interface/transunion_batch_endpoints.py- Empty batch uploads return HTTP
400.
- Empty batch uploads return HTTP
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_countryerrors 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 |