Architecture and Repository Orientation

Overview

This repository is a monorepo for Lita’s e-housing platform, and the top-level layout cleanly separates product code from operational assets. The persistent map in workspace/REPO_MAP.md captures the root boundaries and acts as the repo’s orientation layer for future sessions.

The product-facing runtime is split across the FastAPI backend in backend/, the Next.js frontend in frontend/, the US consent and scoring service in services/us-api/, and the US banking data gateway in services/us-data-gateway/. Around that core are operational and supporting directories for deployment assets, SQL and schema work, automation, sample data, documentation, and workspace memory.

Architecture Overview

flowchart TB
    subgraph ProductCode[Product Code]
        Backend[backend FastAPI backend]
        Frontend[frontend Next.js app]
        UsApi[services us api]
        UsDataGateway[services us data gateway]
    end

    subgraph OpsAssets[Operational Assets]
        Platform[platform deployment assets]
        DbAssets[db schema assets]
        Scripts[scripts automation]
        Data[data seed data]
        Documents[documents docs]
    end

    subgraph Memory[Workspace Memory]
        RepoMap[workspace REPO MAP]
        Patterns[workspace PATTERNS]
        Decisions[workspace DECISIONS]
        Todo[workspace TODO]
        Changelog[workspace CHANGELOG]
    end

    Backend --> DbAssets
    Frontend --> Backend
    Frontend --> Documents
    UsApi --> DbAssets
    UsDataGateway --> DbAssets
    UsDataGateway --> Redis[Redis]
    Platform --> Backend
    Platform --> Frontend
    Platform --> UsApi
    Platform --> UsDataGateway
    Memory --> Documents

Repository Boundaries

The root directories are organized by responsibility, not by release artifact. Product code lives in service/application trees, while deployment, schema, docs, and memory live beside it instead of inside a single app folder.

Directory Boundary Role What it Hosts Product or Operational
backend/ E-housing backend FastAPI backend service, migrations, scripts, tests Product code
frontend/ E-housing frontend Next.js app, UI routes, proxy routes, application flows Product code
services/us-api/ US consent and scoring Fastify service, analytics, feature governance, retraining jobs Product code
services/us-data-gateway/ US banking services Go HTTP gateway, auth, provider abstraction, bank data endpoints Product code
platform/ Runtime and deployment Deployment/runtime assets, housing label service assets Operational assets
db/ Database assets SQL-related infrastructure and migration assets Operational assets
scripts/ Automation Utility scripts, including Vertex AI helpers Operational assets
data/ Sample data Seed and sample JSON for local workflows Operational assets
documents/ Documentation Engineering and product docs Operational assets
workspace/ Persistent memory Repo map, patterns, decisions, changelog, TODO Operational memory

Workspace Memory Surface

workspace/REPO_MAP.md is the canonical map for the top-level layout, and the other workspace files carry durable operational context.

File Role
workspace/REPO_MAP.md Root directory map and update protocol
workspace/PATTERNS.md Recurring architecture and engineering conventions
workspace/DECISIONS.md Important architectural decisions
workspace/DEBUGGING.md Incident and troubleshooting notes
workspace/CHANGELOG.md Notable repository-level changes
workspace/TODO.md Short list of high-value next actions
workspace/SOUL.md Session behavior and tone constraints

Functional Domain Separation

The repo keeps the major product domains physically separated so each one can evolve with its own stack and deployment model.

E Housing Application

The e-housing flow is split between the Python backend and the Next.js frontend.

Area Evidence in Source Responsibility
backend/src/usecase/account_detection.py infer_account_coverage, AccountCoverageResult Computes account coverage against Plaid-detected accounts
backend/src/scripts/create_test_application.py POST /v1/applications, GET /v1/applications/{id} calls Creates a test application and prints the credit score
frontend/app/api/v1/applicants/[id]/account-coverage/route.ts Frontend proxy route Forwards account coverage lookups to the backend API
frontend/app/api/v1/applicants/[id]/transactions/route.ts Frontend proxy route Aggregates transaction history for an applicant
documents/account-coverage.md Product doc Describes the account coverage inference behavior
documents/feature-availability.md Product doc Explains dashboard label behavior derived from backend payloads

