🇳🇵 NepseSage

Professional-Grade Clinical Analysis Platform for the Nepal Stock Exchange

NepseSage transforms raw NEPSE market data into high-precision visual intelligence — combining institutional-grade market analytics, AI-powered insights, behavioral psychology tracking, and a risk-free trading simulator in a single, cohesive platform.

Overview

NepseSage is a full-stack financial intelligence platform built specifically for the Nepal Stock Exchange (NEPSE). It is designed around a "Clinical Analyst" philosophy: high data density, zero-latency interactions, and a professional aesthetic — giving retail investors the same toolset previously available only to institutional traders.

The platform covers the complete investor workflow:

Discover — Live market data, sector performance, top movers, and company fundamentals.
Analyze — Technical indicators (RSI, MACD, Bollinger Bands, SMA), chart series, and market depth.
Strategize — AI-powered stock analysis and sentiment aggregation via the Sage AI engine.
Track — Portfolio management with P&L metrics, historical value tracking, and a discipline score.
Learn — A behavioral trading journal that identifies cognitive biases and psychological patterns.
Compete — A paper-trading simulator and community leaderboard using real market data.
Share — A community insights board where users post and discuss trade setups.

Features

📊 Clinical Dashboard

The mission-control home screen for every investor session.

Real-time portfolio value, cost basis, unrealized P&L, and return percentage.
Discipline Score — a proprietary 0–100 metric that tracks adherence to the user's own trading plan.
Risk Meter — live Portfolio Beta and volatility ratings.
Market summary widget with NEPSE index, turnover, and advance/decline breadth.

📈 Market Intelligence

Complete NEPSE market data, always in sync.

Market status (open/closed), live index value, total turnover, and sub-index breakdown.
Top gainers, losers, and turnover leaders.
Sector performance heatmap across all NEPSE-listed sectors.
Symbol search with company fundamentals panel (EPS, P/E, book value, etc.).
Floorsheet data for any traded symbol.

🔬 Technical Analysis

Professional-grade charting and indicator data.

OHLCV price history for all symbols, stored and served from MongoDB for speed.
Pre-computed EOD indicators: RSI, MACD, SMA-20/50/200, Bollinger Bands.
Full chart-series arrays for multi-panel indicator rendering.
Market depth (buyer/seller queue) for any symbol.
Index history with configurable range (1M, 3M, 1Y, ALL) and advance/decline breadth series.

🤖 Sage AI

Groq-powered market intelligence (Llama 3.3 70B), contextualized for NEPSE.

Symbol Analyzer: Input a ticker (e.g., NICA, NTC) and receive a structured technical + sentiment breakdown.
AI Chat: Conversational interface for open-ended market questions.
Market Sentiment: Aggregates NEPSE-wide sentiment signals.
Journal AI: Automatically analyzes journal entries to detect behavioral patterns and emotional biases.

🧠 Behavior Lab (Trading Journal)

The psychological edge most platforms ignore.

Log trades with emotional state, rationale, outcome, and free-form notes.
Automatic bias detection: flags FOMO, Revenge Trading, Overconfidence, Anchoring, and more.
Discipline Heatmap: GitHub-style calendar showing trading activity and discipline over time.
Psychological Sentiment Trend: Line chart tracking emotional state across trading sessions.
Discipline Score is recalculated after every journal entry.

🎮 Paper Trading Simulator

Risk-free strategy testing with real NEPSE prices.

Start with a configurable virtual capital amount.
Place buy/sell orders that execute at live-fetched market prices.
View full order history and simulated portfolio performance.
Reset anytime to start a new strategy run.

🏆 Leaderboard

Community accountability and competition.

Ranks all simulator participants by portfolio performance.
Encourages disciplined trading through transparent public scoring.

💡 Community Insights

A curated feed of trade ideas from the NepseSage community.

Post bullish, bearish, or neutral insights tied to a specific symbol.
Like and comment on insights from other analysts.
Filter by sentiment or symbol.

Architecture

NepseSage follows a monorepo structure separating concerns between a REST API backend and a Next.js frontend. The backend operates an automated data pipeline that ingests, normalizes, and serves live and historical NEPSE data.

┌─────────────────────────────────────────────────────────────┐
│                        Client (Browser)                      │
│             Next.js 15 App Router + React 19                 │
└──────────────────────────┬──────────────────────────────────┘
                           │ HTTPS / REST
                           ▼
