OpenStock Project Introduction

Project Overview

OpenStock is a modern, open-source stock market application designed to provide free and open market-tracking tools for everyone. It serves as an open-source alternative to expensive market platforms, supporting real-time price tracking, personalized alerts, and detailed company insights.

Core Philosophy: Knowledge should be open, free, and accessible; technology belongs to everyone.

Key Features

🔐 Authentication

• Email/password authentication system powered by Better Auth + MongoDB
• Routes protected via Next.js middleware
• Full user session management

🔍 Global Search

• Fast stock search powered by the Finnhub API
• Displays trending stocks when idle, with debounced queries
• Command + K shortcut to open the command palette

⭐ Watchlist

• Each user’s watchlist stored in MongoDB
• Unique ticker symbols per user
• Easy add/remove functionality

📊 Stock Details

• Symbol information from TradingView
• Candlestick/advanced charts, baseline charts, and technical indicators
• Company profile and financial data widgets

📈 Market Overview

• Heatmaps, quotes, and headline news
• Embedded TradingView widgets
• Real-time market data updates

🎯 Personalized Onboarding

• Collects user’s country and investment goals
• Assesses risk tolerance and preferred industries
• Customizes user experience accordingly

📧 Email & Automation

• AI-generated personalized welcome emails (via Inngest calling Gemini)
• Daily news digest emails (scheduled tasks)
• Personalized content based on user’s watchlist

🎨 Polished UI

• shadcn/ui components built on Radix UI primitives
• Tailwind CSS v4 design system
• Default dark theme
• Responsive design

Tech Stack

Core Technologies

• Next.js 15 (App Router)
• React 19
• TypeScript
• Tailwind CSS v4 (via @tailwindcss/postcss)
• shadcn/ui + Radix UI primitives
• Lucide icon library

Authentication & Data

• Better Auth – Email/password authentication with MongoDB adapter
• MongoDB + Mongoose – Data persistence
• Finnhub API – Ticker symbols, company profiles, and market news
• TradingView – Embeddable charting widgets

Automation & Communication

• Inngest – Event handling, scheduled tasks, and AI inference (Gemini)
• Nodemailer – Email delivery (Gmail transport)
• next-themes – Theme switching
• cmdk – Command palette
• react-hook-form – Form handling

Language Composition

• TypeScript (~93.4%)
• CSS (~6%)
• JavaScript (~0.6%)

Project Structure

app/
├── (auth)/                    # Authentication-related pages
│   ├── layout.tsx
│   ├── sign-in/page.tsx
│   └── sign-up/page.tsx
├── (root)/                    # Main app pages
│   ├── layout.tsx
│   ├── page.tsx
│   ├── help/page.tsx
│   └── stocks/[symbol]/page.tsx
├── api/inngest/route.ts       # Inngest API endpoint
├── globals.css
└── layout.tsx

components/
├── ui/                        # shadcn/Radix UI primitives
├── forms/                     # Form components
├── Header.tsx
├── Footer.tsx
├── SearchCommand.tsx
└── WatchlistButton.tsx

database/
├── models/watchlist.model.ts
└── mongoose.ts

lib/
├── actions/                   # Server actions
│   ├── auth
│   ├── finnhub
│   ├── user
│   └── watchlist
├── better-auth/
├── inngest/                   # Inngest client and functions
├── nodemailer/               # Email configuration
├── constants.ts
└── utils.ts

scripts/
└── test-db.mjs               # Database connection test

types/
└── global.d.ts

public/assets/images/         # Logos and screenshots

Quick Start

Prerequisites

• Node.js 20+
• pnpm or npm
• MongoDB connection string (MongoDB Atlas or local Docker)
• Finnhub API key
• Gmail account (for sending emails)
• Optional: Google Gemini API key (for AI-generated content)

Installation Steps

1. Clone the repository

git clone https://github.com/Open-Dev-Society/OpenStock.git
cd OpenStock

2. Install dependencies

pnpm install
# or
npm install

3. Configure environment variables

Create a .env file:

# Core config
NODE_ENV=development

# Database
MONGODB_URI=your_mongodb_connection_string