services/us-api/ is the consent, scoring, and governance boundary for the US banking workflow. It keeps policy enforcement, decision storage, feature generation, and retraining logic separate from the customer-facing app.

Module Responsibility
src/services/consentService.ts Consent lifecycle, receipt generation, revocation, active-consent validation
src/services/connectionService.ts Connection readiness and refresh state
src/services/featureService.ts Cashflow feature synthesis and evidence snapshot storage
src/services/scoringService.ts Decision validation, storage, replay, and allowlist enforcement
src/services/modelGovernanceService.ts Feature schema registration, drift detection, retraining triggers, model lineage
src/services/webhookService.ts Partner webhook delivery and signed payload dispatch
src/jobs/featureDriftJob.ts Scheduled drift check runner
src/jobs/retrainTriggerJob.ts Retraining trigger evaluator
src/routes/internalAnalytics.ts Internal analytics ingestion and metric retrieval

Dashboard Labeling

Dashboard labeling is split between static label configuration in the frontend and supporting documentation in documents/, with runtime deployment assets grouped under platform/.

Area Responsibility
frontend/app/application/connect-accounts/providers.ts Country and provider label maps for connect accounts
documents/feature-availability.md Documents the fallback account label behavior in the dashboard
platform/ Houses deployment/runtime assets, including the housing label service noted in the repository map

US Banking Services

services/us-data-gateway/ isolates direct banking data retrieval from the consent and scoring layer. It owns the HTTP surface for accounts, balances, transactions, and income, while keeping auth and provider selection inside the service boundary.

Module Responsibility
cmd/us-data-gateway/main.go Service bootstrap and route registration
internal/config/config.go Environment-backed runtime config
internal/handlers/handlers.go Request authorization, consent checks, provider fetches, JSON responses
internal/provider/provider.go Provider interface and response data models
internal/provider/mock.go In-memory/mock provider implementation
internal/handlers/handlers_test.go Response and error-code tests for handler helpers

US Data Gateway

The gateway is a thin HTTP service with three layers visible in the source: bootstrap, request handlers, and provider abstraction. main.go wires the database, Redis, public key material, and the provider implementation into a single Handler.

Configuration and Wiring

services/us-data-gateway/internal/config/config.go

Config

Property Type Description
Port string HTTP listen port, defaulting to 8084
DatabaseURL string PostgreSQL connection string
RedisURL string Redis connection string
JWTPublicKey string PEM-encoded RSA public key used by token verification
Provider string Provider selector read at startup

Handler Surface

services/us-data-gateway/internal/handlers/handlers.go

Handler

Property Type Description
DB *pgxpool.Pool Database pool used for consent lookup
Provider provider.Provider Bank-data provider abstraction
Auth auth.TokenVerifier Bearer-token verifier injected at startup
Method Description
Accounts Returns bank accounts after auth, consent, and category checks
Balances Returns balances after auth, consent, and category checks
Transactions Returns transactions filtered by optional date range
Income Returns income entries for the requested consent
authorize Validates the Authorization header and delegates token verification
ensureConsentActive Loads consent state from the database and rejects inactive or expired consents
writeError Normalizes error responses into JSON
writeJSON Serializes a JSON response with the chosen status code
contains Checks whether a requested category is present in the claims

consentRecord

Property Type
ID string
Status string
ExpiresAt time.Time
Categories []string

Provider Abstraction

[!NOTE] main.go reads PROVIDER, but both the mock case and the default branch construct provider.MockProvider{}. In the shown wiring, the provider selector does not change runtime behavior.

services/us-data-gateway/internal/provider/provider.go

Provider

