StockAlert Pro - Complete Implementation Guide

📋 Executive Summary

StockAlert Pro is a production-ready stock market scanning platform built with:

Backend: Node.js + Express + PostgreSQL + Redis
Frontend: React 18 + TailwindCSS + Recharts
Infrastructure: Docker, GitHub Actions, Railway/AWS
Features: SMS alerts, derivatives tracking, insider trading, order book analysis

🗂️ Complete Project Structure

stock-alert-pro/
├── backend/
│   ├── src/
│   │   ├── config/
│   │   │   ├── database.js          # Sequelize config
│   │   │   ├── redis.js             # Redis client
│   │   │   └── environment.js       # Environment validation
│   │   ├── models/
│   │   │   ├── User.js              # User authentication
│   │   │   ├── Strategy.js          # Trading strategies
│   │   │   ├── AlertLog.js          # Alert history
│   │   │   ├── Derivative.js        # Futures/Options data
│   │   │   ├── OptionsBuyer.js      # Options tracking
│   │   │   ├── OrderBook.js         # Order book data
│   │   │   ├── InsiderTransaction.js # Director trades
│   │   │   └── GeopoliticalEvent.js # News events
│   │   ├── controllers/
│   │   │   ├── authController.js    # Auth logic
│   │   │   ├── strategyController.js# Strategy CRUD
│   │   │   ├── alertController.js   # Alert management
│   │   │   ├── derivativesController.js
│   │   │   ├── insiderController.js
│   │   │   └── newsController.js
│   │   ├── routes/
│   │   │   ├── auth.js
│   │   │   ├── strategies.js
│   │   │   ├── alerts.js
│   │   │   ├── derivatives.js
│   │   │   ├── insider.js
│   │   │   ├── orderbook.js
│   │   │   └── news.js
│   │   ├── services/
│   │   │   ├── alertService.js      # SMS/Email sending
│   │   │   ├── derivativesService.js# Data fetching
│   │   │   ├── insiderService.js    # Scraping
│   │   │   ├── newsService.js       # News aggregation
│   │   │   └── scanService.js       # Strategy execution
│   │   ├── middleware/
│   │   │   ├── auth.js              # JWT verification
│   │   │   ├── errorHandler.js      # Error handling
│   │   │   └── rateLimit.js         # Rate limiting
│   │   ├── websocket/
│   │   │   └── wsManager.js         # Real-time updates
│   │   ├── utils/
│   │   │   ├── logger.js            # Winston logging
│   │   │   ├── validators.js        # Input validation
│   │   │   └── helpers.js           # Utility functions
│   │   └── app.js                   # Express app setup
│   ├── migrations/
│   │   ├── 001_create_users_table.sql
│   │   ├── 002_create_strategies_table.sql
│   │   └── ... (up to 009)
│   ├── seeds/
│   │   └── seed.js                  # Initial data
│   ├── __tests__/
│   │   ├── auth.test.js
│   │   ├── strategies.test.js
│   │   └── integration.test.js
│   ├── package.json
│   ├── server.js                    # Entry point
│   └── .env.example                 # Environment template
├── frontend/
│   ├── src/
│   │   ├── components/
│   │   │   ├── AlertCenter.jsx
│   │   │   ├── StrategyStats.jsx
│   │   │   ├── Navbar.jsx
│   │   │   ├── Sidebar.jsx
│   │   │   └── WebSocketProvider.jsx
│   │   ├── pages/
│   │   │   ├── Dashboard.jsx
│   │   │   ├── StrategyScanBuilder.jsx
│   │   │   ├── DerivativesTracker.jsx
│   │   │   ├── InsiderTracker.jsx
│   │   │   ├── OrderBookMonitor.jsx
│   │   │   └── NewsAndGeopolitical.jsx
│   │   ├── services/
│   │   │   ├── api.js               # Axios instance
│   │   │   ├── auth.js              # Auth service
│   │   │   └── websocket.js         # WebSocket client
│   │   ├── store/
│   │   │   └── useStore.js          # Zustand store
│   │   ├── App.jsx                  # Main component
│   │   ├── index.css                # Global styles
│   │   └── main.jsx                 # Entry point
│   ├── public/
│   │   └── index.html
│   ├── package.json
│   └── vite.config.js
├── docker-compose.yml               # Multi-container setup
├── .github/
│   └── workflows/
│       └── ci-cd.yml                # GitHub Actions
├── README.md
└── DEPLOYMENT.md                    # Deployment guide

