Engineering Reference, Workspace Memory, and Supporting Documents

Overview

This section is the shared engineering memory for the repo’s operational procedures, published API contracts, and domain design notes. It answers the questions engineers usually ask before they open the implementation: how to run the stack locally, how production deployment is performed, what the customer-facing API contracts promise, and which feature decisions are intentional versus incidental.

Use these documents when you need the repo’s operational truth or product intent. Prefer code inspection when you need the current branching logic, exact validation behavior, or a live implementation detail that may have drifted from the written guidance.

Document Map

flowchart TD
    Q[Engineering question] --> Ops[Operational runbook]
    Q --> Spec[API specification]
    Q --> Impl[Implementation overview]
    Q --> Note[Domain design note]

    Ops --> Dev[development and deployment]
    Ops --> Test[lita testing and Vertex verification]
    Spec --> Consent[Lita consent and US API]
    Impl --> Behavior[Current implemented behavior]
    Note --> Partner[Sothebys and Spinwheel plans]
Document What question it answers Prefer it over code inspection when
development.md How do I set up and use the repo locally, including Docker Compose, env files, and local application data? You need exact local commands, developer account setup, or troubleshooting steps for the workspace
deployment.md How is the MVP deployed, verified, and rolled back across Compose, GCP, Fastly, and schema updates? You are deploying, validating production, or applying schema changes to a long-lived database
lita-testing-guide.md How do I smoke-test the Lita consent-data API end to end? You want the canonical local test flow, curl examples, or idempotency checks
lita-consent-data-api.md What is the customer-facing consent-based data access and scoring contract? You need the published API model, auth headers, SLA commitments, or legal framing
us-api-v1.md What is the US-specific consent, data, feature, webhook, and scoring contract? You are integrating the US product surface or checking allowed purpose and category rules
account-coverage.md How does the backend infer missing connected accounts relative to Plaid’s detected accounts? You are reviewing account completeness logic, support cases, or application coverage behavior
vertex_ai_verification.md How do I verify the Vertex AI training and deployment pipeline end to end? You are working on the TransUnion / Vertex AI orchestration or validating endpoint readiness
lita-implementation-overview.md What does the current Lita consent-data implementation actually do today? You need runtime behavior, persistence mapping, or error handling instead of the broader spec
feature-availability.md How does the dashboard derive connected account labels and fallback values? You need the exact UI behavior for feature availability or account type rendering
sothebys-agent-initiated-credit-access.md How should an operator-initiated credit pull workflow work for Sotheby’s Japan? You are scoping the partner workflow, compliance posture, or operational controls
sothebys-open-banking-refresh.md What is and is not possible for staff-initiated open-banking refresh with Plaid? You are setting stakeholder expectations about zero-touch refresh and re-auth limits
spinwheel-integration-plan.md How should the team think about a Spinwheel-like U.S. intake flow and future API strategy? You are scoping the Equifax-based intake flow, competitive positioning, or product roadmap

Operational Runbooks

Development Workspace Setup

[!IMPORTANT] The documents here are not interchangeable: some are runbooks, some are specifications, and some are design notes. Treat them as the fastest path to the right mental model, then inspect code only for the exact implementation path you are about to change.

documents/development.md

This guide answers: how do I get the workspace running locally and keep it usable during development?

It covers:

  • Required tooling for the repo: VS Code, git, Docker, Google Cloud SDK, Python 3.10, and Node.js 20.9+.
  • .env setup from env_template.
  • Developer-facing reviewer accounts and role assignment behavior.
  • Local Docker Compose startup for the backend and frontend.
  • The local application data path used by the frontend API route.
  • Debugging steps for invalid applicant IDs and container log inspection.

Use this guide instead of code inspection when:

  • You need the exact local startup command.
  • You need the current repo-specific environment variables.
  • You are debugging local dashboard data, route fallbacks, or reviewer/admin test accounts.

Deployment Runbook

documents/deployment.md

This guide answers: how is the MVP deployed, validated, and kept stable in production?

It covers:

  • Fastly in front of the Google Cloud HTTPS Load Balancer.
  • Compute Engine deployment using Docker Compose.
  • GitHub Actions-based build, push, and SSH rollout flow.
  • Production environment variables and application storage settings.
  • Schema application for persistent production databases.
  • Pre-launch stability checks and post-deployment verification commands.

