docs: create professional and detailed README files for all subfolders

alembic/README.md

@@ -0,0 +1,48 @@
+# Database Migrations (Alembic)
+
+This directory contains the database migration scripts managed by Alembic. Alembic handles automatic schema updates, tracking revisions, and syncing database tables with SQLAlchemy models.
+
+---
+
+## Migration Commands Reference
+
+### 1. Run Pending Migrations
+To bring your local database (PostgreSQL/NeonDB) up to date with the latest schema changes:
+```bash
+uv run alembic upgrade head
+```
+
+### 2. Generate a New Migration
+To create a new migration after editing SQLAlchemy models in `backend/app/database/models.py`:
+```bash
+uv run alembic revision --autogenerate -m "describe your changes"
+```
+
+### 3. Revert Migrations
+To roll back the last applied migration:
+```bash
+uv run alembic downgrade -1
+```
+
+---
+
+## Database Schema Evolution
+
+The database schema has evolved through the following sequential revisions located in the `versions/` folder:
+
+1. **Initial Schema (`3d7629451f7d_initial_schema.py`)**
+   - Creates the core tables: `users` (credentials and subscription states), `watchlists` (user ticker lists), and `stock_history` (OHLCV candles).
+2. **User Verification (`99690d55ee16_add_user_verification_columns.py`)**
+   - Appends email verification tracking, registration verification codes, and expiration timestamps to the `users` table.
+3. **Subscriptions & Message Limits (`bbdbf37359be_add_subscription_and_message_limit_.py`)**
+   - Adds monthly credit bounds, API request trackers, and usage counters to enforce tiered subscription levels.
+4. **Strategy Execution Logs (`887a33df9c3e_add_strategy_logs_table.py`)**
+   - Creates the `strategy_logs` table to store quantitative backtesting parameters, accuracy scores, and performance logs.
+5. **Saved Strategy Configurations (`1ffb20394fc4_add_saved_strategies.py`)**
+   - Creates the `saved_strategies` table, allowing users to save and load strategy setups.
+6. **Model Predictions Tracking (`31f4439fab74_add_prediction_logs_table.py`)**
+   - Creates the `prediction_logs` table to log probability outputs, actual outcomes, and model scores from the specialized ONNX models.
+7. **Asset Category Fields (`ea96300d7e57_add_asset_class_columns.py`)**
+   - Adds category indicators (e.g. tech, crypto, index) to refine indicator logic per asset class.
+8. **Threshold Alerts (`15639881888f_add_alert_trigger_columns.py`)**
+   - Appends trigger states to the price alerts table to track when a stock crosses user-specified price bounds.

backend/README.md

