ghostfolio/specs/009-fmv-plaid-drilldown/research.md

Research: 009-fmv-plaid-drilldown

Date: 2026-03-22

R1: Admin-Gated Features — Navigation & Permission Analysis

Decision: Move legacy features out of admin gate in header template

Rationale

• All 7 legacy features (Overview, Holdings, Summary, Markets, Watchlist, FIRE, X-Ray) are hidden behind @if (hasPermissionToAccessAdminControl) in header.component.html (desktop L76–107, mobile L338–416)
• hasPermissionToAccessAdminControl is only true for ADMIN role (USER lacks accessAdminControl permission)
• API endpoints do NOT require admin permission — all portfolio endpoints (/portfolio/details, /portfolio/holdings, /portfolio/performance, /portfolio/investments, /portfolio/report) use JWT auth only, no @HasPermission decorator
• Watchlist: USER has createWatchlistItem, deleteWatchlistItem, readWatchlist — fully functional
• FIRE & X-Ray: Use JWT-only portfolio endpoints
• Markets basic view: Does NOT call the readMarketDataOfMarkets-gated endpoint; only the premium Markets view does (which requires readMarketDataOfMarkets, dynamically granted to Premium subscribers of any role)

Implementation Approach

• Extract legacy items from the Admin dropdown and add them as standalone nav items visible to all authenticated users
• No API permission changes needed for Overview, Holdings, Summary, Watchlist, FIRE, X-Ray
• Markets basic view works as-is; premium Markets view requires Premium subscription (existing behavior, not a role gate)

Alternatives Considered

1. Grant accessAdminControl to USER — Rejected: would also expose Admin Control panel, resource management, and other admin-only features
2. Create a new permission per feature — Rejected: Simplicity First; the features already work for any authenticated user, only the nav is gated

---

R2: FMV Dashboard — Existing Data Pipeline

Decision: Reuse existing PortfolioService.getAccountsWithAggregations() for FMV data

Rationale

• getAccountsWithAggregations() already returns AccountsResponse with:
  • totalValueInBaseCurrency — aggregate FMV across all accounts
  • totalBalanceInBaseCurrency — aggregate cash
  • Per-account: valueInBaseCurrency, balanceInBaseCurrency, allocationInPercentage, activitiesCount, platform
• Per-account value computed in getValueOfAccountsAndPlatforms(): valueInBaseCurrency = FX(cashBalance) + Σ(quantity × marketPrice) per account
• Multi-currency conversion handled by ExchangeRateDataService.toCurrency()
• AccountWithValue type already has all fields needed: value, valueInBaseCurrency, balanceInBaseCurrency, allocationInPercentage, platform, activitiesCount
• Excluded accounts filtered via isExcluded field on Account model

Implementation Approach

• New Angular page/component at /fmv or /fmv/dashboard route
• Calls existing GET /api/v1/account endpoint (returns AccountsResponse)
• Renders hero total (totalValueInBaseCurrency) + account cards
• Each account card links to existing account-detail-dialog for drill-down
• No new API endpoints needed — existing data is sufficient

Alternatives Considered

1. New dedicated /api/v1/fmv endpoint — Rejected: existing accounts endpoint already provides all needed data; Simplicity First principle
2. Separate FMV calculation service — Rejected: duplicates getValueOfAccountsAndPlatforms() logic

---

R3: Asset Drill-Down — Existing Account Detail Pattern

Decision: Leverage existing account-detail-dialog with enhanced entry point from FMV view

Rationale

• AccountDetailDialogComponent already provides:
  • Holdings tab: GfHoldingsTableComponent filtered by accountId
  • Activities tab: orders/transactions filtered by account
  • Cash Balances tab: AccountBalance history
• Holdings filtering works via filters: [{ id: accountId, type: 'ACCOUNT' }] passed to getHoldings()
• PortfolioPosition interface includes: quantity, investment (cost basis), valueInBaseCurrency, netPerformance, netPerformancePercent, assetProfile (name, symbol, assetClass)
• Clicking a holding row opens position detail with price chart, activity history, dividends, sector/country breakdown
• Sorting already supported in GfHoldingsTableComponent

Implementation Approach

• FMV account cards open existing AccountDetailDialogComponent with proper accountId
• No new drill-down components needed — existing dialog has all required tabs
• Ensure holdings table columns show: symbol, name, quantity, cost basis (investment), current value, gain/loss

Alternatives Considered

1. New dedicated drill-down page — Rejected: existing dialog already has all required functionality; avoid component duplication
2. Full-page account detail — Rejected: dialog pattern is established UX; keep consistent

---

R4: Plaid SDK Integration — Technology Choice

Decision: Use plaid npm package (v41+) with @plaid/link-initialize for Angular client

Rationale

• Server: plaid npm package (v41.4.0) — official Node.js SDK
  • PlaidApi class with linkTokenCreate(), itemPublicTokenExchange(), investmentsHoldingsGet(), investmentsTransactionsGet()
  • Targets API version 2020-09-14
  • Environments: PlaidEnvironments.sandbox (dev) and .production
• Client: @plaid/link-initialize — official framework-agnostic Plaid Link initializer
  • Works in Angular without wrappers
  • create({ token, onSuccess, onExit, onEvent }) → { open, exit }
  • Returns public_token on success for server exchange
• Products: Products.Investments provides holdings and transactions
• Webhook support: HOLDINGS: DEFAULT_UPDATE and INVESTMENTS_TRANSACTIONS: DEFAULT_UPDATE

