Skip to content

README.md

Latest commit

 

History

History
215 lines (157 loc) · 8.45 KB

README.md

File metadata and controls

215 lines (157 loc) · 8.45 KB
Banner

📈 Market Pulse

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

Next.js TypeScript Maintained

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

Next.js React TypeScript Tailwind CSS shadcn/ui

Backend & Database

MongoDB Better Auth Inngest

AI & Tools

Gemini AI Finnhub Nodemailer

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.