frontend/README.md

Frontend Client Workspace

The frontend is a single-page React client built with TypeScript, Vite, Tailwind CSS, and lightweight UI components. It renders the trading workspace, manages websocket subscriptions, and displays real-time price trends.

---

Technical Components & Integration Details

1. TradingView Lightweight Charts (StockChart.tsx)

The centerpiece of the UI is the stock chart widget, which utilizes the lightweight-charts library:

• WebSocket Real-Time Streaming: The chart opens a connection to the backend WebSocket server (ws://localhost:8000/api/v1/ws/ticks). As ticks arrive from the Redpanda broker, they are pushed directly to the candlestick series update channel.
• Tick Accumulation: If a tick arrives for the current minute, its price updates the close of the current candle. If a new minute arrives, a new candle is created.
• Historical Data Backfill: When switching tickers, the chart calls the API to download the last 100 historical candles from NeonDB to prevent gaps in chart history.

2. Component Directory Map

• App.tsx: Core routing, layout shell, and global authentication states.
• components/StockChart.tsx: Embeds the main candlestick chart, indicators toggle, and price-scaling canvas handlers.
• components/AIAnalyst.tsx: Interactive side-panel allowing users to query the Gemini ReAct agent loop. It displays reasoning steps, tool calls, and model outputs in real time.
• components/TrendingHub.tsx: A social trading feed displaying strategies and prediction records generated by the background ML models.
• components/WatchlistSidebar.tsx: Sidebar allowing users to add, remove, and manage monitored tickers. Saves state directly to NeonDB.
• components/PriceAlerts.tsx: Threshold settings page where users configure price levels for alerts.
• components/RechargeModal.tsx: A payment interface managing balance credits and subscription upgrades.

---

Production Build & Deploy Verification

Strict TypeScript Constraints

The project runs clean type verification during compilation:

npm run build

Under the hood, this executes tsc -b and vite build. To prevent production crashes:

• Any declared variables, parameters, or import statements that are unused will throw compiler error TS6133 and fail the build.
• Always check that your dependencies are imported correctly and clean up unused code before deploying.

Deployment Configuration

The client is optimized for Vercel deployment:

• vercel.json: Sets up URL routing rules to redirect all page requests to index.html to support React client-side routing.
• Vite Proxy Config: Proxy rules are configured to redirect /api/v1 routes to the backend port during local development.