Engineering Reference, Workspace Memory, and Supporting Documents

Overview

This section covers the repository-level helpers that make the Plaid-backed e-housing stack easier to verify locally, exercise against sandbox credentials, and turn into reusable sample data for documentation. The scripts and tests here are not end-user features; they are operational support tools that help developers validate Plaid balance, transaction, and asset flows, bootstrap sandbox access tokens, and generate sample application records for API checks.

The helpers split into three practical groups: manual smoke tests, CI-facing integration and negative-path tests, and artifact generators. Several of them persist output such as transaction_data.json, serialized asset reports, or application summary JSON so those artifacts can be reused in broader analysis and documentation workflows.

Repository Utility Landscape

File Role Runtime Mode Primary Output
backend/test_plaid_balance.py Manual Plaid balance smoke test Standalone script Printed account balances
backend/test_plaid_transactions.py Manual Plaid transaction analysis smoke test Standalone script Printed summary plus transaction_data.json
backend/test_plaid_assets.py Manual Plaid asset report smoke test Standalone script Serialized asset report JSON
backend/tests/usecase/get_plaid_token.py Sandbox token bootstrap utility Standalone script Printed access token
backend/src/scripts/create_test_application.py Local API probe and sample application generator Standalone script Printed application summary JSON
backend/test_plaid_balance_integration.py CI-facing Plaid balance integration coverage unittest module Assertions only
backend/test_plaid_transactions_integration.py CI-facing Plaid transaction integration coverage unittest module Assertions only
backend/test_plaid_assets_integration.py CI-facing Plaid asset integration coverage unittest module Assertions only
backend/tests/infra/external_apis/test_plaid_transactions_handling.py CI-facing negative-path Plaid handling pytest module Assertions only

Architecture Overview

flowchart TB
    subgraph LocalHelpers [Repository Helpers]
        BalanceSmoke[backend test_plaid_balance]
        TransactionSmoke[backend test_plaid_transactions]
        AssetSmoke[backend test_plaid_assets]
        TokenBootstrap[backend tests usecase get_plaid_token]
        ApplicationGen[backend src scripts create_test_application]
        BalanceCI[backend test_plaid_balance_integration]
        TransactionCI[backend test_plaid_transactions_integration]
        AssetCI[backend test_plaid_assets_integration]
        TransactionErrors[backend tests infra external_apis test_plaid_transactions_handling]
    end

    subgraph SharedRuntime [Shared Runtime]
        Dotenv[load_dotenv]
        PlaidGateway[PlaidKycGateway]
        PlaidApi[PlaidApi sandbox]
        ApplicationsApi[Applications API]
    end

    subgraph Artifacts [Artifacts]
        TxJson[transaction_data json]
        AssetJson[asset report json]
        AppJson[application summary json]
        TokenText[access token stdout]
    end

    BalanceSmoke --> Dotenv
    TransactionSmoke --> Dotenv
    AssetSmoke --> Dotenv
    TokenBootstrap --> Dotenv
    ApplicationGen --> Dotenv

    BalanceSmoke --> PlaidGateway
    TransactionSmoke --> PlaidGateway
    AssetSmoke --> PlaidGateway
    TokenBootstrap --> PlaidApi
    ApplicationGen --> ApplicationsApi

    PlaidGateway --> PlaidApi
    PlaidApi --> Artifacts
    ApplicationsApi --> AppJson
    TransactionSmoke --> TxJson
    AssetSmoke --> AssetJson
    TokenBootstrap --> TokenText

    BalanceCI --> PlaidGateway
    TransactionCI --> PlaidGateway
    AssetCI --> PlaidGateway
    TransactionErrors --> PlaidGateway

Shared Plaid Gateway

backend/src/infra/external_apis/plaid_client.py

The utility scripts and tests all converge on PlaidKycGateway as the shared Plaid-facing adapter. The visible scripts instantiate it directly with PlaidKycGateway() after loading environment variables, and the integration tests patch its plaid_client attribute with MagicMock to isolate behavior.

Public Methods Used by the Helpers

Method Description
get_account_balances Fetches account records and balance snapshots for a Plaid access token.
get_transaction_data Fetches transactions and returns transaction summary, source breakdown, and metadata.
get_asset_report Creates and retrieves an asset report over a requested lookback window.

