Enhancing Portfolio Transparency with the Price Health Card
Pocket Portfolio introduced the Price Pipeline Health Card to increase transparency regarding financial data freshness and source reliability. The core problem addressed was user uncertainty about whether displayed stock prices were live or fallback data, and which underlying data provider (like Yahoo, Chart API, Stooq) might be experiencing issues. The card provides a clear visual status: green for “Fresh” (data within 30 seconds), amber for “Fallback” (recent fallback or failure within 60 seconds), and red for “Unhealthy” (no successful data in 5 minutes).
Implementation involved three key steps: recording provider events (success/failure/fallback), exposing a typed `/api/health-price` endpoint aggregating provider health metrics (lastSuccess, lastFailure, failureCount, activeFallback), and rendering the Health Card via a polling React hook (`usePriceHealth`). Key design decisions prioritized bounded latency over completeness, ensuring the dashboard loads quickly even if health data is sparse. A minimal API contract of four fields per provider was chosen to avoid complexity and coupling, while UI rules are declarative for easy tuning of thresholds. A rate-limited Vercel Edge Function prevents self-DDoS from the 30-second polling cadence. Health metrics are ephemerally stored in Redis/Upstash or in-memory for development.
Benefits include enhanced user trust by explaining every number and never showing 0.00, proactive communication about data health, and clear identification of provider issues. The system gracefully handles network failures by displaying “Unknown” and a skeleton UI. The project emphasized small, testable slices and sharing types and status logic between the API and UI to ensure consistency and reduce bugs. This approach allowed for a measurable first release, deferring more complex features like symbol-level freshness for later stages.
