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
load_dotenv()loads Plaid credentials or a direct access token from the local environment.- The script or test creates
PlaidKycGateway(). - The helper passes the access token into one of the gateway methods.
- The gateway returns raw Plaid-shaped data or a normalized analysis payload.
- 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_TOKENis 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_summaryfields including total income, total expenses, and net flow. - Prints
monthly_averagesand a top 10 list oftransaction_sources. - Prints
metadataincluding 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
.envfrom 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')andProducts('assets'). - Uses
SandboxPublicTokenCreateRequestandItemPublicTokenExchangeRequest. - 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, andtotal_amount. - The tests verify nested structures such as
transaction_summary.monthly_averagesandmetadata.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_createandasset_report_get. - The mocked report includes
date_generated,days_requested, and anitemscollection. - The error-path test patches
asset_report_createto 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
ApiExceptionbody containserror_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
argparseoptions:--base-url--email--full-name
- Defaults
--base-urltoAPPLICATIONS_API_BASE_URLorhttp://localhost:8000/api. - Uses
APPLICATIONS_API_TOKENif present to addAuthorization: Bearer .... - Posts to
/v1/applications, then fetches/v1/applications/{id}. - Prints a JSON summary containing:
application_idcredit_scorelogin_credentialsdetail_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.pyandbackend/test_plaid_transactions.pyboth exit early whenPLAID_ACCESS_TOKENis not set.backend/test_plaid_transactions.pyprints a parsede.bodypayload when available, then falls back to the raw body.backend/test_plaid_assets.pyand the integration tests skip or fail fast when Plaid credentials are missing.backend/tests/infra/external_apis/test_plaid_transactions_handling.pyvalidates graceful fallback forINVALID_PRODUCTrather than a hard exception.backend/src/scripts/create_test_application.pyraisesSystemExit(main())after printing its JSON summary.
Dependencies
Runtime and Library Dependencies
dotenv.load_dotenvossysjsondatetime,timedelta,timezonepathlib.Pathpytestunittestunittest.mock.patchunittest.mock.MagicMock- Plaid SDK types and clients:
PlaidApiAccountsBalanceGetRequestAccountsGetRequestItemPublicTokenExchangeRequestSandboxPublicTokenCreateRequestProductsAssetReportCreateRequestAssetReportGetRequestTransactionsGetRequestTransactionsGetResponseTransactionApiException
- Repository helper:
src.infra.external_apis.plaid_client.PlaidKycGatewayget_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.pyto confirm that Plaid transaction failures are normalized into safe fallback payloads. - Use
backend/tests/usecase/get_plaid_token.pywhen a new sandbox token is needed for a local session. - Use
backend/src/scripts/create_test_application.pywhen 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. |