Method Description
FetchAccounts Loads the account list for a consent
FetchBalances Loads balances for a consent
FetchTransactions Loads transactions for a consent and optional date range
FetchTransactionsSync Loads sync deltas for a consent and cursor
FetchIncome Loads income entries for a consent and lookback window

Data Models

Type Properties
Account AccountToken, Name, Type, Mask
Balance AccountToken, Available, Current, Currency
Transaction TransactionID, AccountToken, Amount, Currency, PostedAt, MerchantName, MerchantCategory
TransactionRemoval TransactionID
TransactionSync Added, Modified, Removed, NextCursor
Income IncomeID, Amount, Currency, PayDate

MockProvider

Method Description
FetchAccounts Returns two sample accounts
FetchBalances Returns sample balance rows for the sample accounts
FetchTransactions Returns sample transaction rows
FetchTransactionsSync Returns sample sync deltas
FetchIncome Returns sample income rows

Auth and Cache Dependency

services/us-data-gateway/cmd/us-data-gateway/main.go creates a Redis client from REDIS_URL, parses the RSA public key from JWT_PUBLIC_KEY, and injects both into auth.TokenVerifier. The request path then uses authorize to gate all account, balance, transaction, and income requests before any provider lookup runs.

sequenceDiagram
    participant Main as main.go
    participant Redis as Redis client
    participant Auth as auth.TokenVerifier
    participant H as Handler
    participant Req as HTTP request
    participant DB as pgxpool Pool
    participant Prov as provider.MockProvider

    Main->>Redis: Create client from REDIS_URL
    Main->>Auth: Build TokenVerifier with PublicKey and Redis
    Main->>H: Inject DB Provider Auth
    Req->>H: Accounts
    H->>Auth: Verify Bearer token
    H->>DB: QueryRow consents by consentId
    H->>Prov: FetchAccounts
    H->>Req: writeJSON accounts

US Data Gateway API Surface

Get US Accounts

{
    "title": "Get US Accounts",
    "description": "Returns bank accounts for the consent after bearer-token verification, category checks, and consent-state validation",
    "method": "GET",
    "baseUrl": "<UsDataGatewayBaseUrl>",
    "endpoint": "/api/v1/us/data/accounts",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <token>",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Success",
            "body": "{\n    \"accounts\": [\n        {\n            \"account_token\": \"acct_tok_1\",\n            \"name\": \"Checking\",\n            \"type\": \"depository\",\n            \"mask\": \"1234\"\n        }\n    ]\n}"
        },
        "403": {
            "description": "Authorization or category failure",
            "body": "{\n    \"error\": \"TOKEN_REQUIRED\"\n}"
        },
        "409": {
            "description": "Consent is inactive, expired, or revoked",
            "body": "{\n    \"error\": \"CONSENT_REVOKED\"\n}"
        }
    }
}

Get US Balances

{
    "title": "Get US Balances",
    "description": "Returns balances for the consent after bearer-token verification, category checks, and consent-state validation",
    "method": "GET",
    "baseUrl": "<UsDataGatewayBaseUrl>",
    "endpoint": "/api/v1/us/data/balances",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <token>",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Success",
            "body": "{\n    \"balances\": [\n        {\n            \"account_token\": \"acct_tok_1\",\n            \"available\": 1200,\n            \"current\": 1500,\n            \"currency\": \"USD\"\n        }\n    ]\n}"
        },
        "403": {
            "description": "Authorization or category failure",
            "body": "{\n    \"error\": \"TOKEN_REQUIRED\"\n}"
        },
        "409": {
            "description": "Consent is inactive, expired, or revoked",
            "body": "{\n    \"error\": \"CONSENT_REVOKED\"\n}"
        }
    }
}

Get US Transactions

