From a02c287df4fdcf833b26fe1eaf02f7d79fce51c4 Mon Sep 17 00:00:00 2001
From: Meghram Meena <rinku4578914@gmail.com>
Date: Sat, 15 Nov 2025 11:28:00 +0530
Subject: [PATCH] docs: readme updated

---
 README.md                                     | 369 +++++++++++-------
 .../frontend/cauweb/package-lock.json         |   8 +
 2 files changed, 242 insertions(+), 135 deletions(-)

diff --git a/README.md b/README.md
index 363b73ea..96fe4720 100644
--- a/README.md
+++ b/README.md
@@ -1,227 +1,326 @@
-# QuantResearchStarter
+# QuantResearch_Opcode
 
-[![Python Version](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/)
-[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
-[![CI](https://github.com/username/QuantResearchStarter/actions/workflows/ci.yml/badge.svg)](https://github.com/username/QuantResearchStarter/actions)
+check out the [link](https://qrsopcode.netlify.app/)
 
-A modular, open-source quantitative research and backtesting framework built for clarity, reproducibility, and extensibility. Ideal for researchers, students, and engineers building and testing systematic strategies.
+> **QuantResearch_Opcode** — research-grade quantitative strategy starter kit with an interactive React/TypeScript frontend (cauweb), Python backtesting core, and legacy Streamlit dashboards archived under `legacy/streamlit/`.
 
 ---
 
-## Why this project
+## Table of contents
+
+* [Project overview](#project-overview)
+* [What’s included](#whats-included)
+* [Prerequisites](#prerequisites)
+* [Quickstart (dev)](#quickstart-dev)
+
+  * [Run backend (Python)](#run-backend-python)
+  * [Run frontend (cauweb)](#run-frontend-cauweb)
+  * [Run with mock WS / demo mode](#run-with-mock-ws--demo-mode)
+* [Production build & docker](#production-build--docker)
+* [Realtime contract & WS guide](#realtime-contract--ws-guide)
+* [APIs & Data flows](#apis--data-flows)
+* [Testing & CI](#testing--ci)
+* [Streamlit (legacy) status & migration notes](#streamlit-legacy-status--migration-notes)
+* [Developer workflow & conventions](#developer-workflow--conventions)
+* [Contributing](#contributing)
+* [Roadmap / recommended next issues](#roadmap--recommended-next-issues)
+* [License & contact](#license--contact)
 
-QuantResearchStarter aims to provide a clean, well-documented starting point for quantitative research and backtesting. It focuses on:
+---
+
+## Project overview
+
+This repository provides a complete starter environment for research and prototyping in quantitative finance. It consists of:
+
+* A **Python core** for factor computation, backtesting, and research workflows (packaged under `src/quant_research_starter/`).
+* A modern **React + TypeScript frontend** at `src/quant_research_starter/frontend/cauweb/` for interactive dashboards, live visualizations, strategy management and job control.
+* A legacy **Streamlit** UI archived under `legacy/streamlit/` (kept for reference and reproducibility).
+* Tooling to support reproducible experiments, unit tests, linting, and CI automation.
 
-* **Readability**: idiomatic Python, type hints, and small modules you can read and change quickly.
-* **Testability**: deterministic vectorized backtests with unit tests and CI.
-* **Extensibility**: plug-in friendly factor & data adapters so you can try new ideas fast.
+This README explains how to run both components in dev and production, how realtime is wired, and how to extend the system.
 
 ---
 
-## Key features
+## What’s included (high-level)
 
-* **Data management** — download market data or generate synthetic price series for experiments.
-* **Factor library** — example implementations of momentum, value, size, and volatility factors.
-* **Vectorized backtesting engine** — supports transaction costs, slippage, portfolio constraints, and configurable rebalancing frequencies (daily, weekly, monthly).
-* **Risk & performance analytics** — returns, drawdowns, Sharpe, turnover, and other risk metrics.
-* **CLI & scripts** — small tools to generate data, compute factors, and run backtests from the terminal.
-* **Production-ready utilities** — type hints, tests, continuous integration, and documentation scaffolding.
+```
+/ (repo root)
+├─ src/quant_research_starter/
+│  ├─ core/            # Python backtest + factors + utils
+│  ├─ api/             # Python FastAPI or Flask endpoints (if present)
+│  └─ frontend/
+│     └─ cauweb/       # React + TS frontend
+├─ legacy/streamlit/   # archived Streamlit apps (read-only)
+├─ notebooks/          # Demo notebooks and reproducible examples
+├─ tests/              # Unit tests (python) + frontend tests
+├─ .github/            # CI workflows (build, tests, docs)
+└─ pyproject.toml / package.json
+```
 
 ---
 
-## Quick start
+## Prerequisites
 
-### Requirements
+* **Node**: v18.x or later (use nvm to manage) — used by `cauweb` (frontend)
+* **Yarn** or **npm**: prefer `npm ci` for CI reproducibility
+* **Python**: 3.10 / 3.11 (or the version pinned in `pyproject.toml`)
+* Optional: **Docker** for containerized builds
+* Optional: **VS Code** + Remote Containers if using `.devcontainer`
 
-* Python 3.10+
-* pip
+Ensure `NODE_ENV` and Python virtualenv are isolated per project.
 
-### Install locally
+---
 
-```bash
-# Clone the repository
-git clone https://github.com/username/QuantResearchStarter.git
-cd QuantResearchStarter
+## Quickstart (dev)
+
+Follow these steps to run the backend and frontend locally. The instructions assume you're at the repo root.
 
-# Install package in development mode
-pip install -e .
+### 1) Set up Python env & install backend deps: to be updated
 
-# Install development dependencies (tests, linters, docs)
-pip install -e ".[dev]"
+<!-- ```bash
+# create venv (example)
+python -m venv .venv
+source .venv/bin/activate    # Linux / macOS
+.\.venv\Scripts\activate   # Windows CMD
 
-# Optional UI dependencies
-pip install streamlit plotly
+# install
+pip install -U pip
+pip install -e .[dev]
+# or use poetry / pipx if project uses it
 ```
 
-### Quick CLI Usage
+Run any database migrations or data bootstrap steps if the repo documents them (check `src/quant_research_starter/api/README.md`). -->
 
-After installation, you can use the CLI in two ways:
+<!-- ### 2) Start the Python backend (dev server) : to be updated soon
+
+If the backend is FastAPI / Flask, typical commands:
 
-**Option 1: Direct command (if PATH is configured)**
 ```bash
-qrs --help
-# generate synthetic sample price series
-qrs generate-data -o data_sample/sample_prices.csv -s 5 -d 365
-# compute example factors
-qrs compute-factors -d data_sample/sample_prices.csv -f momentum -f value -o output/factors.csv
-# run a backtest
-qrs backtest -d data_sample/sample_prices.csv -s output/factors.csv -o output/backtest_results.json
+# FastAPI example (uvicorn)
+cd src/quant_research_starter
+uvicorn api.main:app --reload --host 0.0.0.0 --port 8000
+
+# or if a Makefile is provided
+make dev-backend
 ```
 
-**Option 2: Python module (always works)**
+Confirm the REST endpoints (e.g., `GET /health`) are reachable at `http://localhost:8000`. -->
+
+### 3) Run cauweb (React + TS) in dev mode
+
+Open a new terminal and run:
+
 ```bash
-python -m quant_research_starter.cli --help
-python -m quant_research_starter.cli generate-data -o data_sample/sample_prices.csv -s 5 -d 365
-python -m quant_research_starter.cli compute-factors -d data_sample/sample_prices.csv -f momentum -f value
-python -m quant_research_starter.cli backtest -d data_sample/sample_prices.csv -s output/factors.csv -o output/backtest_results.json
+cd src/quant_research_starter/frontend/cauweb
+npm i --save-dev
+npm run dev
 ```
+<!-- 
+* The dev server typically runs at `http://localhost:3000` (or the port shown on start).
+* The frontend dev server is configured to proxy `/api` to `http://localhost:8000` — see `vite.config.js` or `webpack.dev.js` for proxy settings. -->
+
+<!-- If environment variables are required, copy `.env.example` → `.env.local` and edit values. -->
+
+<!-- ### 4) Optional: Run with mock WS server (dev/demo mode)
 
-### Demo (one-line)
+We provide a small mock WS generator for local demos. From `cauweb/`:
 
 ```bash
-make demo
+# run mock WS generator (node script)
+node scripts/mock-ws-server.js --port 9000 --seed 42 --rate 50
+
+# then start cauweb in mock mode (example query param)
+npm run dev -- -- --open "http://localhost:3000/?mock=true&ws=http://localhost:9000"
 ```
 
-### Step-by-step demo
+The mock server emits `tick`, `heartbeat`, `order_update` events useful for UI development.
 
-```bash
-# generate synthetic sample price series
-python -m quant_research_starter.cli generate-data -o data_sample/sample_prices.csv -s 5 -d 365
+--- -->
+
+## Production build & Docker
 
-# compute example factors
-python -m quant_research_starter.cli compute-factors -d data_sample/sample_prices.csv -f momentum -f value -o output/factors.csv
+### Frontend static build
 
-# run a backtest
-python -m quant_research_starter.cli backtest -d data_sample/sample_prices.csv -s output/factors.csv -o output/backtest_results.json
+From `cauweb`:
 
-# DISCLAIMER: OLD VERSION
-# optional: start the Streamlit dashboard, if on main stream
-streamlit run src/quant_research_starter/dashboard/streamlit_app.py
-# NEW VERSION: if streamlit is in legacy folder
-streamlit run legacy/streamlit/streamlit_app.py
+```bash
+npm ci
+npm run build
+# output directory typically `dist/` or `build/`
 ```
+<!-- 
+Test serve locally with `serve` or a small Nginx container:
 
----
+```bash
+npm install -g serve
+serve -s dist -l 8080
+``` -->
 
-## Example: small strategy (concept)
+<!-- ### Build Docker image (frontend)
 
-```python
-from quant_research_starter.backtest import Backtester
-from quant_research_starter.data import load_prices
-from quant_research_starter.factors import Momentum
+*Tip:* `Dockerfile.frontend` should be present. Build and run:
 
-prices = load_prices("data_sample/sample_prices.csv")
-factor = Momentum(window=63)
-scores = factor.compute(prices)
+```bash
+docker build -f Dockerfile.frontend -t qrs-cauweb:latest .
+docker run -p 8080:80 qrs-cauweb:latest
+``` -->
 
-bt = Backtester(prices, signals=scores, capital=1_000_000)
-results = bt.run()
-print(results.performance.summary())
-```
+<!-- ### Backend production
 
-### Rebalancing Frequency
+Use your normal WSGI/ASGI server + env+secrets management. Example (uvicorn + systemd) or containerize with a `Dockerfile.backend`. -->
 
-The backtester supports different rebalancing frequencies to match your strategy needs:
+<!-- ### Full-stack deployment recommendations
 
-```python
-from quant_research_starter.backtest import VectorizedBacktest
-# Daily rebalancing (default)
-bt_daily = VectorizedBacktest(prices, signals, rebalance_freq="D")
+* For static frontend hosting: **Vercel** or **Netlify** for quick deploys. Use `vercel.json` or `netlify.toml` for rewrites to the API.
+* For containerized deploys: build images for backend and frontend; host in Kubernetes or ECS/Fargate with autoscaling. Use a managed Redis for pub/sub and secure the WS gateway.
 
-# Weekly rebalancing (reduces turnover and transaction costs)
-bt_weekly = VectorizedBacktest(prices, signals, rebalance_freq="W")
+--- -->
 
-# Monthly rebalancing (lowest turnover)
-bt_monthly = VectorizedBacktest(prices, signals, rebalance_freq="M")
+<!-- ## Realtime contract & WS guide
 
-results = bt_monthly.run()
-```
+The frontend expects a stable WS message contract. A suggested minimal schema (example):
 
-Supported frequencies:
-- `"D"`: Daily rebalancing (default)
-- `"W"`: Weekly rebalancing (rebalances when the week changes)
-- `"M"`: Monthly rebalancing (rebalances when the month changes)
+```json
+{
+  "schema_version": "1.0",
+  "type": "tick",            # tick | snapshot | order_update | backtest_progress | heartbeat | error
+  "topic": "price:AAPL",   # topic or room
+  "payload": {
+    "timestamp": "2025-11-14T12:34:56.789Z",
+    "price": 192.45,
+    "volume": 1200
+  }
+}
+``` -->
 
-> The code above is illustrative—see `examples/` for fully working notebooks and scripts.
+<!-- Best practices:
 
----
+* Use topic-based subscriptions: `subscribe(topic)` and `unsubscribe(topic)` so the server publishes minimal data to active clients.
+* Include `schema_version` and a short `message_id` for idempotency and replay.
+* Implement heartbeat/ping-pong for stale detection. -->
 
-## CLI reference
+<!-- Where to find client code:
 
-Run `python -m quant_research_starter.cli --help` or `python -m quant_research_starter.cli <command> --help` for full usage. Main commands include:
+* `src/quant_research_starter/frontend/cauweb/src/lib/wsClient.ts` — typed, reconnecting WS client (if present) -->
 
-* `python -m quant_research_starter.cli generate-data` — create synthetic price series or download data from adapters
-* `python -m quant_research_starter.cli compute-factors` — calculate and export factor scores
-* `python -m quant_research_starter.cli backtest` — run the vectorized backtest and export results
+<!-- Server responsibilities:
 
-**Note:** If you have the `qrs` command in your PATH, you can use `qrs` instead of `python -m quant_research_starter.cli`.
+* Translate backend events (backtest updates, order events) into WS messages and publish to Redis pub/sub / message broker.
+* Implement room/topic filtering and auth checks on subscribe.
 
 ---
 
-## Project structure (overview)
+## APIs & Data flows: to be updated
+
+* **Backtest flow**: Frontend POSTs to `/api/backtest` with strategy config → backend enqueues job → backend emits progress to `backtest:{job_id}` → final results stored in DB and accessible via `/api/backtest/{job_id}/results`.
+* **Strategy CRUD**: REST endpoints for strategy create / update / delete, with validation in Python core.
+* **Data adapters**: optional connectors (yfinance, AlphaVantage) are in `src/quant_research_starter/core/data_adapters/`.
+
+> See `src/quant_research_starter/api/README.md` (if present) for detailed endpoint docs.
+
+--- -->
 
+## Testing & CI: to be updated
+
+<!-- ### Python unit tests
+
+```bash
+# from repo root
+pytest -q
 ```
-QuantResearchStarter/
-├─ src/quant_research_starter/
-│  ├─ data/              # data loaders & adapters
-│  ├─ factors/           # factor implementations
-│  ├─ backtest/          # backtester & portfolio logic
-│  ├─ analytics/         # performance and risk metrics
-│  ├─ cli/               # command line entry points
-│  └─ dashboard/         # optional Streamlit dashboard
-├─ examples/             # runnable notebooks & example strategies
-├─ tests/                # unit + integration tests
-└─ docs/                 # documentation source
+
+### Frontend tests
+
+```bash
+cd src/quant_research_starter/frontend/cauweb
+npm ci
+npm run test        # unit tests
+npm run test:e2e    # Playwright / Selenium tests (if configured)
+``` -->
+
+<!-- ### Linting & types
+
+```bash
+# TS typecheck
+npm run typecheck
+# ESLint
+npm run lint
+# Prettier formatting
+npm run format
 ```
 
+CI workflows are in `.github/workflows/` — they typically run linters, unit tests and publish artifacts. -->
+
 ---
 
-## Tests & CI
+## Streamlit (legacy) — archived
 
-We include unit tests and a CI workflow (GitHub Actions). Run tests locally with:
+The Streamlit dashboard is preserved under `legacy/streamlit/` for historical reference. It is **not** the primary UI anymore. If you need to run it:
 
 ```bash
-pytest -q
+cd legacy/streamlit
+pip install -r requirements.txt
+streamlit run app.py
 ```
 
-The CI pipeline runs linting, unit tests, and builds docs on push/PR.
+Migration notes:
+
+* Inventory features in `legacy/streamlit/` and decide which are high value to move into `cauweb`.
+* Create REST endpoints for functions that were tightly coupled to Streamlit server-side Python handlers.
+* Add React counterparts using `LiveChart`, tables and parameter UIs.
 
 ---
 
-## Contributing
+## Developer workflow & conventions
 
-Contributions are very welcome. Please follow these steps:
+* **Branches**: `main` for release-ready code; feature branches `feat/...`, hotfixes `fix/...`.
+* **Commits**: use Conventional Commits (type(scope): subject), refer: `.github/Contributor_Guide/commiting.md`
+* **PRs**: include a description, screenshots, or link tests/lint status. Use the PR template in `.github/PULL_REQUEST_TEMPLATE.md`
+* **Type-safety**: keep TS `strict` mode passing; add runtime validation at API boundaries using `zod` or `io-ts`.
 
-1. Fork the repository
-2. Create a feature branch
-3. Add tests for new behavior
-4. Open a pull request with a clear description and rationale
+<!-- ### Local debugging tips
 
-Please review `CONTRIBUTING.md` and the `CODE_OF_CONDUCT.md` before submitting.
+* Use the mock WS server for UI debugging: `node src/quant_research_starter/frontend/cauweb/scripts/mock-ws-server.js`.
+* For backend debugging, run `uvicorn api.main:app --reload` and then call the endpoints from Postman or `curl`. -->
 
 ---
 
-## AI policy — short & practical
+## Contributing
 
-**Yes — you are allowed to use AI tools** (ChatGPT, Copilot, Codeium, etc.) to help develop, prototype, or document code in this repository.
+1. Fork the repo and create a feature branch.
+2. Run tests & linters locally.
+3. Open a PR against `main` with a clear description, testing notes, and screenshots.
+<!-- 4. If this change introduces schema changes, update `specs/realtime.schema.json` and document migration steps. -->
 
-A few friendly guidelines:
+See `.github/Contributor_Guide/CONTRIBUTING.md` for code-style, review, and release guidance.
 
-* **Be transparent** when a contribution is substantially generated by an AI assistant — add a short note in the PR or commit message (e.g., "Generated with ChatGPT; reviewed and adapted by <your-name>").
-* **Review and test** all AI-generated code. Treat it as a helpful draft, not final production-quality code.
-* **Follow licensing** and attribution rules for any external snippets the AI suggests. Don’t paste large verbatim copyrighted material.
-* **Security & correctness**: double-check numerical logic, data handling, and anything that affects trading decisions.
+---
+
+## Roadmap / recommended next contributions:
+
+Suggested high-value items (already tracked in issues):
 
-This policy is intentionally permissive: we want the community to move fast while keeping quality and safety in mind.
+* Implement typed WS client in `src/quant_research_starter/frontend/cauweb` (reconnect, subscriptions).
+* Migrate high-value Streamlit pages to `cauweb` React components.
+* Add Playwright e2e tests for realtime flows with a mocked WS server.
+* Implement a paper-trade sandbox UI and backend adapter.
 
+See the Issues board for prioritized tasks and labels like `urgent`, `Type:___`, `Semver:___`.
+<!-- 
 ---
 
-## License
+## Troubleshooting
 
-This project is licensed under the MIT License — see the `LICENSE` file for details.
+* **`npm run build` fails with TS errors**: run `npm run typecheck` to isolate type issues; ensure correct `NODE_VERSION` and run `npm ci` to use lockfile.
+* **CORS / proxy errors**: ensure the frontend dev proxy is configured and backend running on expected host/port; check `.env.local`.
+* **WS not connecting**: verify WS URL, check auth token in handshake, and inspect server logs for subscribe rejections.
 
----
+If you hit an environment-specific issue, add a detailed issue with logs and reproduction steps.
+
+--- -->
+
+## License & contact
 
-## Acknowledgements
+This project is licensed under the license in `LICENSE` (check root). For questions, open an issue or contact the maintainers listed in `AUTHORS` / `MAINTAINERS` files.
 
-Built with inspiration from open-source quant libraries and the research community. If you use this project in papers or public work, a short citation or mention is appreciated.
+---
\ No newline at end of file
diff --git a/src/quant_research_starter/frontend/cauweb/package-lock.json b/src/quant_research_starter/frontend/cauweb/package-lock.json
index aef91449..c215f12f 100644
--- a/src/quant_research_starter/frontend/cauweb/package-lock.json
+++ b/src/quant_research_starter/frontend/cauweb/package-lock.json
@@ -69,6 +69,7 @@
       "resolved": "https://registry.npmjs.org/@babel/core/-/core-7.28.5.tgz",
       "integrity": "sha512-e7jT4DxYvIDLk1ZHmU/m/mB19rex9sv0c2ftBtjSBv+kVM/902eh0fINUzD7UwLLNR+jU585GxUJ8/EBfAM5fw==",
       "dev": true,
+      "peer": true,
       "dependencies": {
         "@babel/code-frame": "^7.27.1",
         "@babel/generator": "^7.28.5",
@@ -1597,6 +1598,7 @@
       "resolved": "https://registry.npmjs.org/@types/react/-/react-18.3.26.tgz",
       "integrity": "sha512-RFA/bURkcKzx/X9oumPG9Vp3D3JUgus/d0b67KB0t5S/raciymilkOa66olh78MUI92QLbEJevO7rvqU/kjwKA==",
       "dev": true,
+      "peer": true,
       "dependencies": {
         "@types/prop-types": "*",
         "csstype": "^3.0.2"
@@ -1708,6 +1710,7 @@
           "url": "https://github.com/sponsors/ai"
         }
       ],
+      "peer": true,
       "dependencies": {
         "baseline-browser-mapping": "^2.8.25",
         "caniuse-lite": "^1.0.30001754",
@@ -1746,6 +1749,7 @@
       "version": "4.5.1",
       "resolved": "https://registry.npmjs.org/chart.js/-/chart.js-4.5.1.tgz",
       "integrity": "sha512-GIjfiT9dbmHRiYi6Nl2yFCq7kkwdkp1W/lp2J99rX0yo9tgJGn3lKQATztIjb5tVtevcBtIdICNWqlq5+E8/Pw==",
+      "peer": true,
       "dependencies": {
         "@kurkle/color": "^0.3.0"
       },
@@ -2359,6 +2363,7 @@
           "url": "https://github.com/sponsors/ai"
         }
       ],
+      "peer": true,
       "dependencies": {
         "nanoid": "^3.3.11",
         "picocolors": "^1.1.1",
@@ -2378,6 +2383,7 @@
       "version": "18.3.1",
       "resolved": "https://registry.npmjs.org/react/-/react-18.3.1.tgz",
       "integrity": "sha512-wS+hAgJShR0KhEvPJArfuPVN1+Hz1t0Y6n5jLrGQbkb4urgPE/0Rve+1kMB1v/oWgHgm4WIcV+i7F2pTVj+2iQ==",
+      "peer": true,
       "dependencies": {
         "loose-envify": "^1.1.0"
       },
@@ -2398,6 +2404,7 @@
       "version": "18.3.1",
       "resolved": "https://registry.npmjs.org/react-dom/-/react-dom-18.3.1.tgz",
       "integrity": "sha512-5m4nQKp+rZRb09LNH59GM4BxTh9251/ylbKIbpe7TpGxfJ+9kv6BLkLBXIjjspbgbnIBNqlI23tRnTWT0snUIw==",
+      "peer": true,
       "dependencies": {
         "loose-envify": "^1.1.0",
         "scheduler": "^0.23.2"
@@ -2586,6 +2593,7 @@
       "version": "5.4.21",
       "resolved": "https://registry.npmjs.org/vite/-/vite-5.4.21.tgz",
       "integrity": "sha512-o5a9xKjbtuhY6Bi5S3+HvbRERmouabWbyUcpXXUA1u+GNUKoROi9byOJ8M0nHbHYHkYICiMlqxkg1KkYmm25Sw==",
+      "peer": true,
       "dependencies": {
         "esbuild": "^0.21.3",
         "postcss": "^8.4.43",