User Dashboard Domain - Housing Label Service Ingestion Pipeline and Dashboard Summary Contract

Overview

The housing-label-service sits in the user dashboard domain as the transaction normalization boundary for labeled housing data. It accepts normalized transaction feeds from Plaid and Salt Edge, assigns housing-relevant labels, stores the labeled records, and exposes a dashboard-ready summary for a specific user.

The service also includes an optional ML assist hook that can participate in the ingestion path after transactions have been normalized and labeled. That hook is used as an augmentation step rather than as the public contract surface, while the dashboard summary endpoint consumes the stored labeled data and returns aggregates that are suitable for the user dashboard flow.

Architecture Overview

flowchart TB
    subgraph HousingLabelService [Housing label service]
        Routes[API routes]
        Labeling[Normalization and labeling]
        Store[Transaction storage]
        MLHook[Optional ML assist hook]
        Summary[Dashboard summary builder]
        Routes --> Labeling
        Labeling --> Store
        Labeling -.-> MLHook
        Store --> Summary
    end

    Plaid[Plaid normalized transactions]
    SaltEdge[Salt Edge normalized transactions]
    Dashboard[Dashboard client]

    Plaid --> Routes
    SaltEdge --> Routes
    Summary --> Dashboard

Service Surface

README.md

File: platform/housing-label-service/README.md

The service README is the top-level reference for the housing-label-service package. It describes the ingestion pipeline, the summary contract, and how the service fits the dashboard domain.

package.json

File: platform/housing-label-service/package.json

This file defines the Node package metadata, runtime dependencies, and the scripts used to run, build, and test the service.

jest.config.js

File: platform/housing-label-service/jest.config.js

This file configures Jest for the housing-label-service test suite.

src/api/routes.ts

File: platform/housing-label-service/src/api/routes.ts

This module defines the HTTP routes for transaction ingestion and dashboard summary retrieval.

src/services/ml-hook.ts

File: platform/housing-label-service/src/services/ml-hook.ts

This module provides the ML assist hook used as an optional step in the ingestion pipeline.

Ingestion Pipeline

The ingestion path accepts normalized transactions that already represent Plaid or Salt Edge data in a common shape. The route layer passes those transactions into the labeling pipeline, where they are enriched with housing-oriented labels, persisted, and optionally passed through the ML assist hook before they are made available for downstream dashboard aggregation.

The important contract boundary is that the service works from normalized transaction input, not raw provider-specific payloads. That keeps provider-specific normalization outside this service and lets the service focus on labeling, storage, and dashboard-ready output.

Ingest Transactions

{
    "title": "Ingest Transactions",
    "description": "Accepts normalized Plaid and Salt Edge transactions, applies housing labels, optionally passes them through the ML assist hook, and stores the labeled result for dashboard aggregation.",
    "method": "POST",
    "baseUrl": "<HousingLabelServiceBaseUrl>",
    "endpoint": "/api/ingest",
    "headers": [
        {
            "key": "Content-Type",
            "value": "application/json",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [],
    "bodyType": "json",
    "requestBody": "{\n    \"transactions\": [\n        {\n            \"id\": \"txn_12345\",\n            \"provider\": \"Plaid\",\n            \"accountId\": \"acc_67890\",\n            \"amount\": 124.56,\n            \"currency\": \"USD\",\n            \"postedAt\": \"2026-04-20\",\n            \"merchantName\": \"Grocery Market\",\n            \"description\": \"Card purchase\",\n            \"category\": \"groceries\",\n            \"sourceTransactionId\": \"plaid_txn_abc123\"\n        },\n        {\n            \"id\": \"txn_54321\",\n            \"provider\": \"Salt Edge\",\n            \"accountId\": \"acc_24680\",\n            \"amount\": 89.99,\n            \"currency\": \"USD\",\n            \"postedAt\": \"2026-04-19\",\n            \"merchantName\": \"Electric Company\",\n            \"description\": \"Utility bill\",\n            \"category\": \"utilities\",\n            \"sourceTransactionId\": \"saltedge_txn_def456\"\n        }\n    ]\n}",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Transactions were labeled and stored",
            "body": "[]"
        }
    }
}