🚀 Installation & Setup

Prerequisites

Docker & Docker Compose (or Node.js 18+ + PostgreSQL 15+ + Redis 7+)
Git
GitHub account (for CI/CD)
API Keys: Twilio, NSE, Finnhub, NewsAPI

Step 1: Clone Repository

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

Step 2: Configure Environment Variables

Backend (backend/.env):

# Server
PORT=5000
NODE_ENV=development

# Database
DB_HOST=postgres
DB_PORT=5432
DB_NAME=stockalert_db
DB_USER=postgres
DB_PASSWORD=postgres_password_123

# Redis
REDIS_HOST=redis
REDIS_PORT=6379
REDIS_PASSWORD=redis_password_123

# JWT
JWT_SECRET=your_super_secret_jwt_key_change_in_production
JWT_EXPIRE=7d

# Twilio SMS
TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TWILIO_AUTH_TOKEN=your_twilio_auth_token
TWILIO_PHONE_NUMBER=+1234567890

# NSE API
NSE_API_KEY=your_nse_api_key
NSE_API_BASE_URL=https://www.nseindia.com/api

# News APIs
FINNHUB_API_KEY=your_finnhub_api_key
NEWSAPI_KEY=your_newsapi_key

# Email (SMTP)
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your_email@gmail.com
SMTP_PASSWORD=your_app_password

# Logging
LOG_LEVEL=debug

Frontend (frontend/.env):

VITE_API_URL=http://localhost:5000/api
VITE_WS_URL=ws://localhost:5000
VITE_APP_NAME=StockAlert Pro

Step 3: Start with Docker Compose

# Build and start all services
docker-compose up -d

# Check status
docker-compose ps

# View logs
docker-compose logs -f backend
docker-compose logs -f frontend

Step 4: Database Setup

# Run migrations
docker exec stockalert_backend npm run migrate

# Seed initial data
docker exec stockalert_backend npm run seed

# Verify database
docker exec -it stockalert_postgres psql -U postgres -d stockalert_db -c "\dt"

Step 5: Access Application

Frontend: http://localhost:3000
Backend API: http://localhost:5000
API Docs: http://localhost:5000/api/docs
Database: localhost:5432 (pgAdmin: http://localhost:5050)
Redis: localhost:6379

📊 API Documentation

Authentication Endpoints

Register User

POST /api/auth/register
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "SecurePassword123!",
  "firstName": "John",
  "lastName": "Doe",
  "phoneNumber": "+919876543210"
}

Response (201):
{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "user@example.com",
    "subscriptionTier": "free",
    "createdAt": "2026-01-06T17:30:00Z"
  }
}

Login

POST /api/auth/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "SecurePassword123!"
}

Response (200):
{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": { ... }
}

Strategy Endpoints

Create Strategy

POST /api/strategies
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "EMA 20/50 Crossover",
  "description": "Buy when EMA 20 crosses above EMA 50",
  "clause": "close > ema(20) and ema(20) > ema(50)",
  "timeframe": "daily",
  "alertSettings": {
    "sms": true,
    "email": true,
    "webhook": null
  }
}

Response (201):
{
  "id": "550e8400-e29b-41d4-a716-446655440001",
  "name": "EMA 20/50 Crossover",
  "isActive": true,
  "createdAt": "2026-01-06T17:30:00Z"
}

List Strategies

GET /api/strategies
Authorization: Bearer <token>

Response (200):
[
  { id: "...", name: "EMA 20/50 Crossover", isActive: true, executionCount: 5 },
  { id: "...", name: "RSI Oversold", isActive: true, executionCount: 12 },
  ...
]

Execute Strategy

POST /api/strategies/:id/execute
Authorization: Bearer <token>

Response (200):
{
  "success": true,
  "matchedStocks": ["INFY", "TCS", "WIPRO"],
  "alertsSent": 3,
  "executedAt": "2026-01-06T17:30:00Z"
}

Alert Endpoints

Get Alert Logs

GET /api/alerts/logs?limit=20&status=sent
Authorization: Bearer <token>

Response (200):
[
  {
    "id": "...",
    "message": "INFY crossed EMA 20/50",
    "status": "sent",
    "alertType": "sms",
    "recipient": "+919876543210",
    "sentAt": "2026-01-06T17:30:00Z"
  },
  ...
]

