Directory Structure (Client)

Relevant source files

The following files were used as context for generating this wiki page:

• client/package.json
• client/tailwind.config.ts
• client/components.json
• client/src/app/layout.tsx
• client/src/app/globals.css
• client/src/app/page.tsx
• client/src/app/portal/page.tsx
• client/src/app/quote/[ticker]/page.tsx
• client/src/components/Navbar/index.tsx
• client/src/components/Hero/index.tsx
• client/src/components/StockSummary/index.tsx
• client/src/components/StockRating/index.tsx
• client/src/components/TickerChat/index.tsx
• client/src/components/NewsSection/index.tsx
• client/src/components/ui/navigation-menu.tsx

The Greenline client is a modern web application built with Next.js, TypeScript, and Tailwind CSS. It follows a structured, component-based architecture that separates concerns and promotes code reusability. The project leverages the Next.js App Router for file-system-based routing and server-side rendering capabilities.

The structure is organized into logical directories for pages (app), reusable components (components), and utility functions (lib). Styling is managed primarily through Tailwind CSS with a custom theme, and UI components are based on the shadcn/ui library, providing a consistent and maintainable design system. Data is fetched from external services like Polygon.io for market data and OpenAI for AI-driven analysis.

High-Level Directory Overview

The following diagram illustrates the main directories within the client folder.

Key Directories

Directory	Description
src/app/	Contains the application's pages and layouts, following the Next.js App Router convention. Each sub-folder represents a route.
src/components/	Houses all reusable React components. It is further divided into general application components and base UI components under ui/.
src/lib/	Intended for utility functions and helper modules, as indicated by the alias configuration in components.json.

Sources: client/src/app/layout.tsx, client/src/components/Hero/index.tsx, client/components.json:14

Project Configuration

The root client directory contains configuration files that define the project's dependencies, build scripts, and styling rules.

package.json

This file defines project metadata, scripts, and dependencies.

• Scripts: Includes standard Next.js scripts like dev, build, start, and lint.
• Dependencies: The project relies on several key libraries:

Library	Purpose
next	The core React framework for building the application.
react	The JavaScript library for building user interfaces.
tailwindcss	A utility-first CSS framework for styling.
@radix-ui/*	A collection of unstyled, accessible UI primitives.
recharts	A composable charting library.
openai	The official client library for interacting with the OpenAI API.
lucide-react	A library of simply designed icons.

Sources: client/package.json:5-30

tailwind.config.ts

This file configures Tailwind CSS. It defines the application's color palette, fonts, and custom animations. The configuration extends the base theme with custom colors for primary, secondary, accent, and chart-specific colors. It also adds custom animations like spin-slow and marquee.

Sources: client/tailwind.config.ts:5-80

components.json

This file configures shadcn/ui. It specifies the styling (new-york), color theme (zinc), and path aliases for components (@/components), utilities (@/lib/utils), and UI primitives (@/components/ui). This setup standardizes the structure for UI development.

Sources: client/components.json

Application Routing (src/app)

The application uses the Next.js App Router. The file system inside src/app defines the routes.

This diagram shows the root layout wrapping all pages, with global styles applied.

Sources: client/src/app/layout.tsx, client/src/app/page.tsx, client/src/app/portal/page.tsx, client/src/app/quote/[ticker]/page.tsx

Key Pages

• layout.tsx: The root layout that wraps all pages. It sets up the HTML structure, applies global fonts (Open_Sans), and includes the ThemeProvider for light/dark mode management.
  Sources: client/src/app/layout.tsx:1-41
• page.tsx (Home Page): The landing page of the application. It renders the NavbarHome and HeroSection components.
  Sources: client/src/app/page.tsx:1-17
• portal/page.tsx (Market Overview): A dashboard page that displays the current market status and a list of recent news articles. It fetches data from the Polygon.io API for market status and news.
  Sources: client/src/app/portal/page.tsx:1-248
• quote/[ticker]/page.tsx (Stock Detail Page): A dynamic route that displays detailed information for a specific stock ticker. This page is a composition of many smaller components.
  Sources: client/src/app/quote/[ticker]/page.tsx:1-157

Component Architecture (src/components)

Components are the building blocks of the UI. This directory contains both high-level feature components and low-level UI elements.

Component Composition Example: Stock Detail Page

The StockPage (/quote/[ticker]) demonstrates how multiple, single-responsibility components are assembled to create a complex view.

This diagram shows the components that make up the stock detail page.
Sources: client/src/app/quote/[ticker]/page.tsx:7-19, 126-151

Data-Fetching Components

Many components are responsible for fetching their own data from external APIs.

Navbar Search

The Navbar component includes a search bar that fetches ticker suggestions from the Polygon.io API as the user types.

This sequence shows the flow of searching for a stock ticker in the navigation bar.
Sources: client/src/components/Navbar/index.tsx:37-64

AI-Powered Components

The application integrates with the OpenAI API to provide AI-driven insights.

• TickerChat: Provides a conversational interface where users can "chat" with a stock ticker. It uses the gpt-4o-mini model to generate responses from the perspective of the ticker.
  Sources: client/src/components/TickerChat/index.tsx:50-77
• StockSummary: Fetches historical stock data from Polygon.io, identifies significant price changes, and then uses the OpenAI API (gpt-3.5-turbo) to generate a concise description of potential reasons for each change.
  Sources: client/src/components/StockSummary/index.tsx:66-93

UI Components (src/components/ui)

This directory contains generic, reusable UI components based on shadcn/ui, such as navigation-menu.tsx, card.tsx, and button.tsx. These components are styled with Tailwind CSS and are built on top of Radix UI primitives for accessibility.

Sources: client/src/components/ui/navigation-menu.tsx, client/components.json:15

Conclusion

The Greenline client application is architected using a modern, scalable stack centered around Next.js and a component-based design. The clear separation of concerns—routing in src/app, reusable UI in src/components, and configuration at the root—creates a maintainable and developer-friendly codebase. The direct integration of external data sources like Polygon.io and AI services like OpenAI within individual components allows for modular, self-contained features that are easy to manage and extend.