SFTi Stock Scanner

A professional, real-time penny stock scanner with Interactive Brokers (IBKR) integration, featuring AI-powered analysis, pattern recognition, and comprehensive market insights. Now available as a Progressive Web App (PWA) for mobile deployment!

🌟 Features

• Real-time Market Data: Live IBKR integration for accurate penny stock scanning
• AI-Powered Analysis: Smart stock recommendations and pattern recognition
• Progressive Web App: Install on iPhone/Android for native app experience
• Browser-Only IBKR: Direct connection to IBKR Client Portal - no backend required
• Offline Capability: Works without internet for cached data and core features
• Advanced Filtering: Price, volume, market cap, and float-based filtering
• Interactive Charts: Professional candlestick charts with technical indicators
• Price Alerts: Real-time notifications for breakout patterns
• Market Hours Detection: Dynamic themes based on trading sessions
• Multi-Tab Interface: Analyze multiple stocks simultaneously
• Dark Professional Theme: Bloomberg Terminal-inspired interface

📱 NEW: Mobile PWA Deployment

The SFTi Stock Scanner now runs entirely on your phone without needing your computer!

Quick Mobile Setup:

1. Deploy to HTTPS hosting (Vercel/Netlify/GitHub Pages)
2. Open in Safari on iPhone (or Chrome on Android)
3. Add to Home Screen via Share button
4. Login to IBKR in app settings
5. Trade at 3am without turning on your computer! 🌙📱

See PWA-DEPLOYMENT.md for complete mobile setup guide.

🏗️ Architecture

The SFTi Stock Scanner uses a hybrid architecture with multiple integration modes for maximum flexibility:

Mode 1: Browser-Direct (Primary)

Important

This graph below is being Updated
We are No longer using tradition architecure and JTS/IB-Gateway API
The Web-Implementaion latest 09-15-25

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│  React Frontend │    │  Express Server │    │  IBKR Client    │
│  (Port 4174)    │◄──►│  (Port 3000)    │    │  Portal Gateway │
│  • UI/UX        │    │  • WebSocket    │    │  (Port 5000)    │
│  • AI Patterns  │    │  • API Proxy    │◄──►│  • Auth         │
│  • Direct IBKR  │    │  • Demo Mode    │    │  • Market Data  │
└─────────────────┘    └─────────────────┘    └─────────────────┘
        │                                              ▲
        └──────────────────────────────────────────────┘
                    Direct Browser Connection

Mode 2: PWA/Mobile (Mobile-First)

┌─────────────────┐    ┌─────────────────┐
│  PWA Frontend   │    │  IBKR Client    │
│  (Mobile)       │◄──►│  Portal Web API │
│  • Service Wrkr │    │  (HTTPS Remote) │
│  • Offline      │    │  • Mobile Auth  │
│  • Push Notifs  │    │  • REST APIs    │
└─────────────────┘    └─────────────────┘

Components

Primary Architecture:

1. React Frontend: Modern TypeScript React app with tabbed interface, AI pattern recognition
2. Express Server: HTTP/WebSocket server providing API proxy, rate limiting, demo mode
3. IBKR Client Portal Gateway: Interactive Brokers' official web gateway (localhost:5000)
4. AI Pattern Service: Built-in pattern recognition and intelligent stock analysis

Key Features:

• Direct IBKR Integration: Browser connects directly to Client Portal Gateway
• Fallback Server Mode: Express server proxies IBKR APIs when needed
• Demo Mode: Works without IBKR connection for development/testing
• Real-time Updates: WebSocket streaming for live market data
• AI-Powered Analysis: Pattern recognition and intelligent recommendations

🚀 Quick Start

Prerequisites

• Node.js 20.19.4+ and npm 10.8.2+
• Interactive Brokers Account (paper or live trading)
• IBKR Client Portal Gateway (download from IBKR)
• Modern web browser (Chrome, Firefox, Safari, Edge)

Installation