Send Test SMS

POST /api/alerts/test-sms
Authorization: Bearer <token>
Content-Type: application/json

{
  "phoneNumber": "+919876543210",
  "message": "Test SMS from StockAlert Pro"
}

Response (200):
{
  "success": true,
  "messageId": "SM1234567890abcdef",
  "sentAt": "2026-01-06T17:30:00Z"
}

Derivatives Endpoints

Get Top 20 Contracts

GET /api/derivatives/top-20-contracts

Response (200):
[
  {
    "symbol": "NIFTY50",
    "contractType": "future",
    "volume": 2500000000,
    "openInterest": 1850000000,
    "lastPrice": 25180.50,
    "changePercent": 1.25
  },
  ...
]

Get Options Chain

GET /api/derivatives/NIFTY50/chain?expiryDate=2026-01-16

Response (200):
{
  "symbol": "NIFTY50",
  "expiryDate": "2026-01-16",
  "callBuyers": [
    { strike: 25000, volume: 450000, oi: 380000, lastPrice: 250.50 },
    ...
  ],
  "putBuyers": [
    { strike: 25000, volume: 320000, oi: 290000, lastPrice: 45.25 },
    ...
  ]
}

Get Put-Call Ratio

GET /api/derivatives/NIFTY50/put-call-ratio

Response (200):
{
  "symbol": "NIFTY50",
  "putCallRatio": 0.78,
  "sentiment": "bullish",
  "callVolume": 2500000000,
  "putVolume": 1950000000,
  "timestamp": "2026-01-06T17:30:00Z"
}

Insider Trading Endpoints

Get Director Holdings

GET /api/insider/directors/TCS?limit=10

Response (200):
[
  {
    "directorName": "Ajay Singh",
    "companyName": "TCS",
    "transactionType": "buy",
    "quantity": 10000,
    "price": 3500,
    "transactionDate": "2026-01-05",
    "shareholdingPercent": 0.05
  },
  ...
]

Order Book Endpoints

Get Large Orders

GET /api/orderbook/large-orders?minQuantity=1000000

Response (200):
[
  {
    "companyName": "Reliance Industries",
    "symbol": "RELIANCE",
    "buyQuantity": 5000000,
    "buyPrice": 2850.00,
    "sellQuantity": 3500000,
    "sellPrice": 2851.50,
    "timestamp": "2026-01-06T17:30:00Z"
  },
  ...
]

News Endpoints

Get News Feed

GET /api/news/feed?symbol=INFY&limit=10

Response (200):
[
  {
    "title": "Infosys Q3 Results Beat Expectations",
    "description": "IT major reports strong quarterly earnings...",
    "source": "Reuters",
    "publishedAt": "2026-01-06T10:00:00Z",
    "url": "https://reuters.com/...",
    "sentiment": "positive"
  },
  ...
]

🧪 Testing

Run All Tests

cd backend
npm install
npm test

With Coverage Report

npm test -- --coverage

Watch Mode (Development)

npm test -- --watch

Specific Test File

npm test -- __tests__/auth.test.js

Expected Output

 PASS  __tests__/auth.test.js
  Authentication Tests
    ✓ should register new user (234ms)
    ✓ should login user (145ms)
    ✓ should fail with invalid password (98ms)

 PASS  __tests__/strategies.test.js
  Strategies API Tests
    ✓ should return user strategies (167ms)
    ✓ should create new strategy (156ms)
    ✓ should delete strategy (123ms)

Test Suites: 2 passed, 2 total
Tests:       6 passed, 6 total
Coverage: 82%

🔄 CI/CD Pipeline

GitHub Actions Workflow

The .github/workflows/ci-cd.yml file automatically:

Runs on Push/PR to main/develop branches
Tests: Jest with coverage
Lint: Code quality checks
Build: Docker images
Deploy: To Railway on main branch

Required GitHub Secrets

DOCKER_USERNAME = your_docker_hub_username
DOCKER_PASSWORD = your_docker_hub_password
RAILWAY_TOKEN = your_railway_api_token

Add Secrets to GitHub

# Via GitHub CLI
gh secret set DOCKER_USERNAME --body "your_username"
gh secret set DOCKER_PASSWORD --body "your_password"
gh secret set RAILWAY_TOKEN --body "your_token"