Ingestion Flow

  1. The client submits a normalized transaction batch to /api/ingest.
  2. src/api/routes.ts dispatches the payload into the service pipeline.
  3. Transactions are labeled using housing-oriented rules.
  4. The labeled records are stored for later dashboard aggregation.
  5. If the ML assist hook is enabled for the path, src/services/ml-hook.ts participates as an optional augmentation step.
  6. The service returns a processed response to the caller.
sequenceDiagram
    participant Client as Client
    participant Routes as API routes
    participant Labeling as Labeling pipeline
    participant Hook as ML assist hook
    participant Store as Storage

    Client->>Routes: POST /api/ingest
    Routes->>Labeling: normalized transactions
    Labeling->>Hook: optional assist input
    Hook-->>Labeling: assist output
    Labeling->>Store: labeled transactions
    Store-->>Routes: persisted result
    Routes-->>Client: ingest response

Dashboard Summary Contract

[!NOTE] The ingest contract is centered on normalized provider data. Plaid and Salt Edge data are consumed after normalization, so the service is responsible for labeling and storage rather than provider-specific parsing.

The dashboard summary contract exposes a user-specific aggregate view built from the stored labeled transactions. The summary is the dashboard-ready surface that downstream UI code can consume directly without reassembling provider-level transaction records.

The route is keyed by user ID, which ties the summary to the individual dashboard owner rather than to the transaction source. The stored labeled data is the input to the summary response, and the service returns aggregated data that reflects the user’s labeled housing activity.

Get User Dashboard Summary

{
    "title": "Get User Dashboard Summary",
    "description": "Returns the dashboard-ready aggregate summary for the specified user based on labeled transaction data.",
    "method": "GET",
    "baseUrl": "<HousingLabelServiceBaseUrl>",
    "endpoint": "/api/dashboard/:userId/summary",
    "headers": [],
    "queryParams": [],
    "pathParams": [
        {
            "name": "userId",
            "required": true,
            "description": "User identifier used to load the dashboard summary"
        }
    ],
    "bodyType": "none",
    "requestBody": "",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Dashboard summary for the user",
            "body": "[]"
        }
    }
}

Summary Flow

  1. The dashboard requests the summary for a specific userId.
  2. src/api/routes.ts resolves the request to the summary contract.
  3. The service reads the stored labeled transactions for that user.
  4. Aggregates are assembled into a dashboard-ready summary.
  5. The summary payload is returned to the dashboard client.
sequenceDiagram
    participant Client as Dashboard client
    participant Routes as API routes
    participant Store as Storage
    participant Summary as Summary builder

    Client->>Routes: GET /api/dashboard/userId/summary
    Routes->>Store: read labeled transactions
    Store-->>Routes: stored records
    Routes->>Summary: build aggregates
    Summary-->>Routes: dashboard summary
    Routes-->>Client: summary response

ML Assist Hook

src/services/ml-hook.ts represents the optional augmentation step in the ingestion pipeline. Its role is to participate after the service has received normalized transactions and before the result is finalized for storage and downstream summary use.

The hook is part of the ingest path only. The dashboard summary contract consumes the stored labeled output and does not depend on the hook directly at read time.

Testing and Package Configuration

package.json and jest.config.js define the service package and its test execution setup. Together they support unit-level validation of the route contract and the ML assist hook behavior.

Typical test coverage for this package centers on:

  • ingestion route dispatch
  • label assignment for normalized transaction batches
  • optional ML assist hook participation
  • summary retrieval by userId
  • dashboard aggregate response shape

Integration Points

  • Plaid normalized transaction feed: supplies one of the supported normalized transaction sources.
  • Salt Edge normalized transaction feed: supplies the second supported normalized transaction source.
  • Dashboard client: consumes the /api/dashboard/:userId/summary contract.
  • ML assist hook: optionally augments the ingestion pipeline after labeling.

Error Handling

The service’s externally visible contract is concentrated in route handling and the ML assist hook. Errors in the ingest path affect labeled transaction persistence, while errors in the summary path affect the user’s dashboard aggregate response.

Key Classes Reference

Class Responsibility
README.md Service-level documentation for ingestion and dashboard summary behavior
package.json Package metadata, dependencies, and service scripts
jest.config.js Jest test configuration for the service package
routes.ts HTTP route definitions for ingest and dashboard summary
ml-hook.ts Optional ML assist hook used during ingestion