📈 Market Pulse

Real-time market dashboards, watchlists, alerts, and AI-generated email digests.
Built with Next.js 16 App Router, Tailwind v4, and MongoDB.

Overview • Key Features • Tech Stack • Getting Started • Env Variables • Deployment

---

📋 Overview

Market Pulse is a high-performance financial dashboard designed to eliminate the noise of stock monitoring. Built for speed and clarity, it leverages the Next.js App Router and Server-Sent Events (SSE) to deliver real-time data without the bloat.

Users can create custom watchlists, set price alerts, and receive AI-curated email summaries (powered by Gemini) to stay ahead of the market. The application features a "zero-flash" user experience, using a blurred loader overlay to ensure smooth transitions between data-heavy views.

---

✨ Key Features

Feature	Description
🔐 Secure Auth	Robust Email/Password authentication using Better Auth with secure session cookies.
🛡️ Protected Shell	Middleware-protected routes ensure unauthorized users cannot access the dashboard.
⚡ Real-Time Stream	Custom SSE (Server-Sent Events) endpoint streams batched price updates instantly.
📉 Interactive Charts	Embedded TradingView widgets for Heatmaps, Tickers, and Technical Analysis.
🤖 AI Workflows	Gemini AI generates personalized daily news digests and welcome emails via Inngest.
🔔 Smart Alerts	Configure price thresholds to receive instant email notifications via Nodemailer.

---

🛠 Tech Stack

Framework & UI

Backend & Database

AI & Tools

Technology Details

• Next.js: A powerful React framework for building full-stack web applications with server-side rendering and API routes.
• TypeScript: A statically typed superset of JavaScript that improves code quality, tooling, and error detection.
• Better Auth: A framework-agnostic authentication library providing built-in support for email/password and social sign-on.
• Inngest: A platform for event-driven workflows and background jobs (used here for AI workflows and alerts).
• MongoDB: A flexible, high-performance NoSQL database for storing user data and watchlists.
• Finnhub: A real-time financial data API providing stock market data, economic indicators, and news.
• Gemini AI: Google's AI model used to generate smart email digests and summaries.
• Nodemailer: A Node.js library for handling transactional emails and notifications.
• TailwindCSS & Shadcn: Utility-first CSS framework and accessible component library for rapid UI development.

---

📂 Project Structure

market-pulse/
├── public/
│   └── assets/              # Images, icons, branding
│
├── scripts/                 # Setup & DB test scripts
│
├── src/
│   ├── app/                 # Next.js App Router
│   │   ├── (auth)/          # Authentication pages
│   │   ├── (root)/          # Protected pages (Dashboard, Watchlist, Stock)
│   │   ├── api/             # Auth, SSE, Inngest APIs
│   │   └── landing/         # Marketing / landing page
│   │
│   ├── components/          # UI & feature components
│   │   ├── ui/              # Reusable UI (shadcn-based)
│   │   ├── watchlist/       # Watchlist & alerts UI
│   │   └── landing/         # Landing page sections
│   │
│   ├── database/            # Mongoose models & connection
│   ├── lib/                 # Auth, AI, email, utilities
│   ├── context/             # Global state (Watchlist)
│   └── middleware/          # Route protection
│
├── .env                     # Environment variables
├── next.config.ts
├── package.json
└── README.md

Key API Routes

• /api/quotes/stream: Handles SSE streaming for real-time batched price updates.
• /api/inngest: Handles background jobs (AI email generation, Cron schedules) without affecting user experience.
• /api/auth/*: Better Auth handler.

---

🚀 Getting Started

Follow these steps to run Market Pulse on your local machine.

1. Install Dependencies

Clone the repository and install packages.

git clone [https://github.com/your-username/market-pulse.git](https://github.com/your-username/market-pulse.git)
cd market-pulse
npm install

Note: A postinstall script will run automatically to patch specific TS configurations.

2. Configure Environment

Create a .env file in the root directory and fill in the required variables (see below).

3. Run Development Server

npm run dev

Open http://localhost:3000 with your browser.

4. (Optional) Run Inngest

To test AI workflows and background jobs locally:

npx inngest-cli@latest dev

5. (Optional) Test Database Connectivity

node scripts/test-db.js

---

🔑 Environment Variables

Create a .env file in the root directory:

Variable	Description
MONGODB_URI	Connection string for MongoDB Atlas.
MONGODB_DB_NAME	Database name (e.g., market-pulse).
BETTER_AUTH_SECRET	A secure random string used to sign session tokens.
NEXT_PUBLIC_FINNHUB_API_KEY	API Key from Finnhub (for market data/news).
GEMINI_API_KEY	Google Gemini API Key (for AI email summaries).
NODEMAILER_EMAIL	Gmail address used to send alerts.
NODEMAILER_PASSWORD	Gmail App Password (recommended).
BETTER_AUTH_URL	(Optional) Server-side base URL.

---

🚢 Deployment

This project is optimized for Vercel.

1. Push to GitHub: Commit your changes to your main branch.
2. Import to Vercel: Connect your repository in the Vercel Dashboard.
3. Add Environment Variables: Copy your .env values into Vercel's "Environment Variables" settings.
4. Deploy: Click deploy.

---

📄 Scripts

• npm run dev: Start Next.js in development mode.
• npm run build: Build the application for production.
• npm run start: Start the production server.
• npm run lint: Run ESLint checks.

---

🙏 Acknowledgments

• TradingView for the powerful charting widgets.
• Finnhub for the reliable financial data API.
• Better Auth for the seamless authentication experience.
• Inngest for making serverless queues and AI workflows easy.