PLAID READ-ONLYUSER STORIES → WORKFLOWSNO LIVE CALLS

Basic Plaid user stories for real app actions.

This artifact turns the Plaid prototype into implementation-ready user stories. Each story names the normal user command, screen, UI actions, backend/Plaid action, success state, blocked state, and build requirements.

ConnectAccountsTransactionsInsightsInvestmentsRecovery

Connect stories.

Users need clear account-linking actions before any account data exists.

Connect

Link first institution

As a user, I want to connect my first bank with Plaid, so that Helm can show my balances, transactions, and account history.

Command + screen

Command: “Connect my bank.” Screen: Accounts empty state with one primary CTA, Connect account with Plaid.

  • Tap Connect account.
  • Complete native Plaid Link.
  • Return to Accounts with sync progress.

Success

Institution appears with linked status and first-sync progress.

Blocked

Link canceled, token exchange fails, Plaid not configured, or OAuth redirect missing.

Backend + build

POST /plaid/link-token
Open native LinkKit
POST /plaid/public-token/exchange
  • LinkKit lifecycle
  • Server-owned token storage
  • LIVE_UNLINKED and linking states
Connect

Add another institution

As a user, I want to add another bank or credit union, so that Helm can aggregate all my accounts in one place.

Command + screen

Command: “Add my credit union too.” Screen: Accounts overview with Add institution CTA.

  • Tap Add institution.
  • Link another Plaid Item.
  • See per-institution sync status.

Success

New institution appears without hiding existing data.

Blocked

Unsupported institution, duplicate Item, OAuth failure, or user cancel.

Backend + build

POST /plaid/link-token
Append Item to user item store
GET /plaid/status
  • Add-institution CTA
  • Duplicate handling
  • Per-item progress cards

Accounts stories.

Users should understand current financial position, freshness, and account inclusion.

Accounts

Show account overview

As a user, I want to see where my money is right now, so that I can quickly understand cash, credit, investment, and loan positions.

Command + screen

Command: “Show me where my money is.” Screen: Account overview grouped by account type and institution.

  • View grouped balances.
  • Tap an institution/account for detail.
  • See freshness timestamps.

Success

Fresh balances show grouped totals and account source.

Blocked

Partial item failure, stale data, or account product unavailable.

Backend + build

GET /plaid/status
GET /plaid/accounts
GET /plaid/balances
  • Grouped balance cards
  • Freshness labels
  • Account detail screen
Accounts

Refresh accounts

As a user, I want to refresh my accounts now, so that I know whether balances and transactions are current.

Command + screen

Command: “Refresh my accounts.” Screen: Pull-to-refresh or Refresh button on Accounts.

  • Tap Refresh.
  • Watch per-institution progress.
  • See updated freshness or exact blocker.

Success

Freshness timestamp updates and new data appears.

Blocked

Rate limit, institution unavailable, reauth required, or partial refresh failure.

Backend + build

POST /plaid/sync/refresh
GET /plaid/status
  • Refresh affordance
  • Rate-limit message
  • Per-item refresh status
Accounts

Exclude account from insights

As a user, I want to exclude an account from insights, so that charts do not mix savings, shared, or business accounts into personal spending.

Command + screen

Command: “Don’t include this savings account in spending insights.” Screen: Account detail settings.

  • Toggle Include in insights.
  • See excluded badge.
  • Charts recalculate without hiding the account.

Success

Insight totals exclude selected account and show the rule.

Blocked

Account unavailable; preference still saved locally if account ID is known.

Backend + build

PATCH /plaid/accounts/{id}/preferences
Recompute insight summaries
  • Account settings
  • Inclusion flags
  • Visible excluded badge

Transaction stories.

Users need normal search, filtering, transaction detail, and correction actions.

Transactions

Explore last 90 days

As a user, I want to see my last 90 days and what changed, so that I can understand recent financial behavior.

Command + screen

Command: “Show my last 90 days and explain what changed.” Screen: History explorer with cashflow chart and drivers.

  • Select 90d range.
  • Tap category or chart point.
  • Drill into transactions behind the spike.

Success

Cashflow chart and top drivers link to transaction evidence.

Blocked

No transactions, first sync pending, or selected item lacks transaction product.

Backend + build

GET /plaid/transactions?range=90d
Compute prior-period comparison
Return chart series + drivers
  • Date range picker
  • Chart drilldown
  • Comparison explanations
Transactions

Search transactions

As a user, I want to search charges by merchant, amount, category, and date, so that I can find specific spending quickly.

Command + screen

Command: “Find all Amazon charges over $50.” Screen: Transaction search with filter chips.

  • Enter merchant.
  • Add amount/category/date filters.
  • Open transaction detail.

Success

Filtered list shows count, total, and matched transactions.

Blocked

No matches, sync incomplete, or selected account disconnected.