┌─────────────────────────────────────────────────────────────┐
│                  Express.js API Server                        │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌────────────┐  │
│  │  Auth    │  │  NEPSE   │  │Portfolio │  │  Sage AI   │  │
│  │  Routes  │  │  Routes  │  │  Routes  │  │  Routes    │  │
│  └──────────┘  └──────────┘  └──────────┘  └────────────┘  │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌────────────┐  │
│  │  Journal │  │Simulator │  │ Insights │  │Leaderboard │  │
│  │  Routes  │  │  Routes  │  │  Routes  │  │  Routes    │  │
│  └──────────┘  └──────────┘  └──────────┘  └────────────┘  │
│                                                              │
│                  NEPSE Data Pipeline                         │
│  ┌────────────────────────────────────────────────────────┐  │
│  │  nepseScheduler → nepseSyncService                     │  │
│  │       → nepseFetcher (@rumess/nepse-api)               │  │
│  │       → nepseAdapter (normalize + transform)           │  │
│  │       → MongoDB (persist)                              │  │
│  └────────────────────────────────────────────────────────┘  │
└──────────────────────────┬──────────────────────────────────┘
                           │ Mongoose ODM
                           ▼
┌─────────────────────────────────────────────────────────────┐
│                     MongoDB Atlas                            │
│  Collections: users, marketdata, indexhistory, indexsnapshot │
│               portfolios, simulators, journalentries,        │
│               insights, comments                             │
└─────────────────────────────────────────────────────────────┘
                           │
                           ▼
              ┌─────────────────────────┐
              │  Groq API (Llama 3.3)   │
              └─────────────────────────┘

Tech Stack

Frontend (`/web-app`)

Category	Technology	Version
Framework	Next.js (App Router)	15
Language	TypeScript (strict mode)	5
UI Library	React	19
Styling	Tailwind CSS	4
Component Library	Shadcn UI (Radix UI primitives)	Latest
Animation	Framer Motion	11
Charts	Recharts	2
Forms	React Hook Form + Zod	7 + 3
State	React Context API	—
HTTP Client	Fetch API (custom `services.ts`)	—
Fonts	Space Grotesk (heading), DM Sans (body)	—

Backend (`/server`)

Category	Technology	Version
Runtime	Node.js (ES Modules)	20+
Framework	Express.js	5
Language	JavaScript (ESM)	—
Database	MongoDB + Mongoose ODM	9
Authentication	JSON Web Tokens (JWT)	9
Password Hashing	Bcryptjs	3
AI Integration	Groq SDK (Llama 3.3 70B)	Latest
NEPSE Data	@rumess/nepse-api	1
Scheduler	node-cron	4
Validation	Zod	4

Project Structure