Use this guide instead of code inspection when:

  • You are performing or reviewing a rollout.
  • You need the production routing model.
  • You need to know when schema application is required after pulling new code.
  • You are checking what “healthy deployment” means in this repo’s operations model.

[!NOTE] This document is the canonical place for production deployment mechanics, including the schema helper and the distinction between first-time database initialization and updates to an existing long-lived MySQL volume.

documents/lita-testing-guide.md

This guide answers: how do I prove the consent, token, snapshot, and scoring endpoints work locally?

It covers:

  • Targeted pytest execution for the Lita endpoint module.
  • A one-shot smoke-test script.
  • A full curl-based sequence for consent creation, token issuance, snapshot persistence, snapshot retrieval, and scoring.
  • Troubleshooting guidance for missing or expired bearer tokens and database connectivity.

Use this guide instead of code inspection when:

  • You want the repo’s intended local verification path.
  • You need the exact request bodies used to validate the consent API flow.
  • You are confirming idempotency behavior at the command line.

Vertex AI Verification Guide

documents/vertex_ai_verification.md

This guide answers: how do I verify the Vertex AI training and deployment pipeline without guessing at the orchestration steps?

It covers:

  • Environment preparation for local or prod deployment files.
  • Artifact Registry authentication and repository creation.
  • Building and pushing the training image.
  • Running the pipeline orchestrator through Docker Compose.
  • Fast checks for endpoint readiness and runtime prediction behavior.
  • Failure modes related to image architecture, serving-contract mismatches, and memory pressure.

Use this guide instead of code inspection when:

  • You are validating the TransUnion training and serving path.
  • You need to confirm whether a failure is a pipeline issue, a model artifact issue, or an endpoint readiness issue.
  • You are running the compose-backed orchestration scripts.

API Specifications and Contract Docs

[!IMPORTANT] This guide is the fastest path to understanding how the Vertex AI jobs are expected to be invoked, what environment variables control them, and which error states are considered infrastructure problems versus data or model problems.

documents/lita-consent-data-api.md

This specification answers: what does the customer-facing consent-based API promise, and what are its security and retention rules?

It defines:

  • The consent-based access model.
  • Authentication and authorization headers.
  • The client-hosted scoring endpoint contract.
  • Versioning rules.
  • Retention and audit principles.
  • SLA targets and a glossary of core terms.

Use this specification instead of code inspection when:

  • You need the externally communicated API contract.
  • You are discussing legal, compliance, retention, or long-lived access behavior.
  • You are implementing against the published scoring request and response model.

Lita US API

documents/us-api-v1.md

This specification answers: what is the U.S.-specific consent, data, feature, webhook, and scoring surface?

It defines:

  • U.S. consent semantics and required purpose values.
  • Supported data categories and connection statuses.
  • Partner authentication headers.
  • Consent-scoped access tokens.
  • Data access endpoints for accounts, balances, transactions, income, and features.
  • Webhook registration and delivery semantics.
  • US-specific error codes and compliance constraints.

Use this specification instead of code inspection when:

  • You are integrating with the U.S. product surface.
  • You need to know which purposes and categories are allowed.
  • You are validating webhook, token, and data-access expectations for partner integrations.

Implementation and Behavior Notes

Account Coverage Inference

[!NOTE] This document is the clearest source for U.S. product behavior because it separates consent, connection, access, feature computation, and scoring into distinct contract sections.

documents/account-coverage.md

This note answers: how does the backend decide whether the applicant submitted all Plaid-detected accounts?

It documents:

  • The comparison between connected_accounts and the full set of detected Plaid accounts.
  • The meaning of complete, incomplete, and unknown.
  • Per-connection detail fields.
  • The sequence used to derive missing accounts and coverage ratios.

Use this note instead of code inspection when:

  • You need the operational definition of account coverage.
  • You are investigating why an application appears incomplete.
  • You want to understand what the endpoint reports to reviewers or automation.

Lita Implementation Overview

documents/lita-implementation-overview.md

This note answers: what is the current behavior of the Lita consent/data routes as actually implemented?