@@ -0,0 +1,90 @@
+# Backend Service Layer
+
+The Backend is a high-performance FastAPI service designed to orchestrate the machine learning model pipeline, execute the Gemini ReAct agent loop, manage GraphQL subscriptions, handle HTTP endpoints, and process background Celery tasks.
+
+---
+
+## Architecture & Service Directory
+
+### 1. ONNX Model Hub & Dynamic Hot-Reloading
+Upon service startup (`startup_event` in `backend/app/main.py`), the backend automatically connects to Hugging Face Hub via `hf_hub_download` to pull specialized machine learning models:
+- `model_tech.onnx` (for technology stocks)
+- `model_crypto.onnx` (for cryptocurrency assets)
+- `model_index.onnx` (for broad market indices)
+
+If downloading fails, the server falls back to a general `model.onnx` file stored locally.
+
+#### Hot-Reloading Engine:
+To support model retraining without system downtime, the function `get_onnx_session_for_type` monitors the model files. When a retraining task saves a new model file, the system detects the changed modification time (`os.path.getmtime`), terminates the old session, and hot-reloads the new `ort.InferenceSession` in-memory.
+
+---
+
+### 2. Gemini ReAct Agent Loop
+The core analytical capabilities of QuantIQ are powered by the Gemini GenAI SDK (`gemini-2.5-flash`), running a reasoning-action loop.
+
+#### Synchronous Tool closures:
+The Gemini automatic function calling API executes tools synchronously. However, the database operations inside our FastAPI application are asynchronous. To solve this, the agent loop uses `asyncio.run_coroutine_threadsafe` and closures to safely schedule async queries back onto the main event loop from inside the synchronous tool calls.
+
+#### Tool Ecosystem:
+- `get_user_watchlist`: Retrieves the active ticker watchlist for the logged-in user.
+- `get_stock_history_and_indicators`: Extracts recent price candles and calculates technical indicator values.
+- `create_alert_threshold`: Allows the model to programmatically set alert boundaries.
+- `trigger_model_prediction`: Evaluates the specialized ONNX model predictions.
+
+---
+
+### 3. Mathematical Indicator Formulas
+
+The backend computes technical indicators over a 60-day historical window. The exact formulas are detailed below:
+
+#### Volatility Target and Stop-Loss Levels (ATR-14)
+To calculate risk-managed boundaries:
+1. Compute the True Range (TR) for each candle:
+   $$\text{TR} = \max(\text{High} - \text{Low}, |\text{High} - \text{Close}_{\text{prev}}|, |\text{Low} - \text{Close}_{\text{prev}}|)$$
+2. Compute the 14-period Average True Range (ATR) using Wilder's Smoothing:
+   $$\text{ATR}_t = \frac{\text{ATR}_{t-1} \times 13 + \text{TR}_t}{14}$$
+3. Set the target and stop-loss boundaries based on the signal action (with a default multiplier of 1.5):
+   - **BUY**: 
+     $$\text{Stop Loss} = \text{Close} - (1.5 \times \text{ATR})$$
+     $$\text{Target Price} = \text{Close} + (3.0 \times \text{ATR})$$
+   - **SELL**:
+     $$\text{Stop Loss} = \text{Close} + (1.5 \times \text{ATR})$$
+     $$\text{Target Price} = \text{Close} - (3.0 \times \text{ATR})$$
+
+If the asset history has fewer than 14 days, the system falls back to asset-class default percentages:
+- **Crypto**: Target = 8%, Stop = 4%
+- **Indices**: Target = 1.5%, Stop = 0.75%
+- **Stocks (Tech/General)**: Target = 4%, Stop = 2%
+
+#### Relative Strength Index (RSI-14)
+Computes momentum boundaries using upward and downward price changes over 14 candles:
+$$\text{RS} = \frac{\text{EMA}(\text{Gain}, 14)}{\text{EMA}(\text{Loss}, 14)}$$
+$$\text{RSI} = 100 - \left(\frac{100}{1 + \text{RS}}\right)$$
+
+#### MACD (Moving Average Convergence Divergence)
+Measures trend-following momentum:
+$$\text{MACD Line} = \text{EMA}(\text{Close}, 12) - \text{EMA}(\text{Close}, 26)$$
+$$\text{Signal Line} = \text{EMA}(\text{MACD Line}, 9)$$
+$$\text{Histogram} = \text{MACD Line} - \text{Signal Line}$$
+
+---
+
+### 4. Celery Tasks & Redis Logical Separation
+Redis serves as both our Celery task broker and backend database cache. To prevent packet collisions and memory corruption, the databases are logically isolated:
+- **Broker Channel**: Celery occupies Redis Logical Database 0 (`redis://localhost:6379/0`).
+- **Cache Channel**: Technical indicators caching, yfinance hourly caching, and ATR calculations occupy Redis Logical Database 1 (`redis://localhost:6379/1`).
+
+---
+
+### 5. Strawberry GraphQL Integration
+The client connects to a Strawberry-powered GraphQL router mounted at `/graphql`.
+- **JWT Authorization Parser**: On each request, the custom `get_graphql_context` dependency extracts the HTTP `Authorization: Bearer <token>` header, decodes the JWT signature, extracts the user ID UUID, and fetches the user ORM object to inject it directly into the execution context.
+- **Database Context**: Attaches the active `AsyncSession` to the GraphQL context, ensuring database queries run within safe transaction boundaries.
+
+---
+
+### 6. Prometheus Metrics Instrumentation
+The backend uses `prometheus-fastapi-instrumentator` to export operational metrics.
+- Enpoints metrics are published on the `/metrics` path.
+- The route is protected using HTTP Basic Authentication (`admin` / `admin`).
+- Tracks API latency, HTTP response codes, active WebSocket counts, Gemini token expenditures, and agent reasoning steps.

frontend/README.md

@@ -1,32 +1,41 @@
-# React + TypeScript + Vite
+# Frontend Client Workspace
 
-This template provides a minimal setup to get React working in Vite with HMR and some Oxlint rules.
+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.
 
-Currently, two official plugins are available:
+---
 
-- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Oxc](https://oxc.rs)
-- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/)
+## Technical Components & Integration Details
 