{
    "title": "Get US Transactions",
    "description": "Returns transactions for the consent with an optional date range filter",
    "method": "GET",
    "baseUrl": "<UsDataGatewayBaseUrl>",
    "endpoint": "/api/v1/us/data/transactions",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <token>",
            "required": true
        }
    ],
    "queryParams": [
        {
            "key": "from",
            "value": "2024-10-01",
            "required": false
        },
        {
            "key": "to",
            "value": "2024-10-31",
            "required": false
        }
    ],
    "pathParams": [],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Success",
            "body": "{\n    \"transactions\": [\n        {\n            \"transaction_id\": \"txn_1\",\n            \"account_token\": \"acct_tok_1\",\n            \"amount\": 1200,\n            \"currency\": \"USD\",\n            \"posted_at\": \"2024-10-01T00:00:00Z\",\n            \"merchant_name\": \"Rent Co\",\n            \"merchant_category\": \"RENT\"\n        }\n    ]\n}"
        },
        "403": {
            "description": "Authorization or category failure",
            "body": "{\n    \"error\": \"TOKEN_REQUIRED\"\n}"
        },
        "409": {
            "description": "Consent is inactive, expired, or revoked",
            "body": "{\n    \"error\": \"CONSENT_REVOKED\"\n}"
        }
    }
}

Get US Income

{
    "title": "Get US Income",
    "description": "Returns income entries for the consent after bearer-token verification, category checks, and consent-state validation",
    "method": "GET",
    "baseUrl": "<UsDataGatewayBaseUrl>",
    "endpoint": "/api/v1/us/data/income",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <token>",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Success",
            "body": "{\n    \"income\": [\n        {\n            \"income_id\": \"inc_1\",\n            \"amount\": 5100,\n            \"currency\": \"USD\",\n            \"pay_date\": \"2024-09-30T00:00:00Z\"\n        }\n    ]\n}"
        },
        "403": {
            "description": "Authorization or category failure",
            "body": "{\n    \"error\": \"TOKEN_REQUIRED\"\n}"
        },
        "409": {
            "description": "Consent is inactive, expired, or revoked",
            "body": "{\n    \"error\": \"CONSENT_REVOKED\"\n}"
        }
    }
}

[!NOTE] When ensureConsentActive fails, Accounts, Balances, Transactions, and Income all return ErrConsentRevoked instead of the underlying database or lookup error. The handlers collapse every consent lookup failure into the same 409 response.

services/us-api/ keeps consent, scoring, feature generation, and governance as separate service modules so the scoring lifecycle can be controlled independently from the UI and from the US data gateway.

services/us-api/src/services/consentService.ts

CreateConsentPayload

Property Type Description
user { country: 'US'; user_reference?: string } User identity block
purpose Purpose Consent purpose
data_categories DataCategory[] Requested data categories
access_duration_days number Optional duration in days
expires_at string Optional absolute expiry time
refresh_permissions { enabled: boolean; max_refresh_per_day: number } Optional refresh policy
consent_disclosure_version string Disclosure version accepted by the user
Method Description
createConsent Creates a consent record and logs the creation event
revokeConsent Marks consent as revoked, revokes tokens, disconnects connections, and dispatches a webhook
getConsentReceipt Returns the persisted receipt fields for a consent
ensureConsentActive Rejects missing, inactive, or expired consents

Connection Service

services/us-api/src/services/connectionService.ts

Method Description
ensureConnectionsReady Checks consent-linked connections and returns readiness or raises reauth requirements
recordConnectionRefresh Marks linked connections as refreshed and active

Feature Service

services/us-api/src/services/featureService.ts

Method Description
computeCashflow Derives cashflow features, migrates them to the global schema, and stores an evidence snapshot
fetchEvidence Loads an evidence snapshot by reference

CashflowFeatures

Property Type
income_monthly_avg_usd number
income_stability_index number
nsf_overdraft_count_180d number
balance_min_30d_usd number
rent_payment_detected boolean
debt_payment_ratio_est number

Scoring Service

services/us-api/src/services/scoringService.ts