1. Clone the repository

   git clone https://github.com/statikfintechllc/IB-G.Scanner.git
   cd IB-G.Scanner

2. Install dependencies

   npm install

3. Start development mode

   npm run dev

4. Open browser Navigate to http://localhost:4174

IBKR Setup

1. Download IBKR Client Portal Gateway

   • Official Download
   • Extract to a folder (e.g., ~/ibkr-gateway)

2. Start the Gateway

   cd ~/ibkr-gateway
   bash bin/run.sh root/conf.yaml

   • Gateway runs on https://localhost:5000
   • Login with your IBKR credentials in the browser

3. Connect the App

   • Start the app with npm run dev
   • Click the IBKR Settings button
   • App will connect automatically to the authenticated gateway

Production Deployment

1. Build the application

   npm run build

2. Start production services

   npm run start:prod

3. Access the application

   • Web App: http://localhost:4174
   • API Server: http://localhost:3000

🔧 Service Management

Available Scripts

# Development
npm run dev          # Start React frontend (port 4174)
npm run server       # Start Express server (port 3000)
npm run start:full   # Start both frontend and server

# Production
npm run build        # Build optimized frontend
npm run preview      # Preview production build (port 4174)
npm run start:prod   # Start server + preview

# Utilities
npm run lint         # Run ESLint
npm run kill         # Kill process on port 4174

Service Ports

• Frontend: http://localhost:4174 (development/production)
• API Server: http://localhost:3000 (HTTP + WebSocket on 3001)
• IBKR Gateway: https://localhost:5000 (manual start required)

Service Dependencies

Required:

1. React Frontend - User interface and AI pattern analysis
2. Express Server - API proxy, WebSocket, rate limiting

Optional:

1. IBKR Client Portal Gateway - Real-time market data (runs in demo mode without)
2. Service Worker - PWA offline functionality

🔧 IBKR Setup

Client Portal Gateway Setup

The application uses IBKR's Client Portal Gateway for web-based authentication and market data.

1. Download Client Portal Gateway

   • Official Download Link
   • Requires Java 8+ installed on your system

2. Extract and Configure

   # Extract the gateway
   unzip clientportal.gw.zip -d ~/ibkr-gateway
   cd ~/ibkr-gateway

3. Start the Gateway

   # Start the gateway (will open browser for login)
   bash bin/run.sh root/conf.yaml

4. Authenticate

   • Gateway opens browser to https://localhost:5000
   • Login with your IBKR username and password
   • Accept the security certificate warning
   • Keep the gateway running while using the app

5. Connect the App

   • Start the scanner: npm run dev
   • Click the IBKR Settings button in the app
   • App automatically detects and connects to authenticated gateway

Account Requirements

• IBKR Pro Account (API access required - not available on IBKR Lite)
• Market Data Subscription for real-time quotes
• Paper Trading or funded account for live trading

Troubleshooting

Gateway Won't Start:

• Ensure Java 8+ is installed: java -version
• Check if port 5000 is available
• Disable firewall/antivirus temporarily

Authentication Failed:

• Only one session allowed - logout from TWS/Mobile if connected
• Clear browser cookies and try again
• Restart gateway: Ctrl+C then bash bin/run.sh root/conf.yaml

No Market Data:

• Verify market data subscriptions in IBKR account
• Check that paper trading mode has data access
• Ensure gateway session is still authenticated
  • Add 127.0.0.1 to trusted IPs
  • Enable "Download open orders on connection"

3. Paper Trading Setup (Recommended for testing)
   • Use paper trading account for safe testing
   • Login to TWS with paper trading credentials
   • Verify connection in the app's IBKR Settings

📱 Cross-Platform Deployment

Desktop Application (PWA)

The scanner can be installed as a Progressive Web App:

1. Chrome/Edge: Click install icon in address bar
2. Firefox: Use "Install this site as an app" from menu
3. Safari: Add to Dock from Share menu

Mobile Installation

