# Watch Your Tone

> Watch Your Tone is a sophisticated AI-powered analytics platform that reveals sentiment and emotional trends across news headlines in real-time, enabling data-driven insights into how news outlets frame stories and emotional evolution over time.

A comprehensive sentiment analysis and emotional intelligence platform for understanding media narratives. Uses AI classification to quantify sentiment (-1 to +1 scale) and extract emotional profiles from thousands of news headlines across multiple outlets including CNN, Fox News, BBC, Reuters, and NPR.

## Getting Started

- [Getting Started Guide](https://watchyourtone.news/getting-started): Interactive tutorials and video guides
- [Technology Stack](https://watchyourtone.news/about): Next.js 16, PostgreSQL, AI-powered sentiment analysis
- [Documentation](https://watchyourtone.news/transparency): Real-time data structure and AI model information

## Core Features

- [Dashboard Analytics](https://watchyourtone.news/dashboard): Customizable sentiment timeline, emotion distribution, outlet comparison
- [Search & Explore](https://watchyourtone.news/search): Full-text search with advanced filtering by sentiment, emotion, outlet, and date
- [Outlet Comparison](https://watchyourtone.news/outlets): Compare emotional profiles across news sources with interactive radar charts
- [Emotion Trends](https://watchyourtone.news/emotions): Track emotional distribution (joy, fear, anger, sadness, etc.) over time
- [Topic Narratives](https://watchyourtone.news/narratives): AI-powered topic clustering and sentiment evolution analysis (Supporter tier)
- [Story Comparison](https://watchyourtone.news/compare): Multi-outlet analysis of how different sources report the same stories (Supporter tier)
- [Real-Time Feed](https://watchyourtone.news/feed): Live stream of headlines with sentiment classification

## AI & Analytics

- [AI Insights](https://watchyourtone.news/ai-insights): Model performance monitoring, anomaly detection, and quality metrics (Supporter tier)
- [AI Transparency](https://watchyourtone.news/transparency): Complete infrastructure transparency, model costs, and methodology
- [Multi-Outlet Summaries](https://watchyourtone.news/ai-insights/summarization): Transparent AI summarization across news sources (Partner tier)

## User Features

- [Pricing Plans](https://watchyourtone.news/pricing): Free, Supporter ($4.99/mo), and Partner ($9.99/mo) tiers
- [Data Export](https://watchyourtone.news/dashboard): JSON/CSV export with tier-based quota management
- [Privacy Policy](https://watchyourtone.news/privacy): GDPR-compliant data practices and user rights
- [Terms of Service](https://watchyourtone.news/terms): User agreements and terms

## Technical Details

### Architecture
- **Framework**: Next.js 16 with App Router, TypeScript 5.9 (strict mode)
- **Database**: PostgreSQL 13+ with direct pg client (no ORM)
- **Styling**: TailwindCSS 3.4+ with dark mode support
- **Data Viz**: Recharts 2.13+ for charts and visualizations
- **State**: TanStack Query (React Query) v5 for server state
- **Auth**: NextAuth.js 4 with Google, Discord, Twitter, GitHub, Apple OAuth

### Data Structure
Seven main database tables:
1. `news_headlines` - headline text, outlet, URL, timestamp
2. `headline_classifications` - sentiment scores (-1 to +1), emotions (JSONB), AI reasoning notes
3. `ai_interactions` - complete AI call tracking (prompts, responses, tokens, costs)
4. `user_profiles` - tier-based access control (free/supporter/partner)
5. `user_logins` - authentication and session tracking
6. `export_quota` - tier-based export rate limiting
7. `user_data_requests` - GDPR compliance (data export/deletion)

### AI Models
- Primary: OpenAI GPT-5-nano and GPT-5-mini
- Sentiment: -1 (very negative) to +1 (very positive)
- Emotions: Flexible JSONB structure supporting 11+ emotions (joy, fear, anger, sadness, disgust, surprise, neutral, trust, anticipation, relief, admiration, plus custom emotions)
- Classification includes: sentiment score, emotion intensities, confidence, subjectivity, bias indicators, topics, categories

### API Endpoints
All endpoints return JSON with appropriate cache headers:
- `GET /api/headlines` - Recent headlines with classifications
- `GET /api/sentiment/timeline` - Time-bucketed sentiment (hour/day/week)
- `GET /api/emotions/distribution` - Average emotion intensities
- `GET /api/outlets/stats` - Per-outlet sentiment profiles
- `GET /api/search` - Full-text search with filters
- `GET /api/export` - Data export (quota enforced)
- `GET /api/analytics/*` - Statistics, correlations, topic clusters
- `GET /api/ai/*` - Performance, costs, quality, anomalies, forecasts

### Tier-Based Access
- **Free**: 3 days history, 100 exports/month, basic features
- **Supporter**: 14 days history, unlimited exports, AI insights, narratives, story comparison
- **Partner**: 365 days history, all features, forecasting, multi-outlet summarization

## For Developers

### Key Implementation Patterns
- Database queries use parameterized statements ($1, $2) for SQL injection prevention
- Two-layer caching: React Query client-side (5min stale) + HTTP cache headers server-side
- Mobile-first responsive design with dark mode support
- Emotion colors: Joy (#FCD34D), Fear (#A78BFA), Anger (#F87171), Sadness (#60A5FA)
- Sentiment colors: Very Negative (#991B1B) → Neutral (#6B7280) → Very Positive (#166534)

### Development
```bash
npm run dev          # Start development server (localhost:3000)
npm run build        # Build production bundle (standalone output)
npm run type-check   # TypeScript compiler check
npm run lint         # ESLint
```

### Docker Deployment
```bash
docker compose up -d  # Build and run (exposes on port 3006)
docker compose logs -f
docker compose down
```

## Resources

- [About Page](https://watchyourtone.news/about): Project background and mission
- [GitHub Repository](https://github.com/lgarceau768/news-mood): Source code and documentation
- [Issue Tracker](https://github.com/lgarceau768/news-mood/issues): Report bugs and request features

## Philosophy

Watch Your Tone analyzes **how news is framed**, not whether it's factually accurate. We focus on:
- Emotional tone and sentiment patterns
- Differences in framing across outlets
- Narrative evolution over time
- Transparency in AI methodology

We do NOT:
- Fact-check headlines
- Assign political bias scores
- Make judgments about journalistic quality
- Recommend "better" or "worse" news sources

The goal is media literacy through data: understand how outlets frame stories differently, track emotional trends, and make informed decisions about news consumption.