# Or via GitHub Web UI:
# Settings → Secrets and variables → Actions → New repository secret

📈 Deployment Options

Option 1: Railway (Recommended for Beginners)

Create Railway Account: https://railway.app
Connect GitHub: Link your repository
Create Services:
- Backend (Node.js)
- Frontend (Static)
- PostgreSQL
- Redis
Set Environment Variables in Railway dashboard
Deploy: Automatic on git push

Railway Pricing: Free tier available, pay-as-you-go

Option 2: AWS Deployment

Infrastructure Setup:

# 1. RDS PostgreSQL
aws rds create-db-instance \
  --db-instance-identifier stockalert-db \
  --db-instance-class db.t3.micro \
  --engine postgres \
  --master-username postgres \
  --master-user-password YourPassword123

# 2. ElastiCache Redis
aws elasticache create-cache-cluster \
  --cache-cluster-id stockalert-redis \
  --cache-node-type cache.t3.micro \
  --engine redis

# 3. ECS Fargate
aws ecs create-cluster --cluster-name stockalert

# 4. Load Balancer
aws elbv2 create-load-balancer \
  --name stockalert-lb \
  --subnets subnet-xxx subnet-yyy

Option 3: DigitalOcean

Create Droplet (2GB RAM, $12/month)

Install Docker:

curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

Upload docker-compose.yml
Deploy:
```
docker-compose up -d
```
Setup Nginx as reverse proxy
SSL Certificate: Let's Encrypt

🔐 Security Best Practices

Environment Variables

Never commit .env to Git
Use .env.example for templates
Rotate secrets regularly

Database Security

-- Create dedicated user
CREATE USER stockalert_user WITH PASSWORD 'strong_password_123';
GRANT CONNECT ON DATABASE stockalert_db TO stockalert_user;
GRANT USAGE ON SCHEMA public TO stockalert_user;
GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA public TO stockalert_user;

-- Enable SSL
ALTER SYSTEM SET ssl = on;

API Security

JWT tokens expire in 15 minutes
Refresh token rotation
Rate limiting (100 req/min)
CORS whitelist only trusted domains
Helmet security headers
Request validation with Joi

SMS Security

Hash phone numbers
Encrypt sensitive data
Log all alerts
Monitor failed attempts

Code Security

Dependabot for dependency updates
SAST scanning (SonarQube)
Container scanning (Trivy)
Supply chain security (SBOM)

🚨 Troubleshooting

Docker Issues

Containers won't start:

# Check logs
docker-compose logs backend

# Rebuild images
docker-compose build --no-cache

# Full reset
docker-compose down -v
docker-compose up -d

Port already in use:

# Find process using port
sudo lsof -i :5000

# Kill process
sudo kill -9 <PID>

# Or use different port
PORT=5001 docker-compose up

Database Issues

Migration failed:

# Connect to database
docker exec -it stockalert_postgres psql -U postgres -d stockalert_db

# Check tables
\dt

# Reset database
docker exec stockalert_backend npm run migrate:reset

Connection refused:

# Check PostgreSQL is running
docker exec stockalert_postgres pg_isready

# Check Redis is running
docker exec stockalert_redis redis-cli ping

Backend Issues

Module not found:

docker exec stockalert_backend npm install
docker-compose restart backend

Memory leak:

# Check memory usage
docker stats stockalert_backend

# Increase memory limit in docker-compose.yml
# mem_limit: 2g

Frontend Issues

CORS errors:

# Check Backend URL in frontend .env
VITE_API_URL=http://localhost:5000/api

# Check CORS in backend
cors({ origin: ['http://localhost:3000'] })

WebSocket connection failed:

# Check WebSocket URL
VITE_WS_URL=ws://localhost:5000

# Verify backend serves WebSocket
netstat -an | grep 5000

📚 Additional Resources

Documentation: https://stockalert-pro.docs.com
API Postman Collection: https://www.postman.com/collections/stockalert-pro
GitHub Issues: https://github.com/yourusername/stock-alert-pro/issues
Community Forum: https://forum.stockalert-pro.com

📝 License

MIT License - See LICENSE file for details

Last Updated: January 6, 2026 Version: 1.0.0 Maintainer: Your Team

FilesExpand file tree

SETUP_GUIDE (1).md

Latest commit

History