1. iOS:

   • Open in Safari
   • Tap Share → Add to Home Screen

2. Android:

   • Open in Chrome
   • Tap menu → Add to Home Screen

🛠️ Development

Project Structure

src/
├── components/          # React components
│   ├── ui/             # Shadcn UI components
│   ├── AISearch.tsx    # AI-powered search
│   ├── AlertsManager.tsx # Alert system
│   ├── IBKRSettings.tsx # IBKR configuration
│   └── ...
├── lib/                # Core logic
│   ├── ibkr.ts        # IBKR API integration
│   ├── alerts.ts      # Alert system
│   └── market.ts      # Market hours detection
├── types/              # TypeScript definitions
└── assets/            # Static assets

Available Scripts

# Development server
npm run dev

# Build for production
npm run build

# Preview production build
npm run preview

# Lint code
npm run lint

# Type checking
npm run build

Environment Configuration

Create .env.local for custom configuration:

# IBKR Configuration
VITE_IBKR_HOST=127.0.0.1
VITE_IBKR_PORT=7497
VITE_IBKR_CLIENT_ID=1

# API Keys (optional)
VITE_ALPHA_VANTAGE_KEY=your_key_here
VITE_POLYGON_API_KEY=your_key_here

🔧 Configuration

Scanner Filters

Default filter settings can be modified in src/App.tsx:

const DEFAULT_FILTERS: ScannerFilters = {
  priceMin: 0.01,      // Minimum price
  priceMax: 5.00,      // Maximum price (penny stock definition)
  marketCapMin: 1_000_000,     // $1M minimum
  marketCapMax: 2_000_000_000, // $2B maximum
  floatMin: 1_000_000,         // 1M shares minimum
  floatMax: 1_000_000_000,     // 1B shares maximum
  volumeMin: 100_000,          // Minimum daily volume
  changeMin: -100,             // Minimum % change
  changeMax: 100,              // Maximum % change
  newsOnly: false              // Filter by news availability
};

Market Hours

The app automatically detects market sessions and applies appropriate themes:

• Pre-market (4:00-9:30 AM EST): Dark red theme
• Regular (9:30 AM-4:00 PM EST): Bright red theme
• After-hours (4:00-8:00 PM EST): Deep gold theme
• Closed: Neutral gray theme

🚨 Troubleshooting

Common Issues

IBKR Connection Failed

• Verify TWS/Gateway is running
• Check API settings are enabled
• Confirm port configuration (7497 for TWS, 4001 for Gateway)
• Add 127.0.0.1 to trusted IPs

No Market Data

• Ensure market data subscriptions are active in IBKR account
• Verify account permissions for penny stocks
• Check if market is open (data may be delayed when closed)

Performance Issues

• Limit number of open chart tabs (max 6)
• Clear browser cache
• Close unused tabs to free memory
• Check internet connection stability

Error Messages

• "IBKR connection failed - running in demo mode": Normal when TWS isn't running
• "Maximum 6 tabs allowed": Close existing tabs before opening new ones
• "No stocks match criteria": Adjust filter settings to broaden search

📊 Data Sources

• Primary: Interactive Brokers TWS API
• Charts: IBKR real-time data with TradingView-style rendering
• News: Integrated IBKR news feed
• Float Data: IBKR fundamental data when available

🔐 Security

• All API keys stored locally (never transmitted)
• IBKR connections use local socket connections
• No sensitive data stored on external servers
• User preferences encrypted in local storage

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

For issues and questions:

1. Check troubleshooting section above
2. Verify IBKR setup is correct
3. Review browser console for errors
4. Ensure all prerequisites are installed

🔄 Updates

The app includes an automatic update system:

• Beta toggle in settings for daily updates
• Production updates via standard deployment
• No manual intervention required

---

⚠️ Disclaimer: This software is for educational and analysis purposes. Always verify data independently before making trading decisions. Past performance does not guarantee future results.

---

© 2025 StatikFinTech, LLC