# Better Auth
BETTER_AUTH_SECRET=your_better_auth_secret
BETTER_AUTH_URL=http://localhost:3000

# Finnhub
FINNHUB_API_KEY=your_finnhub_key
NEXT_PUBLIC_FINNHUB_API_KEY=
FINNHUB_BASE_URL=https://finnhub.io/api/v1

# Inngest AI (Gemini)
GEMINI_API_KEY=your_gemini_api_key

# Email config
NODEMAILER_EMAIL=youraddress@gmail.com
NODEMAILER_PASSWORD=your_gmail_app_password

4. Verify database connection

pnpm test:db

5. Start development server

pnpm dev

6. Start Inngest (for workflows and cron jobs)

npx inngest-cli@latest dev

7. Access the app

Open your browser and visit http://localhost:3000

Docker Deployment

The project includes a Docker Compose setup to quickly launch both the app and MongoDB:

# Start MongoDB
docker compose up -d mongodb

# Build and start the app
docker compose up -d --build

When using Docker, the MongoDB connection string should be:

MONGODB_URI=mongodb://root:example@mongodb:27017/openstock?authSource=admin

Data & Integrations

Finnhub API

• Provides stock search, company profiles, and market news
• Free tier may return delayed quotes
• Rate limits apply

TradingView

• Supplies embeddable chart, heatmap, quote, and other widgets
• External images sourced from i.ibb.co

Better Auth + MongoDB

• Email/password authentication
• MongoDB adapter for session storage
• Most routes are protected except login/signup pages

Inngest Workflows

• User creation event → AI-powered personalized welcome email
• Scheduled job (daily at 12 PM) → Sends news digest email
• Local development uses npx inngest-cli@latest dev

Email Delivery (Nodemailer)

• Uses Gmail as transport
• Includes welcome and news digest email templates
• Professional SMTP service recommended for production

Available Scripts

• pnpm dev – Starts development server (Turbopack)
• pnpm build – Builds for production
• pnpm start – Starts production server
• pnpm lint – Runs ESLint
• pnpm test:db – Verifies database connection

Developer Experience

• TypeScript strict mode
• Tailwind CSS v4 (no separate config file needed)
• shadcn/ui component library
• cmdk command palette
• next-themes for theme switching
• lucide-react icons

Open Dev Society Manifesto

We live in a world where knowledge is hidden behind paywalls, tools are locked behind subscriptions, information is distorted by bias, and beginners are told they’re “not good enough” to build.

Our Beliefs:

• Technology belongs to everyone
• Knowledge should be open, free, and accessible
• Communities should welcome newcomers with trust, not gatekeeping

Our Mission:

• Build genuinely useful free and open-source projects
• Create tools accessible to both professionals and students
• Provide a platform where learning is always free
• Foster communities that guide rather than judge beginners
• Offer resources run on trust—not profit

Our Commitments:

• Never lock away knowledge
• Never charge for access
• Never trade trust for money
• Operate on transparency, donations, and community power

Contribution Guidelines

Contributions are welcome from everyone—students, self-taught developers, and seasoned engineers alike.

• Discuss ideas and bugs via Issues
• Look for issues labeled "good first issue" or "help wanted"
• Keep PRs focused; include screenshots for UI changes
• Be kind, mentor beginners, and reject gatekeeping—that’s the ODS way

Security

If you discover a security vulnerability:

• Do not publicly file an Issue
• Email us at: opendevsociety@cc.cc
• We will coordinate responsible disclosure and patch promptly

License

OpenStock is licensed under AGPL-3.0. If you modify, redistribute, or deploy it (including as a web service), you must release your source code under the same license and credit the original authors.

Acknowledgements

• Finnhub – For accessible market data
• TradingView – For embeddable market widgets
• Communities of shadcn/ui, Radix UI, Tailwind CSS, Next.js
• Inngest – For reliable background tasks and workflows
• Better Auth – For simple and secure authentication
• All contributors who make open-source tools possible

Special thanks to Adrian Hajdin (JavaScript Mastery), whose excellent stock market app tutorial greatly assisted Open Dev Society in building OpenStock.

Built on openness, for everyone, forever free. — Open Dev Society

Project URL: https://github.com/Open-Dev-Society/OpenStock