# Project Overview

## MarketPulse Dashboard

MarketPulse is a browser-based stock monitoring dashboard built as a single-page application in `dash.html`. It integrates Finnhub market data with a responsive UI and persistent local preferences.

## Purpose

Provide a fast, lightweight dashboard for:

- U.S. market status visibility
- key index tracking (DJI, IXIC, SPX, VIX)
- gainers/losers scanning
- multi-watchlist monitoring
- rapid troubleshooting through built-in diagnostics

## Core Capabilities

- **Live Refresh Pipeline** with partial-success handling
- **3 Independent Watchlist Cards** with per-card selection and `None` option
- **Persistent Preferences** (theme, display toggles, watchlist selections, interval, debug)
- **API Test Panel** for key validation and symbol lookup
- **Debug Console** with timestamped operational logs and test helpers
- **Self-Test Utilities** for initialization and integrity checks

## Current Architecture

- **Frontend:** HTML + Bootstrap/Bootswatch + vanilla JavaScript
- **Data Source:** Finnhub REST API
- **Persistence:** Browser storage (`localStorage` / fallback wrappers)
- **Deployment Model:** Static file, client-side execution

## User Roles

### End Users

- Configure API key
- Select themes and visible panels
- Manage watchlists and ticker symbols
- Monitor market and watchlist movements

### Developers

- Extend fetch/render logic
- Improve diagnostics and reliability
- Evolve docs, tests, and architecture

## Reliability & Diagnostics

The project includes defensive coding and operational visibility:

- null-safe DOM updates
- explicit async error logging
- per-card watchlist fetch diagnostics
- built-in self-tests (`runSelfTests`, `testApiCalls`, `testWatchlistIntegrity`)

## Known Constraints

- Client-side API key storage (acceptable for local/private use, not hardened)
- API rate limits can cause partial watchlist/market fetch failures
- Single-file script increases coupling and maintenance overhead

## Strategic Direction

1. Modularize script into focused files (`state`, `api`, `render`, `watchlists`, `diagnostics`)
2. Add lint/test automation for regressions
3. Introduce optional backend proxy for API-key protection
4. Move toward typed contracts and release versioning

## Documentation Map

See the docs folder for complete references:

- `REQUIREMENTS.md`
- `USER_GUIDE.md`
- `PROGRAMMER_GUIDE.md`
- `ARCHITECTURE.md`
- `TESTING_AND_OPERATIONS.md`
- `CHANGELOG.md`
- `ROADMAP.md`