# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Overview

This is the **SMA Widgets Group** - a PHP/JavaScript-based widget framework that provides embeddable financial market sentiment analysis widgets powered by Social Market Analytics (Context Analytics). The widgets display real-time social sentiment data from Twitter about stocks, futures, cryptocurrencies, and other financial instruments.

## Architecture

### Entry Points and Widget Loading

The codebase uses an iframe-based widget system:

1. **short.php** - Minimal entry point that sets default configuration and delegates to `source/index.php`
2. **source/index.php** - Main widget template that renders the UI shell with buttons and containers
3. **source/bin/globals.php** - Extracts and processes URL parameters (apikey, ontology, filters, frequency, subject, loadOnly, config, serverDomain, customCSS)
4. **source/js/sma_widget.js** - Client-side JavaScript that creates iframes and loads widget content dynamically
5. **source/js/server.js** - The actual widget implementation loaded inside iframes (referenced but not in this codebase)

### Widget Types

The system supports multiple widget types, selectable via buttons:
- **Top Sentiment** - Shows stocks with highest positive social sentiment
- **Bottom Sentiment** - Shows stocks with lowest/most negative sentiment
- **Futures** - Social sentiment for futures contracts (ES_F, NQ_F, YM_F, etc.)
- **Short Squeeze** - Tracks stocks with high short squeeze keyword mentions
- **Classification** - Stock classification based on social data
- **Earnings Watcher** - Tracks earnings-related social sentiment
- **Security Lookup** - Detailed intraday charts for individual securities

### Data Flow

1. Widget initialization passes configuration to iframe via `window._smaWParamIntD`
2. PHP backend files make API calls to Social Market Analytics endpoints:
   - `factorsData.php` - Fetches aggregate sentiment data (sscore, svolume, svscore, sdispersion)
   - `heatmap_data.php` - Fetches time-series data for charting (hourly/daily sentiment scores)
3. API endpoints vary by ontology (ticker, future, crypto) and data source (finance/stocktwits)
4. Results are processed and displayed in tables with click-through to detailed charts

### API Integration

The system integrates with multiple Social Market Analytics API endpoints:
- **api.socialmarketanalytics.com** - Main Twitter sentiment data
- **api-cc.socialmarketanalytics.com** - Crypto-specific sentiment
- **api2.socialmarketanalytics.com** - StockTwits sentiment data
- **vfeed1.socialmarketanalytics.com** - High-frequency data feed

Authentication requires an API key passed as `apikey` parameter.

### Configuration System

Widgets are configured via the `config` object passed during initialization:
- `loadOnly` - Comma-separated list of widget types to enable (e.g., 'top_sentiment,futures')
- `config` - Object with per-widget settings:
  - `btn_label` - Custom button text
  - `filters` - API filter expressions (e.g., 'svolume+gt+13')
  - `sort` - Custom sorting (e.g., 'squeeze_count+desc')
- `serverDomain` - Selects API data source ('finance' or 'stocktwits')
- `customCSS` - Inject custom styles into widgets

### Time Handling

The `heatmap_data.php` file handles complex time period calculations:
- Converts frequencies (1D, 1W, 1M, 6M, 1Y) into appropriate date ranges and API frequency parameters
- Uses US/Eastern timezone for all data
- Applies special filtering for daily data (time+eq+0810)
- Returns time-series data as millisecond timestamps for Highcharts

## Common Development Tasks

### Testing Widgets Locally

Access the demo page:
```
/demo/index.php
```

This loads a pre-configured widget group with multiple widget types enabled.

### Adding Custom API Endpoints

The base URL selection logic is in `factorsData.php` and `heatmap_data.php`:
- Check `$api_source` and `$ontology` to route to correct endpoint
- Maintain timezone handling (US/Eastern)
- Follow existing curl wrapper pattern: `get_data_via_api($url, $api_key, $params)`

### Modifying Widget Buttons

Edit `source/index.php` to add/remove widget types:
- Add button with `onclick="loadWidget(this, 'widget_name')"`
- Add corresponding case in `loadWidget()` JavaScript function
- Follow naming convention: use descriptive IDs and CSS class `new-btn`

## Important Notes

- **API Keys**: Never commit hardcoded API keys. Keys in `short.php` and demo files appear to be examples/defaults
- **Domain Detection**: The widget automatically detects environment (production/staging/local) via `extractHostname()` in sma_widget.js
- **Responsive Design**: Widget includes mobile breakpoints at 768px - test both desktop and mobile views
- **Modal Popups**: The intraday detail charts use jqModal plugin - referenced in HTML structure as `#intraday-popup`
- **External Dependencies**: Widgets depend on externally hosted scripts from widget-deft.socialmarketanalytics.com for actual widget rendering