Security

• Access tokens encrypted at rest using AES-256-GCM with PLAID_ENCRYPTION_KEY env var
• itemId stored as public reference; accessToken only used server-side
• Never log access tokens

Plaid → Ghostfolio Type Mapping

Plaid type	AssetClass	Plaid subtype	AssetSubClass
equity	EQUITY	common stock, preferred equity	STOCK
etf	EQUITY	etf	ETF
mutual fund	EQUITY	mutual fund	MUTUALFUND
fixed income	FIXED_INCOME	bond, municipal bond	BOND
cash	LIQUIDITY	cash	CASH
cryptocurrency	LIQUIDITY	cryptocurrency	CRYPTOCURRENCY
derivative	EQUITY	option, warrant	STOCK
loan	FIXED_INCOME	—	BOND
other/null	ALTERNATIVE_INVESTMENT	private equity fund, LP unit	PRIVATE_EQUITY

Alternatives Considered

1. ngx-plaid-link community package — Rejected: community-maintained, may lag behind Plaid updates; @plaid/link-initialize is official
2. CDN script tag — Rejected: less type safety, harder to test; npm package preferred
3. Build custom API client — Rejected: official SDK is well-maintained and typed

---

R5: Plaid Sync Queue — Infrastructure Pattern

Decision: Follow existing BullMQ pattern with new PLAID_SYNC_QUEUE

Rationale

• Existing pattern uses @nestjs/bull (Bull 4.x):
  • Queue registered in module: BullModule.registerQueue({ name: QUEUE_NAME })
  • Processor class with @Processor(QUEUE_NAME) and @Process({ name: JOB_NAME }) methods
  • Service with @InjectQueue() exposing addJobToQueue()
  • Rate limiting via limiter: { duration, max } option
• Two queues already exist:
  • DATA_GATHERING_QUEUE — rate limited 1 job/4sec, 12 attempts with exponential backoff
  • PORTFOLIO_SNAPSHOT_COMPUTATION_QUEUE — custom lock duration
• Cron scheduling via @nestjs/schedule @Cron() decorator in CronService
• Feature flag pattern: ENABLE_FEATURE_PLAID: bool({ default: false })

Implementation Approach

• New queue constant: PLAID_SYNC_QUEUE = 'PLAID_SYNC_QUEUE' in libs/common/src/lib/config.ts
• New module: PlaidSyncModule registering queue, processor, service
• Processor handles: SYNC_INVESTMENTS job (fetch holdings + transactions from Plaid, create/update Orders + SymbolProfiles)
• Cron: Daily sync at configurable time, guarded by ENABLE_FEATURE_PLAID flag
• On-demand: User-triggered refresh via API endpoint → enqueue job
• Rate limit: respect Plaid's rate limits (100 req/min production)

Alternatives Considered

1. Direct API calls without queue — Rejected: queue provides retry logic, rate limiting, and non-blocking execution
2. Separate microservice — Rejected: massive overkill; Simplicity First; existing monorepo queue pattern works

---

R6: Environment Variables — Plaid Configuration

Decision: Add 5 new env vars following existing pattern

Variables

Variable	Type	Default	Purpose
PLAID_CLIENT_ID	string	''	Plaid API client ID
PLAID_SECRET	string	''	Plaid API secret
PLAID_ENV	string	'sandbox'	Plaid environment (sandbox/production)
PLAID_ENCRYPTION_KEY	string	''	32-byte hex key for AES-256-GCM encryption of access tokens
ENABLE_FEATURE_PLAID	boolean	false	Feature flag to enable/disable Plaid integration

Implementation

1. Add to Environment interface in apps/api/src/services/interfaces/environment.interface.ts
2. Add to cleanEnv() validation in apps/api/src/services/configuration/configuration.service.ts
3. Access via this.configurationService.get('PLAID_CLIENT_ID')

---

R7: Markets Page Permission — USER Role Access

Decision: Markets basic view works for USER; premium Markets remains subscription-gated

Rationale

• Two Markets views exist:
  • Basic GfHomeMarketComponent at /home/markets — does NOT call readMarketDataOfMarkets-gated endpoint
  • Premium GfHomeMarketsPremiumComponent at /home/markets-premium — calls GET /market-data/markets requiring readMarketDataOfMarkets
• readMarketDataOfMarkets is dynamically granted to Premium subscribers of ANY role (USER or ADMIN)
• The home page component (home-page.component.ts L80–87) already auto-switches between basic and premium based on permission
• No permission change needed — the routing already handles the correct view per subscription level

Alternatives Considered

1. Grant readMarketData to USER — Rejected: readMarketData is admin-level (edit asset profiles); would be over-permissioning
2. Remove Markets entirely for USER — Rejected: basic view works and provides value

---

R8: Account Type Storage

Decision: Add optional accountType string field to Account model

Rationale

• Plaid returns account.type (e.g., 'investment', 'depository', 'credit', 'loan') and account.subtype (e.g., '401k', 'brokerage', 'ira', 'checking')
• Currently, Account model has no accountType field
• Storing as a simple string field (not an enum) avoids frequent enum migrations as Plaid adds new account types
• Field is optional — manually-created accounts don't need it

Alternatives Considered

1. Prisma enum — Rejected: Plaid adds new types over time; enum requires migration for each; string is more flexible
2. Metadata JSON field — Rejected: harder to query and filter; dedicated field is clearer
3. Ignore account type — Rejected: useful for filtering and display in FMV dashboard