Feature: User Portal
Relevant source files
The following files were used as context for generating this wiki page:The User Portal is the main dashboard of the Greenline application, accessible via the "Access Portal" link on the landing page. It serves as a central hub for users to access real-time market information, financial news, and detailed analytics on specific stocks. Built using Next.js and React, the portal is designed as a single-page application experience that dynamically fetches data from various financial APIs, primarily Polygon.io.
From the portal's main page, users can view a high-level market overview and browse the latest news. The integrated navigation bar allows for searching and navigating to detailed quote pages for individual stock tickers, such as the Stock Detail Page, to perform in-depth analysis.
Sources: client/src/app/portal/page.tsx, client/src/components/Hero/index.tsx:191-202
Architecture and Core Components
The User Portal is composed of several key React components that work together to provide a comprehensive financial dashboard. The main entry point is the /portal page, which aggregates data and renders various informational sections.
The following diagram illustrates the high-level component structure of the portal and its relation to the detailed stock page.
This diagram shows the main components of the User Portal and the Stock Detail Page.
Sources: client/src/app/portal/page.tsx:106-258, client/src/app/quote/[ticker]/page.tsx:132-212
Key Components
| Component | File Path | Description |
|---|---|---|
| Portal Page | client/src/app/portal/page.tsx | The main page for the market overview. Fetches and displays market status and general news. |
| Navbar | client/src/components/Navbar/index.tsx | Provides global navigation and a ticker search bar that allows users to find and navigate to specific stock quote pages. |
| Market Status | client/src/app/portal/page.tsx | A set of cards displaying the real-time status (open/closed) of major exchanges, currencies, and market indices. |
| News Feed | client/src/app/portal/page.tsx | A list of the latest financial news articles, fetched from the Polygon API. |
| Stock Detail Page | client/src/app/quote/[ticker]/page.tsx | A dynamic page that provides an in-depth view of a single stock ticker, aggregating multiple data components. |
Data Fetching
The portal relies heavily on client-side data fetching from external APIs within useEffect hooks. The primary data source is the Polygon.io API, used for market status, news, and stock data. Other APIs like OpenAI and Financial Modeling Prep are used for specialized analytics.
Data Sources
| API Provider | Usage | Endpoint Example | Source File |
|---|---|---|---|
| Polygon.io | Market Status | https://api.polygon.io/v1/marketstatus/now | client/src/app/portal/page.tsx:71 |
| Polygon.io | News Articles | https://api.polygon.io/v2/reference/news | client/src/app/portal/page.tsx:55 |
| Polygon.io | Ticker Search | https://api.polygon.io/v3/reference/tickers | client/src/components/Navbar/index.tsx:50 |
| Polygon.io | Stock Details | https://api.polygon.io/v3/reference/tickers/{ticker} | client/src/app/quote/[ticker]/page.tsx:68 |
| OpenAI | AI Summary | chat.completions.create | client/src/components/StockSummary/index.tsx:84 |
| Financial Modeling Prep | Stock Rating | https://financialmodelingprep.com/api/v3/rating/{ticker} | client/src/components/StockRating/index.tsx:48 |
General Data Flow
The typical data fetching flow in a component involves setting loading states, making an API call with an API key from environment variables, and then updating the component's state with the fetched data or an error message.
This diagram shows the client-side data fetching sequence from a React component to an external API.
Sources: client/src/app/portal/page.tsx:49-90, client/src/components/Navbar/index.tsx:44-67
Portal Page (/portal)
The main portal page at /portal provides a "Market Overview". It fetches and displays two main types of information upon loading: the current status of various financial markets and a list of the latest news articles.
Sources: client/src/app/portal/page.tsx
Market Status
The page fetches data from Polygon's /v1/marketstatus/now endpoint to determine if various markets are open or closed. This information is displayed in a series of cards.
The MarketStatus data structure is as follows:
| Field | Type | Description |
|---|---|---|
market | string | Overall market status (e.g., "open", "closed"). |
afterHours | boolean | Indicates if after-hours trading is active. |
earlyHours | boolean | Indicates if pre-market trading is active. |
exchanges | object | Status of major exchanges like nasdaq, nyse. |
currencies | object | Status of crypto and fx (forex) markets. |
indicesGroups | object | Status of various indices groups. |
A custom StatusBadge component is used to visually represent the status with color-coding: green for "open" and red for "closed".
Sources: client/src/app/portal/page.tsx:26-44, 92-103
News Feed
The page also fetches a list of general news articles from Polygon's /v2/reference/news endpoint. Each article is displayed in a card, showing its title, publication date, and a short description. Clicking an article opens the full story in a new tab.
Sources: client/src/app/portal/page.tsx:18-24, 226-257
Navigation and Ticker Search
The Navbar component is present on all portal pages and provides consistent navigation and a powerful ticker search functionality.
Sources: client/src/components/Navbar/index.tsx
Ticker Search Flow
The search bar allows users to find stock tickers. As the user types, a debounced API request (500ms delay) is sent to Polygon's /v3/reference/tickers endpoint. The results are displayed in a dropdown list. Selecting a result navigates the user to the corresponding /quote/[ticker] page.
This diagram illustrates the sequence of events for searching a ticker in the Navbar.
Sources: client/src/components/Navbar/index.tsx:44-67, 29-33
Stock Detail Page (/quote/[ticker])
This dynamic page provides a comprehensive, 360-degree view of a specific stock ticker. It aggregates data from multiple sources and presents it through a collection of specialized components.
Sources: client/src/app/quote/[ticker]/page.tsx
Page Composition
The page is built by composing several independent components, each responsible for a specific piece of information.
This diagram shows the components that make up the Stock Detail Page and the data they fetch.
Sources: client/src/app/quote/[ticker]/page.tsx:132-212
AI-Powered Stock Summary (StockSummary)
The StockSummary component provides an AI-generated analysis of a stock's performance over the last month.
- It fetches 6 months of daily historical stock data from Polygon.
- It identifies "significant changes" where the daily price movement exceeds 2%.
- For each significant change, it calls the OpenAI
gpt-3.5-turbomodel with a prompt asking for a concise explanation of potential market influences. - The results are displayed as an interactive timeline, where each event can be expanded to view the AI-generated description.
This diagram shows the data flow for generating the AI-powered critical summary.
Sources: client/src/components/StockSummary/index.tsx:40-101
Stock Rating Analysis (StockRating)
The StockRating component fetches a comprehensive rating analysis from the financialmodelingprep.com API. It presents an overall score (e.g., 4/5) and a recommendation (e.g., "Buy").
It also provides a breakdown of the score based on several financial metrics:
- DCF (Discounted Cash Flow)
- ROE (Return on Equity)
- ROA (Return on Assets)
- DE (Debt to Equity)
- PE (Price to Earnings)
- PB (Price to Book)
The component visualizes the distribution of buy, hold, and sell recommendations across these metrics using progress bars.
Sources: client/src/components/StockRating/index.tsx:44-63, 142-150
Ticker-Specific News (NewsSection)
Unlike the general news on the portal homepage, the NewsSection component on the stock detail page fetches news articles specifically related to the current ticker by using the ticker query parameter in the API call to Polygon.