PROJECT OVERVIEW:
The application, named 'Piyasa Gözcüsü' (Market Watcher), aims to bring transparency to financial markets by detecting and alerting users about suspicious trading activities and speculative movements. The core problem it solves is the lack of real-time, actionable intelligence regarding unusual market behavior that often precedes significant price shifts, as highlighted by events like the mystery jump in oil trading mentioned in the Hacker News post. The value proposition is to empower investors, analysts, and traders with timely information to make more informed decisions, avoid potential manipulations, and capitalize on emerging market trends.
TECH STACK:
- Frontend: React.js (with functional components and hooks)
- Styling: Tailwind CSS for rapid UI development and a consistent design system.
- State Management: Zustand or Redux Toolkit for efficient global state management.
- Routing: React Router DOM for navigation.
- Data Fetching: Axios or Fetch API for API requests.
- Real-time Data: WebSockets (e.g., Socket.IO client) for live market data streams.
- Charting: Chart.js or Recharts for data visualization.
- UI Components: Headless UI for accessible and unstyled components.
- Deployment: Vercel or Netlify for seamless CI/CD and hosting.
CORE FEATURES:
1. **Real-time Market Data Feed:**
* **User Flow:** Upon login, the user sees a dashboard populated with market data for selected assets (stocks, commodities, crypto). Data updates in real-time without requiring manual refresh.
* **Details:** Fetches data via WebSockets or frequent polling from financial data providers (e.g., Alpha Vantage, CoinGecko API, or a custom backend). Displays price, volume, percentage change, and basic indicators.
2. **Anomaly Detection Alerts:**
* **User Flow:** The system continuously monitors incoming data for significant deviations from normal patterns (e.g., sudden spike in volume with minimal price change, unusually large trades, price movements ahead of major news).
* **Details:** Pre-defined or user-configurable thresholds for volume spikes, price volatility, and trade size anomalies. When an anomaly is detected, a notification pops up on the dashboard and optionally via browser/email notifications.
3. **News & Social Media Sentiment Analysis Integration:**
* **User Flow:** Users can see sentiment scores and relevant headlines related to specific assets or market events. The system correlates news release times with trading activity.
* **Details:** Integrates with news APIs (e.g., NewsAPI) and potentially social media APIs (e.g., Twitter API) to fetch relevant information. Applies sentiment analysis (positive, negative, neutral) to news and social media mentions.
4. **Anomaly Report & Analysis Screen:**
* **User Flow:** Clicking on an alert or an asset takes the user to a detailed view. This screen shows historical data, the specific anomaly event, related news, and sentiment analysis results.
* **Details:** Visualizations include price/volume charts highlighting the anomalous period, a timeline of related news/events, and sentiment trend graphs.
5. **Customizable Watchlist:**
* **User Flow:** Users can add/remove assets to their personal watchlist. The dashboard prioritizes and displays data for these assets.
* **Details:** Uses local storage or a backend to persist user preferences. Allows searching and filtering of available assets.
UI/UX DESIGN:
- **Layout:** Single Page Application (SPA) structure. Main dashboard view with a sidebar for navigation (Watchlist, Alerts, Settings, Analytics). Top navigation bar for search and user profile.
- **Color Palette:** Professional and clean. Primary colors: Dark blue/charcoal for backgrounds, white/light gray for text, accent colors (e.g., green for positive, red for negative, yellow/orange for alerts) used sparingly.
- **Typography:** Sans-serif fonts (e.g., Inter, Roboto) for readability. Clear hierarchy using font weights and sizes.
- **Responsiveness:** Mobile-first approach. Fully responsive design adapting to desktop, tablet, and mobile screen sizes using Tailwind CSS's responsive modifiers.
- **Components:** Clean, intuitive interface. Focus on data visualization and clear alert presentation. Minimalistic design to avoid clutter.
COMPONENT BREAKDOWN:
- `App.js`: Main application component, sets up routing and global layout.
- `Dashboard.js`: Displays the main overview, including watchlist summary and recent alerts.
- Props: `userData` (user preferences), `marketData` (live feed).
- `Watchlist.js`: Renders the user's customizable list of assets.
- Props: `watchlistItems`, `onRemoveItem`, `onAddItem`.
- `AssetCard.js`: Displays summary information for a single asset in the watchlist.
- Props: `assetData` (price, change, volume), `assetName`, `symbol`.
- `AlertsFeed.js`: Lists recent detected anomalies.
- Props: `alerts` (array of anomaly objects).
- `AlertItem.js`: Displays a single alert.
- Props: `alertDetails` (timestamp, type, asset, severity).
- `AnalyticsChart.js`: Reusable charting component.
- Props: `chartData`, `chartOptions`, `chartType`.
- `NewsFeed.js`: Displays relevant news articles.
- Props: `newsItems`.
- `SentimentIndicator.js`: Shows sentiment score (e.g., gauge or color-coded text).
- Props: `sentimentScore`.
- `SearchBar.js`: For searching assets.
- Props: `onSearch`.
- `Notification.js`: Handles displaying transient notifications.
- Props: `message`, `type`, `isVisible`.
DATA MODEL:
- **State Structure (Example using Zustand):**
```javascript
{
user: { profile: {...}, preferences: { watchlist: [], alertThresholds: {} } },
marketData: {
'AAPL': { price: 170.50, change: 1.2, volume: 5000000, timestamp: 1678886400 },
'CL=F': { price: 80.20, change: -0.5, volume: 150000, timestamp: 1678886400 },
// ... more assets
},
alerts: [
{ id: 'a1', timestamp: 1678886000, type: 'VOLUME_SPIKE', asset: 'TSLA', details: 'Volume 3x avg' },
// ... more alerts
],
news: {
'AAPL': [ { title: '...', source: '...', publishedAt: '...', sentiment: 'positive' } ],
// ...
},
loadingStates: { marketData: false, news: false },
error: null
}
```
- **Mock Data Formats:**
- `marketData`: `{ symbol: string, price: number, change: number, volume: number, timestamp: number }`
- `alert`: `{ id: string, timestamp: number, type: 'VOLUME_SPIKE' | 'PRICE_VOLATILITY' | 'UNUSUAL_TRADE', asset: string, details: string, severity: 'low' | 'medium' | 'high' }`
- `newsItem`: `{ title: string, source: string, url: string, publishedAt: string, sentiment: 'positive' | 'negative' | 'neutral' }`
ANIMATIONS & INTERACTIONS:
- **Data Updates:** Subtle flashing or color change on price updates to indicate change.
- **Alerts:** Smooth slide-in/fade-in animation for new alerts in the feed. A pulsating effect for critical alerts.
- **Hover Effects:** Subtle background color changes or slight scale-up on interactive elements like buttons and list items.
- **Transitions:** Smooth transitions between different chart views or when filtering data.
- **Loading States:** Skeleton loaders or spinners while fetching data. Disabled states for buttons during submission.
- **Micro-interactions:** Visual feedback on adding/removing items from the watchlist.
EDGE CASES:
- **Empty States:** Display user-friendly messages when the watchlist is empty, no alerts have triggered, or no news is available for an asset.
- **Error Handling:** Graceful error handling for API failures (e.g., display error message, retry option). Network connection loss detection.
- **Validation:** Input validation for search fields, settings forms (e.g., alert thresholds).
- **Accessibility (a11y):** Use semantic HTML, ARIA attributes where necessary, keyboard navigation support, sufficient color contrast.
- **Data Gaps:** Handle missing data points in real-time feeds gracefully.
- **Timezones:** Ensure consistent handling of timestamps and display times appropriate to the user's locale.
SAMPLE DATA:
1. **Asset Data (AAPL):** `{ "symbol": "AAPL", "price": 175.30, "change": 1.85, "volume": 7500000, "timestamp": 1678890000 }`
2. **Asset Data (BTC-USD):** `{ "symbol": "BTC-USD", "price": 28500.50, "change": -150.75, "volume": 50000, "timestamp": 1678890005 }`
3. **Anomaly Alert (Volume Spike):** `{ "id": "a101", "timestamp": 1678889500, "type": "VOLUME_SPIKE", "asset": "NVDA", "details": "Volume surged 5x above 1-hour average during pre-market", "severity": "medium" }`
4. **Anomaly Alert (Price Volatility):** `{ "id": "a102", "timestamp": 1678889600, "type": "PRICE_VOLATILITY", "asset": "CL=F", "details": "Price dropped 3% in 5 minutes on low news volume", "severity": "high" }`
5. **News Item (Positive):** `{ "title": "Analyst Upgrades TechCorp Stock on Strong Earnings Forecast", "source": "Bloomberg", "url": "http://example.com/news/techcorp_upgrade", "publishedAt": "2023-03-15T10:30:00Z", "sentiment": "positive" }`
6. **News Item (Negative):** `{ "title": "Regulatory Scrutiny Intensifies for BioPharma Inc.", "source": "Reuters", "url": "http://example.com/news/biopharma_scrutiny", "publishedAt": "2023-03-15T11:00:00Z", "sentiment": "negative" }`
7. **Watchlist Item:** `{ "symbol": "GOOGL", "name": "Alphabet Inc.", "currentPrice": 105.10, "dayChange": 0.90 }`
8. **User Preferences:** `{ "watchlist": ["AAPL", "MSFT", "GOOGL"], "alertThresholds": { "VOLUME_SPIKE": 2.5, "PRICE_VOLATILITY": 0.05 }, "emailNotifications": true }`
9. **Sentiment Data:** `{ "asset": "TSLA", "timestamps": [1678880000, 1678883000, 1678886000], "scores": [0.6, -0.2, 0.4] }`
10. **Empty Alerts State:** `[]`
11. **Empty News State:** `[]`
DEPLOYMENT NOTES:
- **Build:** Use `create-react-app` build command or Next.js build. Ensure it's optimized for production (`npm run build`).
- **Environment Variables:** Store API keys (financial data, news API), WebSocket endpoints, and other sensitive information in environment variables (e.g., `.env` file). Access them via `process.env.REACT_APP_VARIABLE_NAME`.
- **Performance Optimizations:** Code splitting with React.lazy and Suspense. Memoization with `React.memo`, `useMemo`, `useCallback`. Optimize image loading. Bundle analysis to identify and reduce package sizes. Efficient state management to prevent unnecessary re-renders.
- **HTTPS:** Ensure the application is served over HTTPS.
- **CORS:** Configure backend or proxy server to handle Cross-Origin Resource Sharing if frontend and backend are on different domains.
- **CDN:** Utilize a Content Delivery Network for serving static assets to improve load times globally.