It documents:

  • Consent creation, fetch, token issuance, and revocation checks.
  • Snapshot storage and latest snapshot retrieval.
  • Scoring behavior, including deterministic scoring and request-id-based idempotency.
  • Repository-backed persistence models and timestamp behavior.
  • Auth and error-handling behavior for token-gated routes.

Use this note instead of code inspection when:

  • You need the current implementation behavior, not just the product spec.
  • You are tracing what tables and models back the Lita routes.
  • You want a compact summary of auth, persistence, and error handling.

Feature Availability Notes

documents/feature-availability.md

This note answers: what connected account labels will the dashboard show when the backend payload is sparse?

It documents:

  • The dashboard’s account-type label fallback behavior.
  • The fact that the current implementation derives the label from backend payload data.
  • The fallback value of account when no type is supplied.

Use this note instead of code inspection when:

  • You are checking a UI label or display issue.
  • You need to know whether a value is hard-coded or payload-driven.
  • You are validating whether the frontend expects a specific backend account type.

Domain Design Notes

Sotheby’s Agent Initiated Credit Access

documents/sothebys-agent-initiated-credit-access.md

This design note answers: how should a staff-initiated Japanese bureau pull workflow work when an operator acts on behalf of a consented customer?

It covers:

  • The desired flow from consent capture to operator-triggered bureau requests.
  • Compliance requirements under APPI.
  • Security controls such as IP allowlists, mutual TLS, role-based permissions, and audit trails.
  • Implementation planning for bureau due diligence, dashboard/API changes, notifications, and pilot rollout.

Use this note instead of code inspection when:

  • You are discussing product strategy with partners or compliance.
  • You need the intended operating model, not an implemented route.
  • You are scoping the Japanese bureau workflow.

Sotheby’s Open Banking Refresh Workflow

documents/sothebys-open-banking-refresh.md

This design note answers: what level of “zero-touch” refresh is actually allowed with Plaid and similar open-banking rails?

It clarifies:

  • The one-time customer authentication requirement.
  • What staff-initiated refresh can do within a valid consent window.
  • What is not allowed, including first-time login on behalf of a customer.
  • The recommended implementation pattern for delegated consent, background refresh, and failover UX.

Use this note instead of code inspection when:

  • You are managing expectations with stakeholders.
  • You need to explain why some refreshes still require customer interaction.
  • You are planning the customer and operator experience around open-banking refresh.

Spinwheel Integration Plan

documents/spinwheel-integration-plan.md

This design note answers: how should the team build a Spinwheel-like U.S. intake flow, and what is the broader product strategy around it?

It covers:

  • The proposed use of Equifax Instant ID and OneView.
  • A backend service-layer plan.
  • PII handling and consent/audit expectations.
  • Frontend messaging for a streamlined phone-based application flow.
  • Competitive pricing research and investor messaging.
  • A longer-term API product roadmap.

Use this note instead of code inspection when:

  • You are scoping the U.S. intake workflow.
  • You need the business rationale for the integration.
  • You are discussing future partner APIs or positioning.

How to Use These Documents as Workspace Memory

These files are the repo’s durable memory for operational and product intent. They preserve facts that are easy to lose in code alone:

  • exact local and production commands,
  • deployment and verification sequences,
  • published API contracts,
  • behavior that is intentionally exposed to users or partners,
  • and partner-specific design direction that is not yet implemented.

A practical rule:

  • Read the document first when the question is “what is supposed to happen?”
  • Read the code first when the question is “what happens on this line right now?”

Key Classes Reference

Class Responsibility
development.md Local setup, environment preparation, and developer troubleshooting
deployment.md Production deployment, rollout, and verification guidance
lita-testing-guide.md Local smoke testing for the Lita consent-data API
lita-consent-data-api.md Customer-facing consent-based API contract and operating model
us-api-v1.md U.S.-specific consent, data, feature, webhook, and scoring contract
account-coverage.md Account completeness inference and status rules
vertex_ai_verification.md Vertex AI training and endpoint verification workflow
lita-implementation-overview.md Current implementation behavior for the consent-data API
feature-availability.md Frontend label fallback behavior for connected accounts
sothebys-agent-initiated-credit-access.md Proposed Japanese staff-initiated credit access workflow
sothebys-open-banking-refresh.md Constraints and design for staff-initiated open-banking refresh
spinwheel-integration-plan.md U.S. intake integration plan and future API strategy