📈 Premarket Stock Suggester

A modern, AI-powered web application that displays premarket stock suggestions based on news sentiment analysis. Built with Next.js, TypeScript, and shadcn/ui.

✨ Features

• Real-time Stock Analysis: Displays bullish and bearish stock signals based on news sentiment
• High Priority Watchlist: Sortable table showing stocks with highest priority and bias scores
• Market Overview Dashboard: Key statistics about news coverage and stock signals
• Responsive Design: Fully responsive UI that works on all devices
• Dark Mode Ready: Built-in dark mode support with smooth transitions
• Auto-refresh: Automatically fetches new data every 5 minutes
• Clean UI: Trading-dashboard aesthetic with intuitive color coding

🚀 Tech Stack

• Framework: Next.js 15 (App Router)
• Language: TypeScript
• Styling: Tailwind CSS
• UI Components: shadcn/ui
• Data Fetching: TanStack React Query
• HTTP Client: Axios
• Date Formatting: date-fns
• Icons: Lucide React

📦 Installation

1. Clone the repository:

git clone <your-repo-url>cd StockSuggestor

2. Install dependencies:

npm install

3. Configure environment variables:

The API endpoint is already configured in .env.local:

NEXT_PUBLIC_API_URL=https://hwkhkt7ao8.execute-api.us-east-1.amazonaws.com/dev

You can update this to point to a different API endpoint if needed.

🏃 Running the Application

Development Mode

npm run dev

Open http://localhost:3000 in your browser.

Production Build

npm run build
npm start

Linting

npm run lint

📊 API Integration

The application fetches data from the /watchlist endpoint. The API returns data in the following format:

{"statusCode": 200,"headers": {"Content-Type": "application/json","Access-Control-Allow-Origin": "*","Access-Control-Allow-Headers": "Content-Type","Access-Control-Allow-Methods": "GET, POST, OPTIONS"},"body": {"success": true,"data": {"watchlist": [{"stock_symbol": "RELIANCE","direction": "BULLISH"|"BEARISH","priority": "HIGH"|"MEDIUM","bias_score": 3.5,"reason": "Strong earnings report and positive market sentiment","news_count": 15,"sector": "Finance","latest_news_datetime": "2024-01-18T09:30:00","date": "2024-01-18"}],"bullish_stocks": [...],"bearish_stocks": [...]},"metadata": {"generated_at": "2024-01-18T09:30:00","total_news_fetched": 150,"total_analyzed": 145,"bullish_count": 25,"bearish_count": 18,"watchlist_size": 10}}}

The application automatically normalizes the API response data to a UI-friendly format.

🎨 Components

Core Components

• StatsCard: Displays key metrics with icons and trends
• StockTable: Sortable table for watchlist stocks
• StockCard: Individual stock card with expandable analysis
• PriorityBadge: Visual indicator for stock priority
• DirectionBadge: Bullish/Bearish indicator with icons
• BiasScoreIndicator: Color-coded bias score display
• LoadingSkeleton: Loading state UI
• ErrorState: Error handling with retry functionality
• EmptyState: Empty data state messaging

Component Features

• Auto-sorting: Watchlist sorted by priority (HIGH → MEDIUM) then bias score
• Truncation: Long reasons truncated with "Read more" accordion
• Time Formatting: Automatic date/time formatting to IST
• Visual Signals: Green for bullish, red for bearish
• High Conviction Badge: Shown when bullish bias_score > 3
• High Risk Badge: Shown for HIGH priority bearish stocks

🎯 Project Structure

StockSuggestor/
├── app/
│ ├── layout.tsx # Root layout with providers
│ ├── page.tsx # Main dashboard page
│ └── globals.css # Global styles and themes
├── components/
│ ├── providers/
│ │ └── query-provider.tsx
│ └── ui/
│ ├── badge.tsx
│ ├── bias-score-indicator.tsx
│ ├── button.tsx
│ ├── card.tsx
│ ├── direction-badge.tsx
│ ├── empty-state.tsx
│ ├── error-state.tsx
│ ├── loading-skeleton.tsx
│ ├── priority-badge.tsx
│ ├── stats-card.tsx
│ ├── stock-card.tsx
│ └── stock-table.tsx
├── hooks/
│ └── usePremarketData.ts # React Query hook
├── lib/
│ ├── api.ts # API client
│ └── utils.ts # Utility functions
├── types/
│ └── api.ts # TypeScript types
└── .env.local # Environment variables

🔧 Configuration

React Query Settings

The application uses the following React Query configuration:

• Refetch Interval: 5 minutes
• Retry Attempts: 1
• Stale Time: 5 minutes
• GC Time: 10 minutes

Modify these settings in hooks/usePremarketData.ts.

API Endpoint

Update the API base URL in .env.local:

NEXT_PUBLIC_API_URL=https://your-api-domain.com

🌙 Dark Mode

The application supports dark mode out of the box. Users can toggle dark mode using their system preferences. All components are styled with dark mode variants.

📱 Responsive Design

The application is fully responsive with breakpoints:

• Mobile: Single column layout
• Tablet (md): 2-column grid for cards
• Desktop (lg): 3-4 column grid for cards

⚡ Performance

• Lighthouse Score: Target > 90
• First Contentful Paint: < 2s
• Bundle Optimization: Tree-shaking and code splitting
• Image Optimization: Next.js automatic image optimization

🔮 Future Enhancements

• Sector filtering
• Auto-refresh toggle control
• Historical date selector
• TradingView chart embeds
• Saved watchlists
• Telegram/WhatsApp alerts
• User authentication
• Custom notifications

📄 License

This project is licensed under the MIT License.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

🐛 Issues

If you encounter any issues, please create an issue on GitHub.

---

Built with ❤️ using Next.js and shadcn/ui