Method Description
validateDecision Enforces deny-reason rules before a decision is accepted
storeDecision Persists the decision payload and associated model lineage
replayDecision Replays a decision from evidence and optionally calls the callback endpoint

DecisionPayload

Property Type
applicant_reference string
purpose string
product_type string
score number
decision string
approved_limit number
model object with name, version, schema_version, training_snapshot_ref, hyperparameters, metrics
reasons array of { code, description }
evidence_ref string
consent_id string
consent_text_version string
connection_status string
features Record<string, unknown>

Model Governance Service

services/us-api/src/services/modelGovernanceService.ts

Method Description
ensureFeatureSchemaVersion Creates the global feature schema record if it does not already exist
runFeatureDriftDetection Computes feature drift against a stored baseline and writes a drift report
evaluateRetrainingTriggers Checks performance and drift thresholds and creates a retraining trigger when needed
recordModelLineage Persists model artifact metadata and the initial deployment record

GlobalCreditFeatureSchemaV1

Property Type
schema_version typeof GLOBAL_CREDIT_FEATURE_SCHEMA_VERSION
income_monthly_avg_usd number
income_stability_index number
nsf_overdraft_count_180d number
balance_min_30d_usd number
rent_payment_detected boolean
debt_payment_ratio_est number

FeatureMigrationResult

Property Type
schema_version typeof GLOBAL_CREDIT_FEATURE_SCHEMA_VERSION
features GlobalCreditFeatureSchemaV1
migration_notes string[]

DenyReasonsAllowlist

INSUFFICIENT_INCOME, INCOME_INSTABILITY, RECENT_OVERDRAFTS, LOW_MIN_BALANCE, HIGH_CASHFLOW_VOLATILITY, INSUFFICIENT_HISTORY, UNVERIFIED_ACCOUNT, INCONSISTENT_IDENTITY_SIGNALS, HIGH_RISK_DEVICE_SIGNAL

ConnectionStatusValues

ACTIVE, REAUTH_REQUIRED, DEGRADED, DISCONNECTED

PurposeValues

RENTAL_SCREENING, LENDING_UNDERWRITING, ACCOUNT_OPENING, INCOME_VERIFICATION, FRAUD_PREVENTION, GENERAL_PERSONAL_FINANCE

DataCategoryValues

IDENTITY_BASIC, ACCOUNTS, BALANCES, TRANSACTIONS, INCOME, EMPLOYMENT, CASHFLOW_FEATURES, DEVICE_RISK, WATCHLIST_SCREENING

Webhook Service

services/us-api/src/webhooks/webhookService.ts

Method Description
dispatchWebhook Finds active webhook endpoints for a partner, signs the payload, and delivers the event

Jobs

services/us-api/src/jobs/featureDriftJob.ts

Method Description
runDailyFeatureDriftCheck Runs drift detection with the global credit feature schema and training baseline label

services/us-api/src/jobs/retrainTriggerJob.ts

Method Description
evaluateRetrainingForModel Delegates retraining evaluation to the model governance service

US API Service Notes

src/services/consentService.ts writes new consents with PENDING_USER_ACTION, while ensureConsentActive only accepts ACTIVE. That means a newly created consent must be advanced by another flow before data-access handlers will serve it.

E Housing Backend Boundary

The backend side of the e-housing product is represented in this context by the Python use-case module and the test application helper. These files show the backend’s role as the product domain that powers application-level logic and request orchestration.

Account Coverage Inference

backend/src/usecase/account_detection.py

AccountCoverageResult

Property Type
status str
reported_accounts int
detected_accounts int
missing_accounts int
coverage_ratio Optional[float]
details list[dict[str, Any]]
errors list[str]
Function Description
_normalise_string Trims and validates string input
_iter_connected_account_records Walks the connected_accounts container
_collect_plaid_entries Collects Plaid-specific account submissions keyed by access token
infer_account_coverage Compares submitted accounts against Plaid-detected accounts and produces a coverage result

