StockLens

Technical + fundamental stock screener for NSE & BSE equities, served via a React+MUI web UI.

Tech stack: TypeScript end-to-end — Express 5 API, Upstox API data, React 19 frontend.

Quick start

npm install
cd frontend && npm install && cd ..
cd server && npm install && cd ..

cp .env.example .env
# Add your Upstox Analytics Token (Developer Apps → Analytics tab) to .env

npm start

Opens two services:

• :8000 — Express API
• :5173 — React dev server

Prerequisites

• Node.js 22+ (uses nvm; run nvm use if available)
• Upstox Analytics Token (1-year read-only token from Upstox Developer Apps → Analytics tab)

Individual services

cd server   && npx tsx src/index.ts       # API
cd frontend && npm run dev                # UI

API

• GET /api/health — server + Upstox API status
• GET /api/analyze?symbol=TCS&years=2&timeframe=daily — full analysis
• Timeframes: daily, weekly, monthly

Desktop app (macOS / Windows)

The same app can be packaged as a native desktop application: a Tauri 2 shell (system webview) spawns the Express backend as a compiled sidecar binary and opens it in a window. No Node, npm, or terminal needed on the user's machine.

Build requirements (build-time only — users don't need these):

• Rust toolchain (rustup / cargo)
• Bun ≥ 1.1 (brew install bun or the official installer)

Build:

npm run tauri:build
# or step by step:
npm run sidecar        # compiles the backend to 3 platform binaries
npm --prefix frontend run build
cd src-tauri && npx tauri build

Output: src-tauri/target/release/bundle/ — .dmg on macOS, .exe/.msi on Windows.

How the token works in the desktop app: each user pastes their own Upstox Analytics Token in the in-app Settings dialog (gear icon). It is stored in the OS keychain (Keychain / Credential Manager) and injected into the sidecar at launch — it never lives in a file or in the repo.

Unsigned caveats (personal/trusted distribution):

• macOS: first launch requires right-click → Open (no notarization yet).
• Windows: SmartScreen may warn on an unsigned installer.

Project layout

See AGENTS.md for full architecture, indicators, and milestones.