Stock Analyzer

An enterprise-grade, high-performance financial tracking dashboard built utilizing the decoupled MERN stack. Designed with a frosted glassmorphism interface, Stock Analyzer allows investors to monitor real-time stock quotes, visualize chronological price trends, obtain AI-driven stock insights via Groq LLM, manage customized watchlists, and query real-time market data securely. The backend employs a multi-provider fallback system (Finnhub → Alpha Vantage → Twelve Data) ensuring maximum uptime and resilience against API rate limits. The entire application is fully containerized with Docker for consistent, environment-independent deployment.

Live URL: https://stock-analyzer-mvyi.onrender.com/portfolio
API Server Endpoint: https://stock-analyzer-mvyi.onrender.com

System Architecture & Workflow

[ Client: React + Recharts + Axios ]
           │             ▲
    HTTPS  │             │ JSON Web Tokens (JWT)
           ▼             │
[ API Gateway & Routing (Express + Cors) ]
           │             ▲
           ▼             │ Mongoose ODM / Groq SDK
[ Business Logic & Security (BcryptJS / Multi-Provider / Groq) ]
      │                  │                            │
      ▼                  ▼                            ▼
[ MongoDB Atlas ]  [ Finnhub → Alpha Vantage ]  [ Groq Cloud LLM ]
                   [     → Twelve Data       ]  (Llama 3.1 8B)

Authentication Flow: Users register or log in. Server-side verification validates user credentials securely. Sessions are authorized via JSON Web Tokens, which are cached client-side.
Gateway Router: API routing filters cross-origin (CORS) queries and applies JWT authorization checkpoints to secure user endpoints.
Live Search Suggestions: User inputs trigger backend requests to search endpoints, querying ticker recommendations from global exchanges.
Stock Valuation & Metrics: Fetched stocks populate detailed cards. Clicking "Load Historical Chart" generates interactive market charts based on one-month historical quote data.
AI Financial Analysis: Groq Cloud SDK executes prompt-engineered evaluation pipelines generating structured stock outlooks (sentiment, recommendations, risks).
Portfolio Compilation: Ticker mappings are stored securely in MongoDB database records. During page load, the backend aggregates watchlist mappings with live valuation quotes asynchronously.

Core Features

JWT Authenticated Environment: Robust login and signup operations securing custom user endpoints.
Auto-complete Query Engine: Fast, query-responsive symbol matching search capabilities.
Live Valuation Aggregator: Real-time stock quote lookups (prices, exchange data, open/close, daily highs and lows, volume metrics).
Interactive Chronological Charts: One-month trend analysis powered by responsive data visualizer widgets.
AI Stock Analysis: Structured fundamental & sentiment evaluation powered by Groq LLM (llama-3.1-8b-instant) with clear investment takeaways, strengths, and risk breakdowns.
AI Finance Assistant: Embedded conversational interface offering contextual answers to stock queries and investing principles.
Relational Watchlist Engine: Personalized dashboards listing current assets with real-time price updates.
Docker Containerization: Full multi-service Docker setup for reproducible local and production deployments.

Technical Mechanism Overview

Tool / Technology	Technical Role	Implementation Purpose
Axios	Client HTTP Agent	Communicates asynchronously with Node endpoints; appends JWT tokens in Request Headers for secure routing validation.
CORS	Cross-Origin Middleware	Controls client access domains; restricts and regulates traffic from authorized local hosts.
BcryptJS	Cryptographic Hashing	Secures passwords using salted one-way hashing algorithms prior to database storage.
Recharts	Interactive Visualization	Renders dynamic SVG charts representing historical stock values, including customizable tooltip cards.
Groq Cloud API	AI Inference Engine	Powers real-time financial Q&A and structured stock sentiment analysis using Llama 3.1.
Finnhub API	Primary Data Provider	Serves stock quotes (`/quote`), search suggestions (`/search`), and historical candle data (`/stock/candle`).
Alpha Vantage API	Secondary Fallback	Provides `GLOBAL_QUOTE`, `SYMBOL_SEARCH`, and `TIME_SERIES_DAILY` endpoints when Finnhub is rate-limited.
Twelve Data API	Tertiary Fallback	Supplies `/quote`, `/symbol_search`, and `/time_series` endpoints as final fallback provider.
Docker	Containerization	Packages the client, server, and MongoDB into isolated, portable containers orchestrated via Docker Compose.

Fallback Strategy: Each data function (quotes, search, historical) tries Finnhub first. On failure (rate limit, error, or invalid response), it automatically falls through to Alpha Vantage, then Twelve Data — ensuring uninterrupted service.

