Data Flow
Relevant source files
The following files were used as context for generating this wiki page:
- client/src/app/quote/[ticker]/page.tsx
- client/src/components/StockChart/index.tsx
- client/src/components/StockSummary/index.tsx
- client/src/components/StockRating/index.tsx
- client/src/app/portal/page.tsx
- client/src/components/Navbar/index.tsx
- client/src/components/TickerChat/index.tsx
- client/src/components/Hero/index.tsx
- client/src/components/NewsSection/index.tsx
The Greenline application employs a client-centric data flow architecture. The Next.js frontend is responsible for fetching, processing, and displaying financial data from a variety of external and internal APIs. This approach allows for a rich, interactive user experience by pulling specialized data directly into the relevant UI components.
Data is sourced from financial data providers like Polygon.io and Financial Modeling Prep for market prices, company details, and ratings. Additionally, it leverages OpenAI for AI-powered features like summarization and conversational chat, and a local Python-based backend for machine learning-based price forecasting. All API keys and interactions are managed on the client side.
Core Data Architecture
The application's data flow is characterized by direct communication between client-side React components and various external/internal API endpoints. There is no central backend data aggregation layer; each component is largely self-contained in its data fetching logic.
This diagram illustrates the high-level data flow, showing how the client application interacts with multiple data sources.
Data Sources
The application relies on several key data providers, each serving a specific purpose.
| API Provider | Purpose | Example Components |
|---|---|---|
| Polygon.io | Primary source for stock prices, aggregates, company details, news, and market status. | StockChart, StockSummary, NewsSection, Navbar, HeroSection |
| Financial Modeling Prep | Provides detailed stock rating analysis and scores. | StockRating |
| OpenAI | Used for natural language processing tasks, including generating summaries and powering the ticker chat. | StockSummary, TickerChat |
| Local ML API | A local backend service that provides machine learning-based price forecasting. | StockChart |
Sources: client/src/components/StockChart/index.tsx:140, client/src/components/StockRating/index.tsx:49, client/src/components/StockSummary/index.tsx:76, client/src/components/TickerChat/index.tsx:61
Component-Level Data Flows
Each component manages its own state and data fetching lifecycle, typically triggered by useEffect hooks.
Stock Chart & Price Forecasting
The StockChart component has a two-stage data flow. First, it fetches historical price data from Polygon.io. Second, upon user request, it sends this historical data to a local machine learning API to receive a price forecast, which is then merged with the historical data for visualization.
This sequence diagram shows the process of fetching historical data and then generating a forecast.
Polygon.io Aggregates Endpoint
The component dynamically constructs the URL for the Polygon.io aggregates endpoint based on the selected time window.
| Parameter | Description | Example Value | Source |
|---|---|---|---|
multiplier | The size of the time window. | 1 or 5 | client/src/components/StockChart/index.tsx:181 |
timespan | The type of time window. | minute or day | client/src/components/StockChart/index.tsx:182 |
from | The start date of the range. | 2023-01-01 | client/src/components/StockChart/index.tsx:180 |
to | The end date of the range. | 2023-12-31 | client/src/components/StockChart/index.tsx:180 |
apiKey | The API key for Polygon.io. | process.env.NEXT_PUBLIC_POLYGON_API_KEY | client/src/components/StockChart/index.tsx:180 |
AI-Generated Stock Summary
The StockSummary component creates a timeline of significant price movements. It first fetches 6 months of daily stock data from Polygon.io. It then identifies days with price changes greater than 2%. For each of these significant events, it makes a call to the OpenAI API to generate a concise, human-readable explanation for the price movement.
This sequence diagram details the flow of data to generate the summary.
Stock Rating Analysis
The StockRating component fetches comprehensive rating data from the Financial Modeling Prep API. The data includes an overall score and recommendation, as well as scores for individual metrics like DCF, ROE, and PE. The component then processes this data to display an overall rating and a breakdown of the underlying metrics.
This diagram shows the simple data retrieval process for stock ratings.
Ticker Search
The Navbar component provides a real-time search functionality for stock tickers. As a user types into the search input, a debounced useEffect hook triggers an API call to the Polygon.io tickers endpoint. The results are then displayed in a dropdown list.
This sequence diagram illustrates the interactive search flow.
Market & News Overview
Pages like the main portal and components like HeroSection and NewsSection fetch general market data from Polygon.io. This includes live market prices for a predefined list of tickers, overall market status (open/closed), and the latest financial news articles.
- Live Markets (
HeroSection): Fetches previous day's close data for a hardcoded list of tickers (SPY,QQQ,BTC, etc.) to display in a scrolling banner. - Market Status (
portal): Fetches the current status of various exchanges and market types (e.g.,nasdaq,crypto).- Sources: client/src/app/portal/page.tsx:81-89
- News (
portal,NewsSection): Fetches a list of recent news articles, either general or ticker-specific.
Key Data Structures
The application uses several TypeScript interfaces to type the data received from APIs.
StockInfo Interface
This interface is used on the [ticker] page to store detailed information about a company.
| Field | Type | Description | Source |
|---|---|---|---|
name | string | The full name of the company. | client/src/app/quote/[ticker]/page.tsx:41 |
description | string | A description of the company's business. | client/src/app/quote/[ticker]/page.tsx:42 |
market_cap | number | The company's market capitalization. | client/src/app/quote/[ticker]/page.tsx:43 |
logo_url | string | URL for the company's logo. | client/src/app/quote/[ticker]/page.tsx:44 |
website | string | The company's official website URL. | client/src/app/quote/[ticker]/page.tsx:45 |
industry | string | The industry the company operates in. | client/src/app/quote/[ticker]/page.tsx:48 |
primary_exchange | string | The primary stock exchange where the ticker is traded. | client/src/app/quote/[ticker]/page.tsx:49 |
Sources: client/src/app/quote/[ticker]/page.tsx:40-50
RatingData Interface
This interface structures the detailed rating information from the Financial Modeling Prep API.
| Field | Type | Description | Source |
|---|---|---|---|
ratingScore | number | The overall rating score (typically 1-5). | client/src/components/StockRating/index.tsx:18 |
ratingRecommendation | string | The overall recommendation (e.g., "Buy", "Sell"). | client/src/components/StockRating/index.tsx:19 |
ratingDetailsDCFScore | number | Score for the Discounted Cash Flow metric. | client/src/components/StockRating/index.tsx:21 |
ratingDetailsROEScore | number | Score for the Return on Equity metric. | client/src/components/StockRating/index.tsx:23 |
ratingDetailsPEScore | number | Score for the Price to Earnings metric. | client/src/components/StockRating/index.tsx:27 |
ratingDetailsPBScore | number | Score for the Price to Book metric. | client/src/components/StockRating/index.tsx:29 |
Sources: client/src/components/StockRating/index.tsx:15-31
Conclusion
The data flow in Greenline is highly decentralized, with individual React components acting as autonomous units that fetch and process data from a suite of specialized APIs. This architecture leverages the strengths of different services—market data from Polygon.io, ratings from Financial Modeling Prep, AI insights from OpenAI, and forecasting from a local ML model—to build a feature-rich financial analysis platform directly on the client. While this increases the number of client-side network requests, it simplifies the overall architecture by removing the need for a complex data aggregation backend.