StockScope - Stock Analytics Platform

A professional-grade stock analytics platform with real-time quotes, interactive charts, technical indicators, and watchlists. Features multi-source data integration with automatic failover for maximum reliability.

Features

Data & Analytics

• Multi-Source Data Integration - Combines Twelve Data, Finnhub, and Yahoo Finance with automatic failover
• Real-time Stock Quotes - Live prices with change, volume, and 52-week high/low
• Technical Indicators - RSI, MACD, SMA (20/50) from Twelve Data's pre-calculated endpoints
• Interactive Charts - Area charts with TradingView's lightweight-charts library
• Historical Data - Up to 1 year of daily OHLCV data with database caching

User Features

• Smart Search - Instant search with popular stock suggestions on focus
• Watchlists - Create and manage multiple watchlists stored in PostgreSQL
• Price Alerts - Set alerts for price thresholds (above/below)
• Real-time Updates - SSE streaming for live price updates

Reliability

• Automatic Failover - If one API is rate-limited, seamlessly falls back to alternatives
• Request Throttling - Built-in rate limit protection to avoid API bans
• Database Caching - Historical data cached in Supabase for faster loads
• In-Memory Cache - Quotes cached for 60s, history for 5-10 minutes

Tech Stack

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                    Frontend (Svelte + Vite)                      │
│  SearchBar │ StockView │ PriceChart │ Watchlist │ Indicators    │
└──────────────────────────┬──────────────────────────────────────┘
                           │ REST API + SSE
┌──────────────────────────▼──────────────────────────────────────┐
│                  Backend (Express + TypeScript)                  │
│  ┌────────────────────────────────────────────────────────────┐ │
│  │              Multi-Source Stock API Client                  │ │
│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌────────────┐  │ │
│  │  │  Twelve  │→ │ Finnhub  │→ │  Yahoo   │→ │   Cache    │  │ │
│  │  │   Data   │  │(fallback)│  │ Finance  │  │  (memory)  │  │ │
│  │  └──────────┘  └──────────┘  └──────────┘  └────────────┘  │ │
│  └────────────────────────────────────────────────────────────┘ │
│  Stock Routes │ Watchlist Routes │ Alert Routes │ SSE Stream    │
└──────────────────────────┬──────────────────────────────────────┘
                           │
┌──────────────────────────▼──────────────────────────────────────┐
│  Supabase (PostgreSQL)                                          │
│  - watchlists              - price_history (cache)              │
│  - watchlist_stocks        - price_alerts                       │
└─────────────────────────────────────────────────────────────────┘

Data Source Priority

Getting Started

Prerequisites

• Node.js 18+
• npm or yarn
• Supabase account (free tier)
• API Keys (all have free tiers):
  • Twelve Data (primary) - 800 calls/day
  • Finnhub (fallback) - 60 calls/min
  • Alpha Vantage (optional) - 25 calls/day

Installation

1. Clone the repository

   git clone https://github.com/yourusername/stock-analytics.git
   cd stock-analytics
   

2. Install dependencies

   npm install
   cd frontend && npm install && cd ..
   

3. Configure environment variables

   cp .env.example .env
   

   Edit .env:

   PORT=3000
   SUPABASE_URL=https://your-project.supabase.co
   SUPABASE_ANON_KEY=your-anon-key
   
   # Primary data source (get at https://twelvedata.com)
   TWELVE_DATA_API_KEY=your-key
   
   # Fallback sources (recommended for reliability)
   FINNHUB_API_KEY=your-key          # https://finnhub.io
   ALPHA_VANTAGE_API_KEY=your-key    # https://alphavantage.co
   

4. Set up the database

   Run in Supabase SQL Editor:

   -- Watchlists
   CREATE TABLE watchlists (
     id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
     name VARCHAR(100) NOT NULL,
     created_at TIMESTAMPTZ DEFAULT NOW(),
     updated_at TIMESTAMPTZ DEFAULT NOW()
   );
   
   -- Watchlist stocks
   CREATE TABLE watchlist_stocks (
     id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
     watchlist_id UUID REFERENCES watchlists(id) ON DELETE CASCADE,
     symbol VARCHAR(10) NOT NULL,
     added_at TIMESTAMPTZ DEFAULT NOW(),
     UNIQUE(watchlist_id, symbol)
   );
   
   -- Price alerts
   CREATE TABLE price_alerts (
     id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
     symbol VARCHAR(10) NOT NULL,
     target_price DECIMAL(12, 2) NOT NULL,
     condition VARCHAR(10) NOT NULL CHECK (condition IN ('above', 'below')),
     triggered BOOLEAN DEFAULT FALSE,
     triggered_at TIMESTAMPTZ,
     created_at TIMESTAMPTZ DEFAULT NOW()
   );
   
   -- Historical price cache
   CREATE TABLE price_history (
     id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
     symbol VARCHAR(10) NOT NULL,
     date DATE NOT NULL,
     open DECIMAL(12, 2),
     high DECIMAL(12, 2),
     low DECIMAL(12, 2),
     close DECIMAL(12, 2),
     volume BIGINT,
     UNIQUE(symbol, date)
   );
   
   -- Indexes
   CREATE INDEX idx_watchlist_stocks_symbol ON watchlist_stocks(symbol);
   CREATE INDEX idx_price_alerts_symbol ON price_alerts(symbol);
   CREATE INDEX idx_price_history_symbol_date ON price_history(symbol, date DESC);
   

5. Build and start

   cd frontend && npm run build && cd ..
   npm run dev
   

6. Open the app at http://localhost:3000

API Endpoints

Stock Data

Watchlists

Alerts & Streaming

Technical Indicators

Rate Limits & Caching

The app includes built-in request throttling to prevent hitting rate limits.

Development

# Start dev server (auto-kills existing process on port 3000)
npm run dev

# Build frontend only
cd frontend && npm run build

# Type checking
npm run lint

Deployment

Railway (Backend)

1. Push to GitHub
2. Connect repo in Railway
3. Add environment variables
4. Deploy

Vercel (Frontend)

The frontend builds to public/build/ and is served by Express. For separate deployment, use the frontend/dist folder.

Environment Variables

License

MIT License - see LICENSE for details.

Built with Claude Code