Helper-to-Gateway Data Flow

  1. load_dotenv() loads Plaid credentials or a direct access token from the local environment.
  2. The script or test creates PlaidKycGateway().
  3. The helper passes the access token into one of the gateway methods.
  4. The gateway returns raw Plaid-shaped data or a normalized analysis payload.
  5. The helper prints, asserts, or serializes the result for later inspection.

Manual Smoke Tests

Plaid Balance Smoke Test

backend/test_plaid_balance.py

This script verifies that a real Plaid access token can be used to fetch account balances through PlaidKycGateway.get_account_balances. It is intentionally simple: it loads .env, checks PLAID_ACCESS_TOKEN, and prints each account’s name, type, and current or available balance.

Entry Point

Function Description
main Loads environment variables, checks for PLAID_ACCESS_TOKEN, calls get_account_balances, and prints the result.

Runtime Behavior

  • Exits early with a printed message if PLAID_ACCESS_TOKEN is missing.
  • Prints each account’s name, type, and balance fields.
  • Catches exceptions and prints the error string.

Plaid Transactions Smoke Test

backend/test_plaid_transactions.py

This script performs the same style of direct verification for transaction analysis. It calls PlaidKycGateway.get_transaction_data with a 90 day lookback, prints the transaction summary and source list, and writes the full analysis payload to transaction_data.json.

Entry Point

Function Description
main Loads environment variables, checks for PLAID_ACCESS_TOKEN, fetches transaction analysis, prints the summary, and saves the full payload.

Workspace Memory Output

Artifact Purpose
transaction_data.json Persisted transaction analysis snapshot used for later review and documentation.

Runtime Behavior

  • Uses lookback_days = 90.
  • Prints transaction_summary fields including total income, total expenses, and net flow.
  • Prints monthly_averages and a top 10 list of transaction_sources.
  • Prints metadata including analysis date, date range, transaction count, and source environment.
  • Serializes the returned payload to transaction_data.json.

Plaid Asset Report Smoke Test

backend/test_plaid_assets.py

This script exercises Plaid asset report generation and persists the result to a JSON file after converting Plaid objects into plain serializable data. The module skips itself at import time when PLAID_CLIENT_ID or PLAID_SECRET is missing, so it behaves like a local verification utility rather than an always-on test.

Entry Point

Function Description
test_asset_report Calls get_asset_report, converts the response to serializable data, and writes it to disk.

Workspace Memory Output

Artifact Purpose
Serialized asset report JSON Local snapshot of the report for analysis and documentation reuse.

Runtime Behavior

  • Loads .env from the script directory if present.
  • Uses test_asset_report() as the primary execution path.
  • Converts nested Plaid objects recursively into JSON-compatible primitives.
  • Prints the generated report filename.
  • Raises exceptions after printing a short error message.

Plaid Token Bootstrap Utility

backend/tests/usecase/get_plaid_token.py

This helper exists to create a sandbox item with assets access, exchange the resulting public token for an access token, and print the access token for use in subsequent smoke tests. It is useful when PLAID_ACCESS_TOKEN is not already available.

Entry Point

Function Description
main Creates a sandbox public token, exchanges it for an access token, and prints a shell export command.

Runtime Behavior

  • Calls get_plaid_client().
  • Creates a sandbox token with Products('auth') and Products('assets').
  • Uses SandboxPublicTokenCreateRequest and ItemPublicTokenExchangeRequest.
  • Prints the access token and a ready-to-copy export command for test_plaid_balance.py.

CI-Facing Integration and Negative-Path Tests

Plaid Balance Integration Tests

backend/test_plaid_balance_integration.py

This module verifies the Plaid client initialization path, sandbox public-token generation, public-token exchange, and account balance retrieval. It is credential-gated: the module skips at import time unless PLAID_CLIENT_ID and PLAID_SECRET are present.

Class: TestPlaidIntegration

Property Type Description
client_id str Plaid client ID loaded from the environment.
secret str Plaid secret loaded from the environment.
env str Plaid environment, defaulting to sandbox.

Public Methods

Method Description
setUpClass Loads credentials from the environment and raises an error if either required Plaid credential is missing.
test_plaid_client_initialization Verifies that PlaidKycGateway initializes a PlaidApi client.
test_sandbox_public_token_creation Creates a sandbox public token using auth and identity products.
test_exchange_public_token Exchanges a public token for an access token.
test_get_account_balances Calls get_account_balances and validates the returned account structure.
test_full_flow Runs the full create token, exchange token, and fetch balances sequence.

