StockForumX

A real-time stock discussion and prediction platform.
Accuracy-based reputation · Time-expiring knowledge · Live analytics

---

Table of Contents

• Features
• Tech Stack
• Project Structure
• Getting Started
  • Prerequisites
  • Installation
  • Running the Application
  • Docker Quick Start
• Configuration
• Database Schema
• API Endpoints
• Real-Time Events
• Documentation
• Contributing
• License

---

Warning

This application deals with financial data. All predictions and discussions are for informational purposes only.

Tip

Use the "Detailed Documentation" section to understand the architecture before contributing.

Features

• Real-time Chat - Live discussions per stock using WebSockets.
• Q&A System - Time-expiring answers with TTL indexes.
• Prediction System - Track price predictions with accuracy scoring.
• Smart Reputation - Calculated based on accuracy and history.
• Live Analytics - Trending stocks, questions, and insights.
• Manipulation Detection - Flag pump behavior and duplicate predictions.
• Similar Question Detection - Prevent duplicates using TF-IDF logic.

Tech Stack

Area	Technology
Frontend	React, Vite
Backend	Node.js, Express
Database	MongoDB (Mongoose)
Real-time	Socket.io
Auth	JWT
Jobs	node-cron
Microservices	Go (Golang)
Charts	Recharts

Project Structure

StockForumX/
├── client/          # React frontend
│   ├── src/
│   │   ├── pages/
│   │   ├── components/
│   │   ├── hooks/
│   │   └── services/
│   └── package.json
├── server/          # Express backend
│   ├── controllers/
│   ├── routes/
│   ├── models/
│   ├── sockets/
│   ├── jobs/
│   ├── utils/
│   └── package.json
├── services/        # Microservices
│   └── price-updater/ # Go service for stock updates
├── shared/          # Shared constants
├── docs/            # Detailed documentation
└── package.json

Getting Started

Prerequisites

Important

Ensure you have the following installed before proceeding as they are critical for the application to run.

• Node.js (v18+)
• MongoDB (v6+)
• npm or yarn

Note

Go (Golang) is only required if you intend to run or modify the independent microservices (e.g., services/price-updater). The core application runs fine without it.

Installation

1. Clone the repository

   git clone https://github.com/udaykiriti/StockForumX.git
   cd StockForumX

2. Install all dependencies

   npm run install:all

3. Setup environment variables

   cp server/.env.example server/.env

Caution

Never commit your .env file to version control. It contains sensitive secrets like your database URI and JWT keys.

Running the Application

You can run both the client and server concurrently with a single command:

npm run dev

Or run them separately:

npm run dev:server  # Backend on http://localhost:5000
npm run dev:client  # Frontend on http://localhost:5173

Docker Quick Start

This is the easiest way to run the entire application (Frontend, Backend, Database, Services) without installing Node.js, Go, or MongoDB locally.

1. Install Docker

• Windows/Mac: Download and install Docker Desktop.
• Linux: Install docker and docker-compose.

2. Configure Environment

Copy the Docker-specific environment config:

cp .env.docker .env

3. Start the Application

Run the following command in the project root:

docker-compose up --build

• The first run will take a few minutes to download images and build the project.
• Once you see "Entered start loop" or similar logs, the app is ready.

4. Access the App

• Frontend: http://localhost (Running on port 80 via Nginx)
• Backend API: http://localhost/api/health (Proxied via Nginx)

5. Stop the Application

Press Ctrl+C in the terminal, or run:

docker-compose down

Tip

See the Docker Deployment Guide for detailed production configuration.

Configuration

Create a server/.env file with the following variables:

PORT=5000
MONGODB_URI=mongodb://localhost:27017/stockforumx
JWT_SECRET=your_super_secret_key_change_this
NODE_ENV=development

Database Schema

The application uses MongoDB with the following key collections:

• Users: User accounts, authentication, and reputation data.
• Stocks: Stock metadata and pricing information.
• Questions: User-submitted questions.
• Answers: Time-expiring answers (TTL).
• Predictions: Price predictions with scoring.
• ChatMessages: Real-time stock chat lines.
• ReputationSnapshots: Historical reputation data.

API Endpoints

Authentication

• POST /api/auth/register - Register new user
• POST /api/auth/login - Login user
• GET /api/auth/me - Get current user context

Stocks

• GET /api/stocks - List all stocks
• GET /api/stocks/:symbol - Get specific stock details

Questions & Answers

• GET /api/questions - List questions
• POST /api/questions - Create a question
• POST /api/questions/:id/answers - Answer a question

Predictions

• GET /api/predictions - Get recent predictions
• POST /api/predictions - Submit a new prediction

Users

• GET /api/users/leaderboard - View top users
• GET /api/users/:id - View user profile

Real-Time Events

We use Socket.io for real-time updates.

Event Name	Description
chat:message	New message in a stock chat room
question:new	A new question has been posted
answer:new	A new answer has been posted
prediction:new	A new price prediction
stock:update	Real-time price update

Documentation

We have comprehensive documentation available for all parts of the system:

Sub-Project Guides

• Frontend: Client Documentation - Setup, scripts, and component structure.
• Backend: Server Documentation - API overview, jobs, and architecture.
• Services: Price Updater Service - Go microservice details.

Detailed Documentation (docs/)

• Getting Started: Quick setup guide.
• API Reference: Complete endpoint specifications.
• Architecture: System design and data flow.
• Database Schema: Collections and relationship diagrams.
• Authentication: Auth flows and security.
• Real-Time Events: WebSocket event reference.
• Deployment: Production deployment guides.
• Troubleshooting: Common issues and fixes.

Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository.
2. Create a feature branch (git checkout -b feature/amazing-feature).
3. Commit your changes (git commit -m 'Add amazing feature').
4. Push to the branch (git push origin feature/amazing-feature).
5. Open a Pull Request.

Note

Please ensure you add tests for any new features.

Backend tests: cd server && npm test Frontend tests: cd client && npm test

License

This project is licensed under the GNU General Public License v2.0 (GPL-2.0). See the LICENSE file for details.