AI StockAlert

AI StockAlert: Stock price monitoring with multi-channel alerts for Windows.

Download for Windows | Learn More

Features

Core Functionality

• Multi-Stock Monitoring - Track up to 15 stocks (free tier) with individual high/low thresholds
• Multi-Channel Alerts - Windows notifications, WhatsApp, and email (coming soon)
• Background Service - Continues monitoring even after closing the GUI
• Bilingual Support - Full English and Spanish interface
• Professional GUI - Modern PyQt6 interface with dark/light themes

Background Service Architecture

• 24/7 Monitoring - Service runs independently of the GUI
• Auto-Reload Config - Changes are picked up without restart
• Graceful Shutdown - Clean stop via GUI or command line
• Market Hours Aware - Only alerts during trading hours

Alert Channels

• Windows Toast Notifications - Click to view stock chart
• WhatsApp Alerts - Via the hosted StockAlert backend (requires an API key)
• Email Alerts - Coming soon

Quick Start

Prerequisites

• OS: Windows 10 or later
• Python: 3.10 or higher
• API Key: Free Finnhub API key (Get one here)

Installation

1. Clone the repository:

   git clone https://github.com/RCushmaniii/stock-alert.git
   cd stock-alert

2. Create and activate virtual environment:

   python -m venv venv
   .\venv\Scripts\Activate.ps1

3. Install dependencies:

   pip install -e ".[dev]"

4. Configure API key:

   Copy-Item .env.example .env
   # Edit .env and add your FINNHUB_API_KEY

Usage

Run the GUI Application

cd src
python -m stockalert

Run the Background Service (Headless)

cd src
python -m stockalert.service

The GUI provides:

• Profile Tab - Set your name, email, and phone for alerts
• Settings Tab - Configure check intervals, cooldown, alert channels
• Tickers Tab - Add/edit/delete stocks with price thresholds
• Help Tab - Tips and documentation

Background Service

The background service allows monitoring to continue even when the GUI is closed:

1. Open the GUI and configure your tickers and settings
2. Go to Settings > Background Service
3. Select "Background Service" mode
4. Click Start Service
5. Close the GUI - monitoring continues!

Command Line Options:

# Run in foreground (for debugging)
python -m stockalert.service --debug

# Install as Windows Service (requires admin)
python -m stockalert.service --install

# Control Windows Service
python -m stockalert.service --start
python -m stockalert.service --stop
python -m stockalert.service --remove

Configuration

Environment Variables (.env)

WhatsApp needs no credentials here. The desktop app holds only a StockAlert API key, entered in Settings and stored in Windows Credential Manager; the sending credentials live on the backend, never in the app.

FINNHUB_API_KEY=your_api_key_here

Configuration File (config.json)

{
  "version": "3.0.0",
  "settings": {
    "check_interval": 60,
    "cooldown": 300,
    "language": "en",
    "service_mode": "background",
    "alerts": {
      "windows_enabled": true,
      "windows_audio": true,
      "whatsapp_enabled": false,
      "email_enabled": false
    }
  },
  "profile": {
    "name": "Your Name",
    "email": "your@email.com",
    "cell": "+15551234567"
  },
  "tickers": [
    {
      "symbol": "AAPL",
      "name": "Apple Inc.",
      "high_threshold": 200.0,
      "low_threshold": 180.0,
      "enabled": true
    }
  ]
}

Architecture

src/stockalert/
├── __main__.py           # GUI entry point
├── app.py                # Main application orchestrator
├── service.py            # Background service entry point
├── core/
│   ├── config.py         # Configuration management
│   ├── monitor.py        # Stock price monitoring
│   ├── alert_manager.py  # Multi-channel alert dispatch
│   ├── whatsapp_service.py # WhatsApp/SMS backend client
│   ├── service_controller.py  # Service control from GUI
│   └── windows_service.py     # Windows Service wrapper
├── api/
│   ├── finnhub.py        # Finnhub API client
│   └── rate_limiter.py   # API rate limiting
├── ui/
│   ├── main_window.py    # PyQt6 main window
│   ├── tray_icon.py      # System tray integration
│   └── dialogs/          # Settings, Profile, Ticker dialogs
├── i18n/
│   └── locales/          # en.json, es.json translations
└── utils/
    ├── market_hours.py   # NYSE trading hours
    └── logging_config.py # Structured logging

Key Design Decisions

• Background Service - Monitoring decoupled from GUI for 24/7 operation
• Config File Watching - Service auto-reloads when settings change
• Rate Limiting - Token bucket algorithm respects Finnhub's 60 calls/min
• Multi-Channel Alerts - Plugin architecture for alert channels
• Bilingual - All UI strings externalized in JSON locale files

Development

Running Tests

pytest tests/ -v

Code Quality

ruff check src/
mypy src/

Building MSI Installer

pip install -e ".[build]"
python setup.py bdist_msi

Troubleshooting

No alerts appearing?

1. Check Windows Settings > Notifications > StockAlert is enabled
2. Verify your Finnhub API key is set in .env
3. Confirm thresholds are set (price must cross threshold)
4. Check cooldown period hasn't blocked repeated alerts

WhatsApp not working?

1. Ensure your StockAlert API key is entered in Settings and saved
2. Check your phone number includes its country code (e.g., +52 for Mexico)
3. Confirm that number has WhatsApp installed and active

Service won't start?

1. Check if another instance is already running
2. View logs in stockalert_service.log
3. Try running with --debug flag

Documentation

Detailed documentation is available in the docs/ folder:

Folder	Contents
docs/guides/	Build guides, MSI creation, code signing
docs/developer/	Architecture, API setup, contributing
docs/user/	User guides (English & Spanish)
docs/legal/	EULA, privacy policy, licenses
docs/archive/	Legacy v2.x documentation

License

Proprietary - CushLabs.ai. All rights reserved.

Credits

• Finnhub - Stock market data API
• PyQt6 - Cross-platform GUI framework
• Meta WhatsApp Cloud API - WhatsApp messaging
• winotify - Windows toast notifications

---

Built by Robert Cushman | CushLabs.ai