Behavior Notes

  • The sandbox token request uses institution_id='ins_1'.
  • The request includes override_username, override_password, and a webhook URL.
  • The integration flow validates the shape of the returned account data, not just call success.

Plaid Transaction Integration Tests

backend/test_plaid_transactions_integration.py

This module verifies that transaction data returned by PlaidKycGateway.get_transaction_data has the expected summary structure and that source aggregation works as expected across income and expense transactions. It also uses environment-based gating for Plaid credentials.

Class: TestPlaidTransactionsIntegration

Property Type Description
client_id str Plaid client ID loaded from the environment.
secret str Plaid secret loaded from the environment.
env str Plaid environment, defaulting to sandbox.
mock_plaid_client MagicMock Mocked Plaid client injected through get_plaid_client.
client PlaidKycGateway Gateway initialized against the mocked Plaid client.
test_access_token str Static token used by the tests.

Public Methods

Method Description
setUpClass Loads Plaid credentials and validates the environment.
setUp Patches get_plaid_client and creates a PlaidKycGateway backed by a mock client.
tearDown Stops the patch started in setUp.
test_get_transaction_data_structure Verifies the returned transaction analysis shape and summary totals.
test_transaction_source_identification Verifies per-source grouping and amount aggregation.

Helper Method

Method Description
_create_mock_transaction Builds a Plaid-shaped transaction dictionary used by the integration tests.

Behavior Notes

  • The transaction fixture includes both positive and negative amounts.
  • Source grouping is validated through source_name, transaction_count, and total_amount.
  • The tests verify nested structures such as transaction_summary.monthly_averages and metadata.date_range.

Plaid Asset Integration Tests

backend/test_plaid_assets_integration.py

This module verifies asset report creation, retrieval, and error handling in isolation. It also uses environment-based gating so it only runs when Plaid credentials are available.

Class: TestPlaidAssetsIntegration

Property Type Description
client_id str Plaid client ID loaded from the environment.
secret str Plaid secret loaded from the environment.
env str Plaid environment, defaulting to sandbox.
access_token str Static token used by the tests.
days_requested int Lookback window for asset report generation.
plaid_gateway PlaidKycGateway Gateway used to call the Plaid asset report methods.

Public Methods

Method Description
setUpClass Loads Plaid credentials and validates the environment.
setUp Creates the gateway and initializes test values.
test_asset_report_creation Verifies get_asset_report success behavior and the returned structure.
test_asset_report_error_handling Verifies the error path when asset report creation fails.

Behavior Notes

  • The happy-path test patches asset_report_create and asset_report_get.
  • The mocked report includes date_generated, days_requested, and an items collection.
  • The error-path test patches asset_report_create to raise an exception and verifies handling.

Plaid Transaction Handling Negative-Path Tests

backend/tests/infra/external_apis/test_plaid_transactions_handling.py

This module verifies that the Plaid gateway handles an invalid transactions product response gracefully instead of failing hard. It is the most explicit CI-facing negative-path helper in this set.

Helper Class: _DummyPlaidClient

Property Type Description
_exception ApiException Exception raised when transactions_get is called.

Public Methods

Method Description
transactions_get Raises the configured ApiException so the gateway error path can be exercised.

Fixture

Function Description
plaid_gateway_with_exception Constructs a PlaidKycGateway with _DummyPlaidClient injected as plaid_client.

Test Coverage

Function Description
test_get_transaction_data_handles_invalid_product Verifies the gateway returns metadata.status == "not_supported" and metadata.error_code == "INVALID_PRODUCT".
test_fetch_transactions_returns_warning Verifies the fallback path returns empty collections and warning text rather than throwing.

Behavior Notes

  • The injected ApiException body contains error_code = "INVALID_PRODUCT".
  • The tests check that the returned warning text includes the Plaid transactions product message.
  • This helper is CI-facing and specifically validates error shaping, not success behavior.

Demo and Analysis Artifact Generators

Local Application Creation Probe

backend/src/scripts/create_test_application.py

This script creates a test housing application through the backend applications API, then fetches the created record to confirm the stored credit_score and login_credentials. It is a local verification and sample-data generator, not a test module.

Entry Point

Function Description
main Parses CLI args, builds headers, posts a test application, fetches the created record, and prints a summary JSON object.
_build_headers Builds the request headers used for both POST and GET calls.

