Backend Overview
Relevant source files
The following files were used as context for generating this wiki page: - [client/src/app/quote/[ticker]/page.tsx](https://github.com/asixham/greenline/blob/HEAD/client/src/app/quote/%5Bticker%5D/page.tsx) - [client/src/app/portal/page.tsx](https://github.com/asixham/greenline/blob/HEAD/client/src/app/portal/page.tsx) - [client/src/components/StockSummary/index.tsx](https://github.com/asixham/greenline/blob/HEAD/client/src/components/StockSummary/index.tsx) - [client/src/components/TickerChat/index.tsx](https://github.com/asixham/greenline/blob/HEAD/client/src/components/TickerChat/index.tsx) - [client/src/components/StockRating/index.tsx](https://github.com/asixham/greenline/blob/HEAD/client/src/components/StockRating/index.tsx) - [client/src/components/StockChart/index.tsx](https://github.com/asixham/greenline/blob/HEAD/client/src/components/StockChart/index.tsx) - [client/src/components/Navbar/index.tsx](https://github.com/asixham/greenline/blob/HEAD/client/src/components/Navbar/index.tsx) - [client/src/components/NewsSection/index.tsx](https://github.com/asixham/greenline/blob/HEAD/client/src/components/NewsSection/index.tsx)The Greenline application's backend is not a monolithic service but rather a composition of several external, third-party APIs. The client-side Next.js application communicates directly with these services to fetch, process, and display financial data and AI-generated insights. This architecture makes the client responsible for orchestrating API calls and managing state.
This document provides an overview of these external services, their specific endpoints, and how the client-side components integrate with them to deliver the application's features. The primary services used are Polygon.io for market data, OpenAI for AI-powered analysis, and Financial Modeling Prep for stock ratings.
System Architecture
The application follows a client-heavy architecture where the Next.js frontend directly queries external APIs. API keys for these services are stored as environment variables and accessed on the client side.
Sources: client/src/components/Hero/index.tsx:21, client/src/components/StockSummary/index.tsx:68, client/src/components/StockRating/index.tsx:50
High-Level Data Flow
The following diagram illustrates the high-level interaction between the Greenline client and the external APIs it consumes.
This diagram shows how the Next.js client application serves as an orchestrator, fetching data from various specialized external APIs to build the user interface.
Sources: client/src/app/quote/[ticker]/page.tsx, client/src/components/StockSummary/index.tsx, client/src/components/StockRating/index.tsx
External API Integration
The application relies on three main external services.
1. Polygon.io API
Polygon.io is the primary source for all stock market data, including pricing, historical data, news, and company information. The API key is retrieved from process.env.NEXT_PUBLIC_POLYGON_API_KEY.
Sources: client/src/components/Hero/index.tsx:21
The table below summarizes the Polygon.io endpoints used throughout the application.
| Endpoint | Purpose | Used In Component(s) |
|---|---|---|
/v2/aggs/ticker/{ticker}/prev | Fetches the previous day's open, high, low, and close (OHLC). | HeroSection, StockCardMini |
/v2/aggs/ticker/{ticker}/range/... | Fetches aggregate bars for a ticker over a date range. | StockChart, StockSummary, StockCard |
/v3/reference/tickers | Searches for tickers by name or symbol. | Navbar |
/v3/reference/tickers/{ticker} | Fetches detailed information for a specific ticker. | StockPage, StockCardMini |
/v1/marketstatus/now | Gets the current status of the market (open/closed). | Home (portal page) |
/v2/reference/news | Fetches market news, filterable by ticker. | Home (portal page), NewsSection |
/v1/related-companies/{ticker} | Fetches a list of tickers for related companies. | StockPage |
Sources: client/src/components/Hero/index.tsx:24, client/src/components/StockChart/index.tsx:206, client/src/components/Navbar/index.tsx:48, client/src/app/quote/[ticker]/page.tsx:64, client/src/app/portal/page.tsx:78, client/src/components/NewsSection/index.tsx:40, client/src/app/quote/[ticker]/page.tsx:90
2. OpenAI API
The OpenAI API is used to provide AI-powered text generation features. The API key is accessed via process.env.NEXT_PUBLIC_OPENAI_API_KEY and is used directly in the browser, which is explicitly enabled via dangerouslyAllowBrowser: true.
Sources: client/src/components/StockSummary/index.tsx:69, client/src/components/TickerChat/index.tsx:58
Ticker Chat
The TickerChat component implements a conversational AI that allows users to "chat" with a stock ticker. It uses the gpt-4o-mini model.
The following sequence diagram shows the flow of a user sending a message.
This diagram illustrates the real-time, streaming interaction between the user, the chat component, and the OpenAI API.
Sources: client/src/components/TickerChat/index.tsx:49-86
Critical Summary Generation
The StockSummary component uses the gpt-3.5-turbo model to generate concise explanations for significant stock price changes over the last 6 months. It identifies days with price changes greater than 2% and asks the AI to analyze potential reasons.
Sources: client/src/components/StockSummary/index.tsx:55-87
3. Financial Modeling Prep API
This service is used to fetch detailed rating analysis for a stock.
| Endpoint | Purpose | Used In Component(s) |
|---|---|---|
/api/v3/rating/{ticker} | Retrieves a comprehensive rating including an overall score and breakdown by metrics like DCF, ROE, etc. | StockRating |
The API call in StockRating uses a hardcoded API key.
// client/src/components/StockRating/index.tsx:49-51
const response = await fetch(
`https://financialmodelingprep.com/api/v3/rating/${ticker}?apikey=z00pmv1R647g3wa404anMdADxAoIxzmP`
);
Sources: client/src/components/StockRating/index.tsx:48-52
Core Feature Data Flows
Stock Quote Page (/quote/[ticker])
This page is a central hub that aggregates data from numerous components, each responsible for fetching data from different APIs.
The data loading process for the quote page is as follows:
This diagram shows how the main quote page initiates fetches for basic stock details and then child components perform their own data fetching from various APIs.