Open-Dev-Society/OpenStock

New from Open Dev Society: kitbash . Before you build, find out which parts already exist on GitHub. Borrow them, adapt them, or write the rest. © Open Dev Society. This project 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. OpenStock OpenStock is an open-source alternative to expensive market platforms. Track real-time prices, set personalized alerts, and explore detailed company insights — built openly, for everyone, forever free. Note: OpenStock is community-built and not a brokerage. Market data may be delayed based on provider rules and your configuration. Nothing here is financial advice. 📋 Table of Contents ✨ Introduction 🌍 Open Dev Society Manifesto ⚙️ Tech Stack 🔋 Features 🤸 Quick Start 🐳 Docker Setup 🔐 Environment Variables 🧱 Project Structure 📡 Data & Integrations 🌍 Market Support 🧪 Scripts & Tooling 🤝 Contributing 🛡️ Security 📜 License 🙏 Acknowledgements ✨ Introduction OpenStock is a modern stock market app powered by Next.js (App Router), shadcn/ui and Tailwind CSS, Better Auth for authentication, MongoDB for persistence, Finnhub for market data, and TradingView widgets for charts and market views. 🌍 Open Dev Society Manifesto We live in a world where knowledge is hidden behind paywalls. Where tools are locked in subscriptions. Where information is twisted by bias. Where newcomers are told they’re not “good enough” to build. We believe there’s a better way. Our Belief: Technology should belong to everyone. Knowledge should be open, free, and accessible. Communities should welcome newcomers with trust, not gatekeeping. Our Mission: Build free, open-source projects that make a real difference: Tools that professionals and students can use without barriers. Knowledge platforms where learning is free, forever. Communities where every beginner is guided, not judged. Resources that run on trust, not profit. Our Promise: We will never lock knowledge. We will never charge for access. We will never trade trust for money. We run on transparency, donations, and the strength of our community. Our Call: If you’ve ever felt you didn’t belong, struggled to find free resources, or wanted to build something meaningful — you belong here. Because the future belongs to those who build it openly. ⚙️ Tech Stack Core Next.js 15 (App Router), React 19 TypeScript Tailwind CSS v4 (via @tailwindcss/postcss) shadcn/ui + Radix UI primitives Lucide icons Auth & Data Better Auth (email/password) with MongoDB adapter MongoDB + Mongoose Finnhub API for symbols, profiles, and market news TradingView embeddable widgets Automation & Comms Inngest (events, cron, AI inference via Gemini) Nodemailer (Gmail transport) next-themes, cmdk (command palette), react-hook-form Language composition TypeScript (~93.4%), CSS (~6%), JavaScript (~0.6%) 🔋 Features Authentication Email/password auth with Better Auth + MongoDB adapter Protected routes enforced via Next.js middleware Global search and Command + K palette Fast stock search backed by Finnhub Popular stocks when idle; debounced querying Watchlist Per-user watchlist stored in MongoDB (unique symbol per user) Stock details TradingView symbol info, candlestick/advanced charts, baseline, technicals Company profile and financials widgets Optional cross-source sentiment insights for Reddit, X.com, news, and Polymarket Market overview Heatmap, quotes, and top stories (TradingView widgets) Personalized onboarding Collects country, investment goals, risk tolerance, preferred industry Email & automation AI-personalized welcome email (Gemini via Inngest) Daily news summary emails (cron) personalized using user watchlists Polished UI shadcn/ui components, Radix primitives, Tailwind v4 design tokens Dark theme by default Keyboard shortcut Cmd/Ctrl + K for quick actions/search 🤸 Quick Start Prerequisites Node.js 20+ and pnpm or npm MongoDB connection string (MongoDB Atlas or local via Docker Compose) Finnhub API key (free tier supported; real-time may require paid) Gmail account for email (or update Nodemailer transport) Optional: Google Gemini API key (for AI-generated welcome intros) Clone and install git clone https://github.com/Open-Dev-Society/OpenStock.git cd OpenStock # choose one: pnpm install # or npm install Configure environment Create a .env file (see Environment Variables ). Verify DB connectivity: pnpm test:db # or npm run test:db Run development # Next.js dev (Turbopack) pnpm dev # or npm run dev Run Inngest locally (workflows, cron, AI) npx inngest-cli@latest dev Build & start (production) pnpm build && pnpm start # or npm run build && npm start Open http://localhost:3000 to view the app. 🐳 Docker Setup You can run OpenStock and MongoDB easily with Docker Compose. Ensure Docker and Docker Compose are installed. docker-compose.yml includes two services: openstock (this app) mongodb (MongoDB database with a persistent volume) Create your .env (see examples below). For the Docker setup, use a local connection string like: MONGODB_URI = mongodb://root:example@mongodb:27017/openstock?authSource=admin Start the stack: # from the repository root docker compose up -d mongodb && docker compose up -d --build Access the app: App: http://localhost:3000 MongoDB is available inside the Docker network at host mongodb:27017 Notes The app service depends_on the mongodb service. Credentials are defined in Compose for the MongoDB root user; authSource=admin is required on the connection string for root. Data persists across restarts via the docker volume. Optional: Example MongoDB service definition used in this project: services : mongodb : image : mongo:7 container_name : mongodb restart : unless-stopped environment : MONGO_INITDB_ROOT_USERNAME : root MONGO_INITDB_ROOT_PASSWORD : example ports : - " 27017:27017 " volumes : - mongo-data:/data/db healthcheck : test : ["CMD", "mongosh", "--eval", "db.adminCommand('ping')"] interval : 10s timeout : 5s retries : 5 volumes : mongo-data : 🔐 Environment Variables Create .env at the project root. Choose either a hosted MongoDB (Atlas) URI or the local Docker URI. Hosted (MongoDB Atlas): # Core NODE_ENV = development # Database (Atlas) MONGODB_URI = mongodb+srv://<user>:<pass>@<cluster>/<db>?retryWrites=true&w=majority # Better Auth BETTER_AUTH_SECRET = your_better_auth_secret BETTER_AUTH_URL = http://localhost:3000 # Finnhub # Note: NEXT_PUBLIC_FINNHUB_API_KEY is required for Vercel deployment NEXT_PUBLIC_FINNHUB_API_KEY = your_finnhub_key FINNHUB_BASE_URL = https://finnhub.io/api/v1 # Sentiment insights (optional) ADANOS_API_KEY = your_adanos_api_key # ADANOS_API_BASE_URL=https://api.adanos.org # AI Provider (optional, default: "gemini") # Supported: "gemini", "minimax", "siray" # AI_PROVIDER=gemini # Gemini GEMINI_API_KEY = your_gemini_api_key # MiniMax (optional, used when AI_PROVIDER=minimax or as fallback) # Get your key at https://platform.minimaxi.com # MINIMAX_API_KEY=your_minimax_api_key # Inngest Signing Key (required for Vercel deployment) # Get this from your Inngest dashboard: https://app.inngest.com/env/settings/keys INNGEST_SIGNING_KEY = your_inngest_signing_key # Email (Nodemailer via Gmail; consider App Passwords if 2FA) NODEMAILER_EMAIL = youraddress@gmail.com NODEMAILER_PASSWORD = your_gmail_app_password Local (Docker Compose) MongoDB: # Core NODE_ENV = development # Database (Docker) MONGODB_URI = mongodb://root:example@mongodb:27017/openstock?authSource=admin # Better Auth BETTER_AUTH_SECRET = your_better_auth_secret BETTER_AUTH_URL = http://localhost:3000 # Finnhub # Note: NEXT_PUBLIC_FINNHUB_API_KEY is required for Vercel deployment NEXT_PUBLIC_FINNHUB_API_KEY = your_finnhub_key FINNHUB_BASE_URL = https://finnhub.io/api/v1 # Sentiment insights (optional) ADANOS_API_KEY = your_adanos_api_key # ADANOS_API_BASE_URL=https://api.adanos.