Runtime Behavior

  • Uses argparse options:
    • --base-url
    • --email
    • --full-name
  • Defaults --base-url to APPLICATIONS_API_BASE_URL or http://localhost:8000/api.
  • Uses APPLICATIONS_API_TOKEN if present to add Authorization: Bearer ....
  • Posts to /v1/applications, then fetches /v1/applications/{id}.
  • Prints a JSON summary containing:
    • application_id
    • credit_score
    • login_credentials
    • detail_url

API Integration

Create Test Application

{
    "title": "Create Test Application",
    "description": "Creates a local sample housing application and returns the generated application record",
    "method": "POST",
    "baseUrl": "<ApplicationsApiBaseUrl>",
    "endpoint": "/v1/applications",
    "headers": [
        {
            "key": "Content-Type",
            "value": "application/json",
            "required": true
        },
        {
            "key": "Authorization",
            "value": "Bearer <token>",
            "required": false
        }
    ],
    "queryParams": [],
    "pathParams": [],
    "bodyType": "json",
    "requestBody": "{\n    \"email\": \"[email protected]\",\n    \"phone\": \"5551234567\",\n    \"country\": \"US\",\n    \"property_type\": \"condo\",\n    \"purchase_intent\": \"loan\",\n    \"budget_range\": \"250k-350k\",\n    \"savings\": \"40000\",\n    \"income\": \"120000\",\n    \"income_currency\": \"USD\",\n    \"employment_status\": \"full-time\",\n    \"financing_consent\": \"yes\",\n    \"full_name\": \"Test Applicant\",\n    \"agree_policy\": true,\n    \"receive_updates\": false,\n    \"skipped_connect_accounts\": false,\n    \"connected_accounts\": {\n        \"plaid\": [\n            {\n                \"id\": \"acct-1\",\n                \"type\": \"checking\",\n                \"balances\": {\n                    \"current\": 2500,\n                    \"available\": 2200,\n                    \"iso_currency_code\": \"USD\"\n                },\n                \"transactions\": [\n                    {\n                        \"date\": \"2026-01-01\",\n                        \"amount\": 4200,\n                        \"direction\": \"credit\",\n                        \"category\": \"salary\"\n                    },\n                    {\n                        \"date\": \"2026-01-03\",\n                        \"amount\": 1200,\n                        \"direction\": \"debit\",\n                        \"category\": \"rent\"\n                    }\n                ]\n            }\n        ]\n    }\n}",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Success",
            "body": "{\n    \"id\": 123,\n    \"credit_score\": 742,\n    \"login_credentials\": {\n        \"username\": \"[email protected]\",\n        \"password\": \"TempPass!123\"\n    }\n}"
        }
    }
}

Get Test Application

{
    "title": "Get Test Application",
    "description": "Fetches the created test application by identifier",
    "method": "GET",
    "baseUrl": "<ApplicationsApiBaseUrl>",
    "endpoint": "/v1/applications/{id}",
    "headers": [
        {
            "key": "Content-Type",
            "value": "application/json",
            "required": true
        },
        {
            "key": "Authorization",
            "value": "Bearer <token>",
            "required": false
        }
    ],
    "queryParams": [],
    "pathParams": [
        {
            "key": "id",
            "value": "123",
            "required": true
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Success",
            "body": "{\n    \"id\": 123,\n    \"credit_score\": 742,\n    \"login_credentials\": {\n        \"username\": \"[email protected]\",\n        \"password\": \"TempPass!123\"\n    }\n}"
        }
    }
}

Plaid Access Token Bootstrap

backend/tests/usecase/get_plaid_token.py

This helper exists to produce a reusable sandbox access token. It is especially useful when a developer wants to run backend/test_plaid_balance.py immediately after sandbox setup.

Entry Point

Function Description
main Creates a sandbox public token with assets access, exchanges it for an access token, and prints both success messages and the token itself.

Workspace Memory Output

Artifact Purpose
Printed access token Copied into PLAID_ACCESS_TOKEN for later smoke tests.

Transaction Analysis Artifact Generation

backend/test_plaid_transactions.py

Beyond being a smoke test, this script creates a persisted analysis snapshot. The saved transaction_data.json can be used as a workspace artifact when documenting transaction source aggregation, monthly averages, and metadata structure.

Workspace Memory Output

