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
- The client submits a normalized transaction batch to
/api/ingest. src/api/routes.tsdispatches the payload into the service pipeline.- Transactions are labeled using housing-oriented rules.
- The labeled records are stored for later dashboard aggregation.
- If the ML assist hook is enabled for the path,
src/services/ml-hook.tsparticipates as an optional augmentation step. - 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
- The dashboard requests the summary for a specific
userId. src/api/routes.tsresolves the request to the summary contract.- The service reads the stored labeled transactions for that user.
- Aggregates are assembled into a dashboard-ready summary.
- 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/summarycontract. - 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 |