API Documentation

Authentication Endpoints

POST /api/auth/register — Create a new user account.
POST /api/auth/login — Authenticate credentials and return a session token.

Stock Data Endpoints

GET /api/stock/suggestions/search?q=:query — Fetch ticker autocomplete recommendations.
GET /api/stock/:symbol — Retrieve real-time market quote metrics.
GET /api/stock/:symbol/history — Retrieve monthly market close price history.

AI Insights Endpoints (JWT Protected)

GET /api/ai/analyze/:symbol — Generate structured AI stock analysis (sentiment, recommendation, strengths, risks).
POST /api/ai/chat — Contextual finance assistant conversational Q&A endpoint.

Portfolio Endpoints (JWT Protected)

GET /api/portfolio — Fetch user's saved watchlist complete with current live quotes.
POST /api/portfolio/add — Save a new stock to the user's watchlist.
DELETE /api/portfolio/:id — Delete a stock record from the user's watchlist.

Installation & Setup

Prerequisites

Node.js (v18 or higher)
MongoDB (Local instance or Atlas connection URI)

Option A: Run with Docker (Recommended)

The fastest way to run the full stack locally.

Prerequisites: Docker Desktop

Clone the repository:

git clone https://github.com/Aryan-Rustagi/Stock-Analyzer.git
cd Stock-Analyzer

Create server/.env with your API keys:

PORT=5000
MONGO_URI=your_mongodb_connection_string
JWT_SECRET=your_jwt_secret_signing_key
GROQ_API_KEY=your_groq_api_key
FINNHUB_API_KEY=your_finnhub_api_token
ALPHA_VANTAGE_API_KEY=your_alpha_vantage_api_key
TWELVE_DATA_API_KEY=your_twelve_data_api_key

Build and start all services:
```
docker compose up --build
```
Access the application:
- Frontend: http://localhost:5173
- Backend API: http://localhost:5000

To stop:

docker compose down

Option B: Run Locally (Manual)

Backend Configuration

Navigate to the server folder:
```
cd server
```
Install server-side dependencies:
```
npm install
```

Create a .env file in the server directory:

PORT=5000
MONGO_URI=your_mongodb_connection_string
JWT_SECRET=your_jwt_secret_signing_key
GROQ_API_KEY=your_groq_api_key
FINNHUB_API_KEY=your_finnhub_api_token
ALPHA_VANTAGE_API_KEY=your_alpha_vantage_api_key
TWELVE_DATA_API_KEY=your_twelve_data_api_key

Start the backend development server:
```
npm run dev
```

Frontend Configuration

Navigate to the client folder:
```
cd ../client
```
Install client-side dependencies:
```
npm install
```
Start the frontend development server:
```
npm run dev
```

Docker Architecture

The application uses a 3-container Docker Compose setup:

docker-compose.yml
├── client   (React + Vite dev server)  → port 5173
├── server   (Node.js + Express API)    → port 5000
└── mongo    (MongoDB database)         → port 27017

File	Purpose
`client/Dockerfile`	Builds the React frontend container on Alpine Linux
`server/Dockerfile`	Builds the Node.js backend container on Alpine Linux
`docker-compose.yml`	Orchestrates all three services with correct networking
`.dockerignore`	Excludes `node_modules` and build artifacts from container context

Inter-container Networking: The client's Vite dev proxy routes all /api calls to http://server:5000 using Docker's internal DNS, where server is the Docker Compose service name.

Design System & AI Collaboration

This application utilizes a custom design system styled in collaboration with AI tools. The visual presentation features:

Glassmorphism Styling: Containers utilizing backdrop blur properties, thin border lines, and gradient glows.
Ambient Animation System: Fluid keyframe transitions, drifting background gradient orbs, and staggered list renders.
Color Architecture: A dark aesthetic focused on deep indigo, sky blue accents, and bright profit/loss visual indicators.

Learning Outcomes & Professional Development

Building this financial analyzer provided key insights into advanced full-stack development patterns:

1. Advanced State Flow & Component Life Cycle

Structured dynamic state logic cleanly to coordinate search inputs, chart visualizations, loading notifications, and dropdown elements.
Managed side-effect cycles by fetching portfolio data on mount and ensuring proper event and timer cleanup.

2. Full-Stack Data Operations & Async Coordination

Developed Mongoose schemas to establish structured data relationships linking custom portfolios to unique user accounts.
Handled complex asynchronous operations by compiling external API data concurrent streams using Promise.all.