NepseSage/
│
├── server/                          # Express.js Backend
│   ├── src/
│   │   ├── app.js                   # Entry point — Express app, CORS, route mounting
│   │   ├── config/
│   │   │   └── db.js                # MongoDB connection (Mongoose)
│   │   │
│   │   ├── controllers/             # Business logic, request/response handlers
│   │   │   ├── aiController.js      # Groq — stock analysis, chat, sentiment
│   │   │   ├── authController.js    # Register, login, profile, plan management
│   │   │   ├── insightController.js # Community insights CRUD, likes, comments
│   │   │   ├── journalController.js # Trade journal entries, discipline, bias stats
│   │   │   ├── leaderboardController.js  # Simulator performance rankings
│   │   │   ├── nepseController.js   # Market data — summary, symbols, movers, history
│   │   │   ├── portfolioController.js    # Portfolio CRUD, transaction history
│   │   │   └── simulatorController.js   # Paper trading — orders, reset, balances
│   │   │
│   │   ├── middleware/
│   │   │   ├── authMiddleware.js    # JWT verification (protect guard)
│   │   │   ├── errorMiddleware.js   # Global error handler + 404 handler
│   │   │   └── validateMiddleware.js # Zod schema validation middleware
│   │   │
│   │   ├── models/                  # Mongoose schemas
│   │   │   ├── User.js              # User — auth, preferences, plan, discipline score
│   │   │   ├── MarketData.js        # OHLCV + technicals per symbol
│   │   │   ├── IndexHistory.js      # Daily NEPSE index time series
│   │   │   ├── IndexSnapshot.js     # Latest index state snapshot
│   │   │   ├── Portfolio.js         # User portfolio holdings
│   │   │   ├── JournalEntry.js      # Trade journal entries with emotion/bias data
│   │   │   ├── Simulator.js         # Paper trading account + orders
│   │   │   ├── Insight.js           # Community insight posts
│   │   │   └── Comment.js           # Comments on insights
│   │   │
│   │   ├── pipeline/                # Automated NEPSE data ingestion
│   │   │   ├── nepseScheduler.js    # node-cron job definitions (startup, intraday, EOD)
│   │   │   ├── nepseSyncService.js  # Orchestration — coordinates fetch → adapt → persist
│   │   │   ├── nepseFetcher.js      # Calls @rumess/nepse-api for live data
│   │   │   └── nepseAdapter.js      # Normalizes raw API responses to DB schema
│   │   │
│   │   ├── routes/                  # Express router definitions
│   │   │   ├── authRoutes.js
│   │   │   ├── nepseRoutes.js
│   │   │   ├── portfolioRoutes.js
│   │   │   ├── journalRoutes.js
│   │   │   ├── simulatorRoutes.js
│   │   │   ├── aiRoutes.js
│   │   │   ├── insightRoutes.js
│   │   │   └── leaderboardRoutes.js
│   │   │
│   │   ├── services/
│   │   │   ├── technicalAnalysis.js # RSI, MACD, SMA, Bollinger Band computation
│   │   │   └── disciplineService.js # Discipline score calculation logic
│   │   │
│   │   └── utils/
│   │       ├── generateToken.js     # JWT signing helper
│   │       ├── schemas.js           # Shared Zod validation schemas
│   │       └── sectorNormalizer.js  # Maps NEPSE sector names → canonical categories
│   │
│   ├── scripts/
│   │   ├── seedCompanyMaster.js     # One-time/weekly company metadata seeding
│   │   ├── backfillHistory.js       # Backfill historical OHLCV for all symbols
│   │   └── test_nepse.js            # Manual NEPSE API connectivity test
│   │
│   ├── .env                         # Environment variables (see below — DO NOT COMMIT)
│   └── package.json
│
└── web-app/                         # Next.js 15 Frontend
    ├── src/
    │   ├── app/                     # Next.js App Router
    │   │   ├── layout.tsx           # Root layout — fonts, ThemeProvider
    │   │   ├── globals.css          # OKLCH design tokens, Tailwind base
    │   │   ├── (auth)/              # Auth route group (no sidebar)
    │   │   │   ├── login/page.tsx
    │   │   │   └── signup/page.tsx
    │   │   └── (dashboard)/         # Authenticated route group (with sidebar)
    │   │       ├── market/          # Market overview page
    │   │       ├── companies/       # All listed companies
    │   │       ├── companyDetails/[symbol]/  # Individual company deep-dive
    │   │       ├── sectors/         # Sector performance page
    │   │       ├── sage-ai/         # AI chat and analysis interface
    │   │       ├── journal/         # Trading journal & behavior lab
    │   │       ├── simulator/       # Paper trading simulator
    │   │       ├── insights/        # Community insights board
    │   │       ├── leaderboard/     # Simulator leaderboard
    │   │       ├── settings/        # User preferences and profile
    │   │       └── upgrade/         # Pro plan upgrade page
    │   │
    │   ├── components/
    │   │   ├── dashboard/           # Dashboard widgets (P&L, discipline score, risk meter)
    │   │   ├── market/              # Market summary, charts, movers, floorsheet, depth
    │   │   ├── journal/             # Journal table, heatmap, sentiment trend, entry sheet
    │   │   ├── sage-ai/             # AI chat input, message renderer, context sheet
    │   │   ├── insights/            # Insights feed, create/edit forms
    │   │   ├── navigation/          # Navbar, Sidebar, Footer
    │   │   ├── notifications/       # Notification panel
    │   │   ├── search/              # Global command-palette search
    │   │   ├── shared/              # AuthGuard, ThemeProvider, UpgradeNudge
    │   │   └── ui/                  # Shadcn UI primitives (50+ components)
    │   │
    │   ├── context/
    │   │   ├── AuthContext.tsx      # JWT auth state — login, logout, user object
    │   │   └── PortfolioContext.tsx # Portfolio data — holdings, transactions
    │   │
    │   ├── hooks/
    │   │   ├── useNepse.ts          # Market data fetching hooks
    │   │   ├── useJournal.ts        # Journal CRUD hooks
    │   │   ├── usePortfolio.ts      # Portfolio mutation hooks
    │   │   ├── useSimulator.ts      # Simulator order hooks
    │   │   └── use-mobile.tsx       # Responsive breakpoint detection
    │   │
    │   └── lib/
    │       ├── services.ts          # All API call functions (typed)
    │       ├── api.ts               # Axios/Fetch base client with auth header injection
    │       └── utils.ts             # Tailwind `cn()` merge utility
    │
    ├── .env.local                   # Frontend environment variables (see below)
    ├── next.config.js
    ├── tailwind.config.ts
    └── package.json

API Reference

All API endpoints are prefixed with /api. Protected routes require a Bearer <token> Authorization header.

Authentication — `/api/auth`

Method	Endpoint	Auth	Description
`POST`	`/auth/register`	Public	Register a new user. Body: `{ name, email, password }`
`POST`	`/auth/login`	Public	Login and receive a JWT. Body: `{ email, password }`
`GET`	`/auth/me`	🔒	Get the current authenticated user's profile.
`PUT`	`/auth/me`	🔒	Update profile (name, avatar, risk tolerance, trading goal, watchlist).
`PUT`	`/auth/change-password`	🔒	Change password. Body: `{ currentPassword, newPassword }`
`POST`	`/auth/upgrade`	🔒	Upgrade account to Pro plan.
`POST`	`/auth/downgrade`	🔒	Downgrade account to Free plan.