Test Application Helper

backend/src/scripts/create_test_application.py

Function Description
_default_payload Builds the request body for the test application create call
_build_headers Builds content-type and optional bearer headers
_request_json Sends an HTTP request and parses a JSON response
main Creates a test application, fetches its detail record, and prints the score summary

This backend boundary is paired with documents/account-coverage.md, which documents the endpoint contract and points back to the backend use-case and schema files.

Dashboard Labeling and Provider Maps

frontend/app/application/connect-accounts/providers.ts centralizes provider selection and country-specific bank labels for the connect-accounts flow. It is the clearest code-level example of dashboard labeling in the repository context because it turns the user’s country and account type into the provider and bank choices shown in the UI.

Provider Label Contracts

Type Purpose
AccountType Restricts connect-account flows to personal or investment
Provider Restricts provider selection to plaid or saltedge
Bank Describes a bank card in the UI
ProviderDetail Bundles provider metadata plus personal and investment banks
CountryOverride Allows country-specific overrides for provider metadata and bank lists

Provider Selection Helpers

Function Description
toCountryKey Normalizes a country string into a lookup key
getInvestmentDescriptionForCountry Returns the investment-category descriptor for a country
getCountryBankConfig Returns the selected provider, provider name, connect URL, and banks for a country and account type
getOpenBankingProvidersForCountry Returns the open-banking provider options for a country
getDefaultOpenBankingProviderForCountry Returns the default open-banking provider option
getOpenBankingProviderById Looks up a provider option by ID

Country and Provider Layout

frontend/app/application/connect-accounts/providers.ts contains explicit country overrides for:

united states, canada, united kingdom, ireland, france, spain, sweden, japan, singapore, and hong kong.

FALLBACK_PLAID_COUNTRIES currently contains united states and canada.

Operational Documentation and Memory

documents/ is the published engineering/product documentation surface, while workspace/ is the persistent operational memory surface. The documents folder captures user-facing and engineering-facing explanations such as account coverage and label availability, and workspace keeps the mutable repo map, patterns, decisions, changelog, and TODO state that future sessions rely on.

Testing Considerations

The repo’s source context shows tests in both the US services and the Go gateway.

Area Evidence Coverage Focus
services/us-api/test/flows.test.ts Fastify route injection with mocked Prisma and auth middleware Consent creation, revoke flow, refresh limit, category enforcement
services/us-api/test/psuConsentAnalytics.test.ts Analytics and watchdog imports Consent event processing, metrics refresh, timeout handling
services/us-data-gateway/internal/handlers/handlers_test.go HTTP recorder tests JSON error mapping for CATEGORY_NOT_ALLOWED and CONSENT_REVOKED

Key Classes Reference

Class Responsibility
REPO_MAP.md Persistent map of the repository’s top-level boundaries
PATTERNS.md Durable engineering and architecture conventions
Config Reads runtime settings for the US data gateway
Handler Serves US banking data endpoints and enforces consent checks
Provider Contract for banking data retrieval implementations
MockProvider Sample provider implementation used by the gateway bootstrap
AccountCoverageResult Captures account coverage inference results
CreateConsentPayload Describes consent creation input
DecisionPayload Describes scoring decisions and audit fields
GlobalCreditFeatureSchemaV1 Defines the normalized credit feature schema
FeatureMigrationResult Captures schema migration output for evidence snapshots
create_test_application.py Creates and inspects a test application through the backend API
account_detection.py Infers account coverage from submitted and detected account sets
consentService.ts Owns consent creation, receipt, revocation, and active-state checks
scoringService.ts Validates, stores, and replays scoring decisions
modelGovernanceService.ts Owns feature schema, drift, and retraining governance
featureService.ts Generates and stores cashflow evidence snapshots
webhookService.ts Delivers signed partner webhooks
providers.ts Resolves connect-account provider and bank labels by country