3. Application Security & Access Control

Implemented token-based session tracking utilizing cryptographic password hashing and JSON Web Tokens.
Engineered secure route guards on the React client to restrict access to unauthorized user dashboards.
Moved JWT verification into a centralized protect middleware used consistently across all protected routes.

4. Enterprise-Grade API Design & Resilience

Engineered a multi-provider fallback system (Finnhub → Alpha Vantage → Twelve Data) to ensure uninterrupted service under rate-limiting conditions.
Implemented safe JSON parsing with res.ok checks and try-catch wrappers to gracefully handle non-JSON error responses (e.g., plain-text "Too Many Requests").
Integrated all API fetches strictly on the backend to protect credentials and bypass cloud host restrictions (like Render IP blocking).
Resolved API key resolution by using dynamic process.env reads inside request-time functions, preventing stale values from module caching.

5. Docker & Containerization

Containerized a MERN stack application using a multi-service Docker Compose setup with isolated Alpine Linux containers.
Resolved platform-specific native binding issues (Rolldown/Vite musl bindings on Alpine) by excluding Windows package-lock.json from Docker builds.
Configured Docker inter-container networking so the Vite proxy correctly resolves the backend using Docker service names instead of localhost.
Created .dockerignore files to prevent Windows node_modules from being copied into Linux containers, ensuring correct platform binaries.

6. Architectural Cleanliness & Refactoring

Completed target refactoring from arrow structures to named function paradigms, providing deep mastery of JavaScript scope contexts.
Collaborated with AI tools to write clean, comment-free code and document architectural patterns.

Project Structure

Stock-Analyzer/
├── client/                 # React 18 + Vite frontend SPA
│   ├── src/
│   │   ├── components/     # ProtectedRoute, Hero, About
│   │   ├── pages/          # Dashboard, SearchStock, Portfolio, Login, SignUp
│   │   ├── App.jsx         # App routing & navigation
│   │   └── config.js       # Dynamic API base URL configuration
├── server/                 # Node.js + Express backend REST API
│   ├── config/             # MongoDB connection and environment validator
│   ├── controllers/        # Auth, Stock, Portfolio, and AI controllers
│   ├── middleware/         # JWT authentication guard
│   ├── models/             # User and Portfolio Mongoose models
│   ├── routes/             # Express API routes
│   ├── services/           # External stock data APIs and Groq AI service
│   ├── utils/              # In-memory TTL cache utility
│   └── server.js           # Express app entry point
└── docker-compose.yml      # Multi-container orchestration

Name		Name	Last commit message	Last commit date
.github		.github
client		client
server		server
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
Dockerfile		Dockerfile
README.md		README.md
docker-compose.yml		docker-compose.yml
package-lock.json		package-lock.json
package.json		package.json
render.yaml		render.yaml

Navigation Menu

Repository navigation

About

Repository files navigation

Stock Analyzer

System Architecture & Workflow

Core Features

Technical Mechanism Overview

API Documentation

Authentication Endpoints

Stock Data Endpoints

AI Insights Endpoints (JWT Protected)

Portfolio Endpoints (JWT Protected)

Installation & Setup

Prerequisites

Option A: Run with Docker (Recommended)

Option B: Run Locally (Manual)

Backend Configuration

Frontend Configuration

Docker Architecture

Design System & AI Collaboration

Learning Outcomes & Professional Development

1. Advanced State Flow & Component Life Cycle

2. Full-Stack Data Operations & Async Coordination

3. Application Security & Access Control

4. Enterprise-Grade API Design & Resilience

5. Docker & Containerization

6. Architectural Cleanliness & Refactoring

Project Structure

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

Stock Analyzer

System Architecture & Workflow

Core Features

Technical Mechanism Overview

API Documentation

Authentication Endpoints

Stock Data Endpoints

AI Insights Endpoints (JWT Protected)

Portfolio Endpoints (JWT Protected)

Installation & Setup

Prerequisites

Option A: Run with Docker (Recommended)

Option B: Run Locally (Manual)

Backend Configuration

Frontend Configuration

Docker Architecture

Design System & AI Collaboration

Learning Outcomes & Professional Development

1. Advanced State Flow & Component Life Cycle

2. Full-Stack Data Operations & Async Coordination

3. Application Security & Access Control

4. Enterprise-Grade API Design & Resilience

5. Docker & Containerization

6. Architectural Cleanliness & Refactoring

Project Structure

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages