Architecture Overview
Relevant source files
The following files were used as context for generating this wiki page:- client/package.json
- client/src/app/layout.tsx
- client/src/app/quote/[ticker]/page.tsx
- client/src/app/portal/page.tsx
- client/src/components/StockSummary/index.tsx
- client/src/components/StockRating/index.tsx
- client/src/components/TickerChat/index.tsx
- client/tailwind.config.ts
- client/src/components/Hero/index.tsx
- client/src/components/Navbar/index.tsx
The Greenline application is a modern, client-rendered web platform designed for advanced market intelligence. It is built using Next.js and leverages a component-based architecture with React. The application's primary function is to aggregate, analyze, and present financial data from multiple third-party APIs, including market data, news, and AI-powered insights.
The architecture is heavily client-focused, with most data fetching and state management handled within React components. It integrates several external services for its core functionality, positioning itself as a sophisticated frontend interface for various data sources. The backend, as represented by the provided files, is non-existent; the client communicates directly with external APIs.
Core Technologies
The client-side application is built on a modern web stack, emphasizing performance, developer experience, and a rich user interface.
Sources: client/package.json, client/src/app/layout.tsx
| Technology / Library | Version | Role |
|---|---|---|
| Next.js | 14.2.9 | The core React framework, providing routing, rendering, and build tooling. The App Router is used. |
| React | ^18 | The UI library for building the component-based user interface. |
| TypeScript | ^5 | Provides static typing for the entire codebase, enhancing code quality and maintainability. |
| Tailwind CSS | ^3.4.1 | A utility-first CSS framework used for styling all components. |
| shadcn/ui | N/A | A collection of reusable UI components built on Radix UI and Tailwind CSS. |
| Recharts | ^2.13.3 | A composable charting library used for rendering stock price charts. |
| OpenAI | ^4.72.0 | Node.js library for interacting with the OpenAI API to generate summaries and power the chat feature. |
| Lucide React | ^0.439.0 | A library of simply designed icons. |
Sources: client/package.json
Application Structure
The project follows the standard Next.js App Router directory structure. Pages are defined within the client/src/app directory, and reusable UI elements are organized into client/src/components.
Sources: client/src/app/page.tsx, client/src/app/portal/page.tsx, client/src/app/quote/[ticker]/page.tsx
Page Routing
The application features several key pages:
/(Home Page): The main landing page, composed of theNavbarHomeandHeroSectioncomponents./portal(Portal Page): A dashboard view showing a market overview and the latest financial news./quote/[ticker](Stock Detail Page): A dynamic route that displays detailed information for a specific stock ticker.
Component Hierarchy
Pages are composed of multiple smaller, specialized components. For example, the Stock Detail page (/quote/[ticker]) assembles various data views into a single cohesive interface.
The following diagram illustrates the component structure of the StockPage.
Data Fetching and External Services
The application operates without a dedicated backend, fetching all data directly from third-party APIs on the client side. This is accomplished using the fetch API within useEffect hooks in React components marked with "use client".
High-Level Data Flow
The diagram below shows the overall data flow, where the Next.js client acts as an orchestrator, pulling data from various specialized APIs and presenting it to the user.
External API Integration
The application relies on three primary external services:
| API Provider | Purpose | Example Components |
|---|---|---|
| Polygon.io | Provides real-time and historical stock prices, market status, company details, and news articles. | HeroSection, Navbar, portal/page, quote/[ticker]/page, NewsSection |
| OpenAI | Powers AI-driven features, including generating critical event summaries and enabling a conversational chat interface for each stock. | StockSummary, TickerChat |
| Financial Modeling Prep | Supplies detailed stock rating analysis, including an overall score and breakdown by financial metrics. | StockRating |
Sources: client/src/app/portal/page.tsx:43-46, client/src/components/StockSummary/index.tsx:75-83, client/src/components/StockRating/index.tsx:50-53
Page Load Sequence (/quote/[ticker])
When a user navigates to a stock detail page, the StockPage component initiates multiple parallel API calls to populate its child components.
This sequence diagram shows the data fetching process for the stock detail page.
AI-Powered Features
A key architectural aspect is the direct integration of the OpenAI API on the client side to provide unique analytical features.
Sources: client/src/components/StockSummary/index.tsx, client/src/components/TickerChat/index.tsx
Critical Summary Generation
The StockSummary component analyzes historical stock data to identify significant price changes. For each significant event, it calls the OpenAI API (gpt-3.5-turbo) to generate a concise description of potential market influences, which are then displayed in a timeline.
Sources: client/src/components/StockSummary/index.tsx:64-87
Ticker Chat
The TickerChat component provides a conversational AI interface where users can "chat" with a stock ticker. It uses the OpenAI API (gpt-4o-mini) with a system prompt that instructs the model to respond as if it were the ticker itself. The component manages the conversation state and streams responses back to the user.
Sources: client/src/components/TickerChat/index.tsx:21-27, 56-78
Styling and UI
The application's visual identity is managed by Tailwind CSS, with a custom theme and component styles defined across several configuration files.
Sources: client/tailwind.config.ts, client/src/app/globals.css, client/components.json
- Base Styling:
client/src/app/globals.csssets up Tailwind layers and defines root CSS variables for light and dark themes. - Theme Configuration:
client/tailwind.config.tsextends the default Tailwind theme with custom colors (e.g.,#D4FF00), animations (spin-slow,marquee), and border-radius settings. - UI Components: The project uses
shadcn/ui, as indicated bycomponents.jsonand the structure of files inclient/src/components/ui. These are primitive, unstyled components (likeCard,Table,Accordion) that are styled locally with Tailwind CSS.
Conclusion
The Greenline project's architecture is that of a lean, modern frontend application. It offloads all data sourcing and complex computation (like AI analysis) to specialized third-party APIs. This client-heavy approach allows for a rich, interactive user experience built with a popular and well-supported tech stack (Next.js, React, Tailwind CSS). The key architectural decision is the direct client-to-API communication, which simplifies development by removing the need for an intermediary backend but places responsibility for security (API keys) and performance on the client-side implementation.