Artifact Purpose
transaction_data.json Full transaction analysis payload written to disk for inspection and reuse.

Asset Report Artifact Generation

backend/test_plaid_assets.py

This script is also a workspace-memory generator. It converts the Plaid report into a serializable shape and writes the result to a JSON file.

Workspace Memory Output

Artifact Purpose
Serialized asset report JSON Full report snapshot used for analysis and documentation.

Helper Lifecycle and State Handling

Common Runtime States

State Description
Environment loaded load_dotenv() has populated Plaid and application settings.
Token missing The helper exits early or prints a direct instruction message.
Sandbox ready The helper has a Plaid access token or can create one from sandbox credentials.
Request succeeded The Plaid or application API returned data that can be printed, asserted, or serialized.
Request failed The helper prints the exception, and some helpers also print parsed error bodies or warnings.

Error Handling Patterns

  • backend/test_plaid_balance.py and backend/test_plaid_transactions.py both exit early when PLAID_ACCESS_TOKEN is not set.
  • backend/test_plaid_transactions.py prints a parsed e.body payload when available, then falls back to the raw body.
  • backend/test_plaid_assets.py and the integration tests skip or fail fast when Plaid credentials are missing.
  • backend/tests/infra/external_apis/test_plaid_transactions_handling.py validates graceful fallback for INVALID_PRODUCT rather than a hard exception.
  • backend/src/scripts/create_test_application.py raises SystemExit(main()) after printing its JSON summary.

Dependencies

Runtime and Library Dependencies

  • dotenv.load_dotenv
  • os
  • sys
  • json
  • datetime, timedelta, timezone
  • pathlib.Path
  • pytest
  • unittest
  • unittest.mock.patch
  • unittest.mock.MagicMock
  • Plaid SDK types and clients:
    • PlaidApi
    • AccountsBalanceGetRequest
    • AccountsGetRequest
    • ItemPublicTokenExchangeRequest
    • SandboxPublicTokenCreateRequest
    • Products
    • AssetReportCreateRequest
    • AssetReportGetRequest
    • TransactionsGetRequest
    • TransactionsGetResponse
    • Transaction
    • ApiException
  • Repository helper:
    • src.infra.external_apis.plaid_client.PlaidKycGateway
    • get_plaid_client

Environment Variables

Variable Used By Purpose
PLAID_ACCESS_TOKEN Manual smoke tests Access token for balance, transaction, and asset retrieval.
PLAID_CLIENT_ID Integration tests and asset utilities Plaid credential required for sandbox client setup.
PLAID_SECRET Integration tests and asset utilities Plaid credential required for sandbox client setup.
PLAID_ENV Integration tests Defaults to sandbox.
APPLICATIONS_API_BASE_URL create_test_application.py Base URL for the local applications API.
APPLICATIONS_API_TOKEN create_test_application.py Optional bearer token for API calls.

Testing Considerations

  • Use the manual smoke scripts when you want to verify a real token quickly without running the whole test suite.
  • Use the integration modules when you want repeatable CI coverage around Plaid initialization, sandbox token exchange, balances, transactions, and asset reports.
  • Use backend/tests/infra/external_apis/test_plaid_transactions_handling.py to confirm that Plaid transaction failures are normalized into safe fallback payloads.
  • Use backend/tests/usecase/get_plaid_token.py when a new sandbox token is needed for a local session.
  • Use backend/src/scripts/create_test_application.py when you need a sample application record and a reproducible JSON summary for documentation or local validation.

Key Classes Reference

Class Responsibility
test_plaid_balance.py Manual balance smoke test via main.
test_plaid_transactions.py Manual transaction analysis smoke test and artifact writer.
test_plaid_assets.py Manual asset report smoke test and serialized report writer.
TestPlaidIntegration CI coverage for Plaid client creation, token exchange, and balances.
TestPlaidTransactionsIntegration CI coverage for transaction data structure and source aggregation.
TestPlaidAssetsIntegration CI coverage for asset report creation, retrieval, and error handling.
_DummyPlaidClient Test double that forces Plaid transaction failures.
plaid_gateway_with_exception Fixture that injects the failing Plaid client into PlaidKycGateway.
get_plaid_token.py Sandbox token bootstrap utility.
create_test_application.py Local API probe and sample application generator.
PlaidKycGateway Shared Plaid adapter used by all smoke and integration helpers.