Backend + build

GET /plaid/transactions/search
Normalize merchant names
  • Search bar
  • Merchant normalization
  • Empty result state
Transactions

Annotate transaction

As a user, I want to tag or recategorize a transaction, so that Helm insights reflect how I think about my spending.

Command + screen

Command: “Mark this as business expense.” Screen: Transaction detail sheet.

  • Tap transaction.
  • Change category or add tag/note.
  • See charts update with override indicator.

Success

Local override is saved; Plaid source data is not mutated.

Blocked

Transaction later changes; conflict shown with keep/update choice.

Backend + build

PATCH /plaid/transactions/{id}/override
Recompute analytics from overrides
  • Transaction detail sheet
  • Local override model
  • Override indicator

Insight stories.

Users need commands that convert raw transactions into useful decisions.

Insights

Find recurring bills

As a user, I want to find recurring charges and price changes, so that I can review subscriptions and bills.

Command + screen

Command: “Find recurring bills and anything that changed.” Screen: Recurring payments insight list.

  • View recurring merchants.
  • Tap price change.
  • Create review reminder or dismiss.

Success

Recurring merchants show next expected date and price drift.

Blocked

Not enough transaction history or low confidence pattern.

Backend + build

GET /plaid/transactions/sync
Cluster recurring merchants
Detect amount drift
  • Recurring detector
  • Confidence labels
  • Reminder/save/dismiss actions
Insights

Explain spending spike

As a user, I want Helm to explain a spending spike, so that I know whether it was normal, recurring, or unusual.

Command + screen

Command: “Why did food spending jump?” Screen: Category insight detail with evidence rows.

  • Tap category bar.
  • See merchants that drove the spike.
  • Save insight or mark as expected.

Success

Spike explanation shows merchant drivers and transaction evidence.

Blocked

Insufficient prior-period data or transfer/refund ambiguity.

Backend + build

GET /plaid/insights/spending-spikes
Compare category + merchant series
  • Category chart drilldown
  • Driver ranking
  • Expected/unexpected feedback

Investment stories.

Plaid investments should support history and research context, never order execution.

Investments

Review holdings and activity

As a user, I want to see my holdings and investment history, so that I can understand allocations, contributions, dividends, and fees.

Command + screen

Command: “Show my holdings and investment history.” Screen: Investments dashboard with allocation chart and activity timeline.

  • View holdings by institution/symbol.
  • Tap allocation segment.
  • Review buys, sells, dividends, transfers, fees.

Success

Holdings and investment transactions display with source/freshness labels.

Blocked

Investment product unavailable, stale securities, missing ticker/cost basis.

Backend + build

GET /plaid/investments/holdings
GET /plaid/investments/history
Map securities + activity types
  • Holdings table
  • Allocation chart
  • Activity timeline
  • Not-for-trading boundary

Recovery stories.

Users need direct answers when data is missing, stale, or disconnected.

Recovery

Fix stale connection

As a user, I want to know why a bank is not updating, so that I can fix only the broken connection without losing healthy data.

Command + screen

Command: “Why is my bank not updating?” Screen: Connected institutions health list.

  • Open institution health.
  • Read exact safe issue.
  • Tap Reconnect institution when required.

Success

Broken institution updates; healthy institutions remained visible throughout.

Blocked

OAuth redirect mismatch, institution action required, Plaid rate limit, or update-mode Link failure.

Backend + build

GET /plaid/status
GET /plaid/item-errors
POST /plaid/link-token?mode=update
  • Health list
  • Sanitized error mapping
  • Update-mode Link flow
Recovery

Export or remove data

As a user, I want to export or remove my Plaid data, so that I stay in control of my financial information.

Command + screen

Command: “Export my transactions for taxes” or “Remove this institution.” Screen: Data controls / institution settings.

  • Choose export range/accounts.
  • Confirm destructive unlink/removal.
  • See final status and what remains.

Success

CSV/export generated, or Item removed/revoked and no longer syncs.

Blocked

No transactions in range, export error, Plaid remove failure, or local cleanup partial success.

Backend + build

GET /plaid/user-data/export
DELETE /plaid/items/{id}
  • Export modal
  • Confirm destructive action
  • Revocation/local cleanup
  • Post-delete state

Implementation gates.

Each story should pass these checks before becoming an app task.

Pre-flight gate

Endpoint contract, screen owner, state machine, and safety labels are defined before implementation.

Revision gate

If a story lacks success/blocked states or clear build requirements, revise the artifact before coding.

Abort gate

If a path would expose secrets, fake live data, or mix Plaid with broker execution, stop and redesign.

Showcase only: This artifact is static. It contains no Plaid secrets, no Link session, no live API calls, no broker controls, and no user data. Plaid is for read-only aggregation/history; broker preview/review remains a separate rail.