A professional-grade paper trading simulator for Indian stock markets (NSE), built with React + Vite frontend and Node.js + Express + MongoDB Atlas backend. Real stock prices fetched live from Yahoo Finance.

Switch between two modes anytime from the sidebar or Settings:

• 🎮 Simulation — Simulated prices that update every 3 seconds. Works 24/7, perfect for after-hours testing
• 🌐 Live — Real NSE prices from Yahoo Finance. Works during market hours (9:15 AM – 3:30 PM IST, weekdays)

alphametrics/
├── package.json                ← root — runs both frontend + backend together
├── vercel.json                 ← Vercel deploy config (auto SPA rewrite)
├── backend/
│   ├── package.json
│   ├── .env                    ← MongoDB Atlas URI + JWT secret (edit this)
│   └── src/
│       ├── index.js            ← Express server + price alert cron job
│       ├── seed.js             ← Creates demo users in MongoDB
│       ├── models/             ← User, Trade, Position, Alert, PnlSnapshot
│       ├── routes/             ← auth, stocks, trades, portfolio, watchlist,
│       │                          alerts, leaderboard, backtest, admin
│       └── middleware/         ← JWT auth guard
└── frontend/
    ├── package.json
    ├── vite.config.js          ← Vite 5 + proxy to backend :5000
    ├── index.html
    └── src/
        ├── main.jsx
        ├── App.jsx             ← All routes defined here
        ├── index.css           ← Global design system & tokens
        ├── api/index.js        ← All API calls in one place
        ├── context/
        │   └── AuthContext.jsx ← Auth, balance, watchlist, data mode state
        ├── data/
        │   ├── mockStocks.js   ← Simulation mode price generator
        │   └── mockData.jsx    ← Chart helpers + backtest utilities
        ├── components/         ← AppLayout, Sidebar, Topbar, BuySellModal
        └── pages/
            ├── AuthPage.jsx
            ├── LandingPage.jsx
            ├── user/           ← Dashboard, Market, StockDetail, Portfolio,
            │                      Orders, Watchlist, Backtest, Leaderboard,
            │                      Alerts, UserSettings
            └── admin/          ← AdminDashboard, AdminUsers, AdminTrades,
                                   AdminAnalytics, AdminSettings

• Node.js v18 or higher — check with node -v
• MongoDB Atlas free account — no local database needed

1. Go to cloud.mongodb.com → sign in or register
2. Click "Build a Database" → choose Free (M0) → any region → Create
3. Set a Username and Password (save these!)
4. Go to Network Access → Add IP Address → "Allow Access from Anywhere" (0.0.0.0/0) → Confirm
5. Go to Database → Connect → Drivers → copy the connection string:

   mongodb+srv://youruser:[email protected]/?retryWrites=true&w=majority
   

Open backend/.env and paste your connection string:

PORT=5000
MONGO_URI=mongodb+srv://youruser:[email protected]/alphametrics?retryWrites=true&w=majority
JWT_SECRET=alphametrics_super_secret_key_change_in_production

Replace youruser, yourpassword, and cluster0.xxxxx with your real values. The /alphametrics at the end is the database name — Atlas creates it automatically.

# Run from the root alphametrics/ folder
npm install
npm install --prefix backend
npm install --prefix frontend

Or use the shorthand script:

npm run install:all

cd backend
node src/seed.js
cd ..

Expected output:

✅ Connected to MongoDB
🗑  Cleared existing users
   ✓ Created: [email protected]
   ✓ Created: [email protected]
   ✓ Created: [email protected]
   ✓ Created: [email protected]
   ✓ Created: [email protected]
   ✓ Created: [email protected]
   ✓ Created: [email protected]
   ✓ Created: [email protected]
🌱 Seed complete! Demo accounts ready.

# From the root alphametrics/ folder
npm run dev

This starts both servers simultaneously:

• Backend → http://localhost:5000
• Frontend → http://localhost:5173

Open http://localhost:5173 in your browser.

All user accounts use password123. Admin uses admin123.

Stock prices — Yahoo Finance is queried using NSE symbols with the .NS suffix (e.g. RELIANCE.NS). Results are cached in memory for 60 seconds to avoid rate limiting.

Trading — When a user executes a BUY, the trade is saved to MongoDB, the position is created/updated with weighted average price, and the user's balance is deducted. SELL does the reverse and calculates realized P&L.

Equity curve — The portfolio chart is built by replaying all of the user's actual trades day-by-day from MongoDB — not random data.

Backtesting — The /api/backtest endpoint fetches historical OHLC data from Yahoo Finance, runs the selected strategy to generate buy/sell signals, simulates trades, and returns metrics: total return, win rate, max drawdown, and annualized Sharpe ratio.

Price alerts — A setInterval on the backend checks all active alerts every 60 seconds against live Yahoo Finance prices and marks them as triggered when the target is hit.

JWT auth — Tokens are stored in localStorage under am_token and sent as Bearer headers on every API request.

# Install everything
npm run install:all

# Seed demo users (run from root)
cd backend && node src/seed.js && cd ..

# Start everything
npm run dev

# Start only backend
npm run backend

# Start only frontend
npm run frontend

MongoDB connection fails — Check your Atlas URI in backend/.env. Make sure Network Access has 0.0.0.0/0 and your username/password are correct.

"Cannot find module seed.js" — You must cd backend first before running node src/seed.js.

Market shows no data — Switch to Simulation mode in the sidebar toggle (market may be closed). Live data only works 9:15 AM – 3:30 PM IST on weekdays.

Vite JSX error — Make sure all files containing JSX use the .jsx extension, not .js.

Rate limit errors — The backend uses express-rate-limit. If you're hitting limits during development, reduce your polling interval or restart the backend server.

• Frontend → Vercel (auto-deploy from GitHub, vercel.json included)
• Backend → Render.com free tier (always-on Node server)
• Database → MongoDB Atlas (already configured)

1. Go to render.com → New → Web Service
2. Connect your GitHub repo
3. Set these fields:
   • Root Directory: backend
   • Build Command: npm install
   • Start Command: node src/index.js
   • Environment: Node
4. Add Environment Variables (do NOT put these in .env on GitHub):

   MONGO_URI       = your MongoDB Atlas URI
   JWT_SECRET      = a strong random secret (openssl rand -hex 32)
   FRONTEND_URL    = https://your-app.vercel.app   ← add after Vercel deploy
   PORT            = 10000
   

5. Deploy — copy the Render URL e.g. https://alphametrics-api.onrender.com

1. Go to vercel.com → New Project → Import GitHub repo
2. Vercel auto-detects settings from vercel.json — no changes needed
3. Add Environment Variable in Vercel dashboard:

   VITE_API_URL = https://alphametrics-api.onrender.com
   

4. Deploy

1. Copy your Vercel URL e.g. https://alphametrics.vercel.app
2. Go back to Render → your backend service → Environment tab
3. Set FRONTEND_URL = https://alphametrics.vercel.app
4. Click Save — Render redeploys automatically

In frontend/src/api/index.js, change:

const BASE = "/api";

to:

const BASE = import.meta.env.VITE_API_URL
  ? `${import.meta.env.VITE_API_URL}/api`
  : "/api";

This makes it use localhost:5000 locally and your Render URL in production.

• backend/.env is in .gitignore ✅
• All secrets set as environment variables on Render, NOT in code
• JWT_SECRET changed from the default placeholder
• MongoDB Atlas Network Access includes 0.0.0.0/0 (for Render's dynamic IPs)