-## React Compiler
+### 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.
 
-The React Compiler is not enabled on this template because of its impact on dev & build performances. To add it, see [this documentation](https://react.dev/learn/react-compiler/installation).
+### 2. Component Directory Map
 
-## Expanding the Oxlint configuration
+- **`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.
 
-If you are developing a production application, we recommend enabling type-aware lint rules by installing `oxlint-tsgolint` and editing `.oxlintrc.json`:
+---
 
-```json
-{
-  "$schema": "./node_modules/oxlint/configuration_schema.json",
-  "plugins": ["react", "typescript", "oxc"],
-  "options": {
-    "typeAware": true
-  },
-  "rules": {
-    "react/rules-of-hooks": "error",
-    "react/only-export-components": ["warn", { "allowConstantExport": true }]
-  }
-}
-```
+## Production Build & Deploy Verification
 
-See the [Oxlint rules documentation](https://oxc.rs/docs/guide/usage/linter/rules) for the full list of rules and categories.
+### Strict TypeScript Constraints
+The project runs clean type verification during compilation:
+```bash
+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.

worker/README.md

@@ -0,0 +1,53 @@
+# Ingestion Worker
+
+The Ingestion Worker is a standalone service responsible for real-time asset price tracking, data streaming, and database candle aggregation. It operates on a continuous async loop to fetch ticker ticks and publish them to a message broker.
+
+---
+
+## Technical Architecture
+
+### 1. Multi-Threaded yfinance Ingestion
+The Yahoo Finance (`yfinance`) library runs synchronous blocking network calls when querying tickers. To prevent blocking the main asyncio event loop, the worker runs all `fast_info` metrics retrievals inside a thread pool executor using `loop.run_in_executor(None, ...)` inside `get_latest_stock_data`.
+
+```python
+loop = asyncio.get_event_loop()
+yf_ticker = yf.Ticker(ticker)
+info = await loop.run_in_executor(None, lambda: yf_ticker.fast_info)
+```
+
+This ensures high concurrency and prevents websocket read latency on the frontend during polling cycles.
+
+### 2. Exponential Rate-Limit Cooldown
+To bypass strict IP rate-limiting blocks from third-party APIs:
+- If a `429 Too Many Requests` or rate-limiting exception string is caught during execution, the worker sets a global cooldown timestamp (`COOLDOWN_UNTIL`).
+- The rate-limiting cooldown backoff starts at 60 seconds.
+- On consecutive rate-limit violations, the backoff doubles exponentially up to a maximum limit of 15 minutes (900 seconds).
+- Once the cooldown timer expires, the backoff resets to 60 seconds on the first successful fetch.
+
+### 3. Redpanda Event Streaming
+All successfully fetched ticker events are formatted as JSON payloads containing the ticker name, latest price, cumulative volume, and UTC timestamp, then published to the Redpanda Cloud topic `stock-ticks`.
+- The worker uses the asynchronous `aiokafka` client (`AIOKafkaProducer`).
+- Payload serialization is handled using a native UTF-8 JSON encoder.
+
+### 4. 1-Minute Candle Aggregation
+In addition to streaming, the worker buffers price and volume data points in memory to calculate 1-minute OHLCV candles:
+- **Open**: The first price point of the minute.
+- **High**: The maximum price point recorded in the minute.
+- **Low**: The minimum price point recorded in the minute.
+- **Close**: The last price point of the minute.
+- **Volume**: The difference between the maximum and minimum cumulative volumes recorded in that minute.
+
+#### Closed-Market Skipping Rules:
+To avoid bloat in the database (e.g. NeonDB storage limitations), the worker filters out flat, inactive closed-market candles (where open equals high, low, and close, and the volume difference is zero).
+- Non-crypto tickers (stocks and indices) will not be committed to the database during closed hours.
+- Crypto tickers (e.g. ending in `-USD` or `-BTC`) bypass this rule and are saved 24/7 since cryptocurrency markets never close.
+
+---
+
+## Service Operations
+
+### Core Main Loop
+The worker queries the database dynamically on each cycle to fetch active tickers from users' watchlists (`select(Watchlist.ticker).distinct()`). This guarantees that:
+- The worker only polls tickers that users are actively monitoring.
+- Adding a ticker to a watchlist dynamically begins polling it without requiring a worker restart.
+- Polling calls are staggered with a 1.5-second sleep interval to spread load evenly.