Stonker: Investor simulator

Video Demo: https://youtu.be/DEfytcz2D5c

(This is my final project for CS50W course)

Description

This is a web application/game made with Django, JS, HTML and CSS. It is a stock market investment game in which the players invest in US stocks listed on Nasdaq and NYSE virtually(No real money involved). Everyone has infinite money and there is no bound on how much they can invest. The ultimate goal is to rank higher on the leaderboard, which ranks players based on their gains/profits from investing in stocks. All the stock data comes from yfinance api.

Distinctiveness and Complexity

Distinctiveness

• Stonker is uniquely positioned as a game rather than a traditional social network or e-commerce platform, which sets it apart from previous course projects:
• The application's primary focus is on simulating a competitive investment environment. Unlike social networks, it doesn't facilitate direct user-to-user communication; the only interaction is through competitive rankings on the leaderboard.
• Stonker is explicitly not an e-commerce site. The stocks available for investment are real-world US market listings, not items posted by other users. Players don't buy or sell stocks from each other within the application; instead, they interact with a simulated market, which differs from traditional online commerce.

Complexity

Stonker demonstrates significant complexity by combining features from various prior projects while introducing new challenges, satisfying requirements for complexity, mobile view, and model usage:

• Live External API Integration & Data Handling: The application heavily relies on the yfinance API to fetch real-time and historical stock data. This involves:

  • Data Cleaning and Formatting: Raw data from the API needs extensive processing, formatting, and conversion to be effectively used and displayed within the Django application and JavaScript frontend.
  • Live Market Data: Unlike e-commerce projects that might deal with static product listings, Stonker handles live market prices that change every second, requiring dynamic updates and calculations that are valid for the present moment.

• Robust Edge Case Management: The project meticulously handles numerous edge cases critical for a financial simulation:

  • Market Closed: Logic accounts for weekends and holidays when the market is closed, ensuring appropriate display of data and handling of transactions.
  • Off-Market Purchases: The system manages purchases made when the market is not actively trading.
  • Historical Graph Display: Ensuring price graphs accurately reflect data even when the market is closed.

• Heavy Django-JavaScript Communication: There is substantial interaction and data exchange between the Django backend and the JavaScript frontend to support dynamic updates, interactive graphs, real-time calculations and transfer of data from client to server with one User model used to store all data related to a player.

• Integration of New Libraries: Building this project necessitated learning and proficiently using several new, specialized libraries:

  • Chart.js: Utilized for rendering interactive and dynamic price graphs for individual stocks and the user's overall portfolio value on the frontend.
  • Pandas: Employed for efficient structuring, manipulation, and analysis of large datasets of stock price information received from the API.
  • yfinance API: The primary data source, requiring careful integration to fetch real-time quotes, historical data, and company information.

• Interactive Portfolio and Stock Graphs: The application generates dynamic graphs (powered by Chart.js) for individual stocks and also a combined graph for the overall portfolio, visualizing performance over time, which requires complex data aggregation.

• Mobile Responsiveness: The entire application is designed to be mobile-responsive, ensuring a consistent and usable experience across various screen sizes.

Project Structure

• finance/: Stonker application
• views.py: Contains the main logic for the app and the views.
• models.py: Contains the model classes for the app.
• urls.py: Contains url patterns for the app.
• static/: Directory containing all the non-html static files (CSS, JS) in their respective subdirectories.
• templates/: Directory containing the html views.
• templatetags/: Directory containing custom template tags created for formatting in django template.
• requirements.txt: Contains list of all required libraries to be installed for using the application.

Usage:

Setup:

• Install Python version 3.x.
• Install Django version 5.x.
• Install the required libraries:

  pip install -r requirements.txt
  

• Create and apply migrations:

  python manage.py makemigrations
  python manage.py migrate
  

• Start the server:

  python manage.py runserver 8000
  

Use application:

• Load the webapp into the browser at http://127.0.0.1:8000
• Create user account on the signup section.
• Now you can use the application as you want

Additional usage info:

• To start investing, go to the portfolio page from the menu. click on the add investment button, Enter the symbol of the stock you want to invest in (Eg. META) along with the quantity of stocks you want to buy. Then click add and wait for the page to reload.

Loading the pages might be really slow since the yfinance API is not as fast.

• The graph on the portfolio will show you the overall price of your portfolio by combining the graphs of all the stocks in the portfolio.

• There are two kinds of profits/gains:

  • Realised gains: are the profits made by a user after selling their investments.
  • Unrealised gains: is the profit/loss on the stocks purchased that are not yet sold.

• Rankings on the leaderboard are on Unrealised gains by default, but the option to sort by Realised gains is available.