QuantResearch

check out the link

QuantResearch — research-grade quantitative strategy starter kit with an interactive React/TypeScript frontend (cauweb), Python backtesting core, and legacy Streamlit dashboards archived under legacy/streamlit/.

---

Table of contents

• Project overview

• What’s included

• Prerequisites

• Quickstart (dev)

  • Run backend (Python)
  • Run frontend (cauweb)
  • Run with mock WS / demo mode

• Production build & docker

• Realtime contract & WS guide

• APIs & Data flows

• Testing & CI

• Streamlit (legacy) status & migration notes

• Developer workflow & conventions

• Contributing

• Roadmap / recommended next issues

• License & contact

---

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.

This README explains how to run both components in dev and production, how realtime is wired, and how to extend the system.

---

What’s included (high-level)

/ (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

---

Prerequisites

• 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

Ensure NODE_ENV and Python virtualenv are isolated per project.

---

Quickstart (dev)

Follow these steps to run the backend and frontend locally. The instructions assume you're at the repo root.

1) Set up Python env & install backend deps: to be updated

3) Run cauweb (React + TS) in dev mode

Open a new terminal and run:

cd src/quant_research_starter/frontend/cauweb
npm i --save-dev
npm run dev

Production build & Docker

Frontend static build

From cauweb:

npm ci
npm run build
# output directory typically `dist/` or `build/`

Testing & CI: to be updated

---

Streamlit (legacy) — archived

The Streamlit dashboard is preserved under legacy/streamlit/ for historical reference. It is not the primary UI anymore. If you need to run it:

cd legacy/streamlit
pip install -r requirements.txt
streamlit run app.py

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.

---

Developer workflow & conventions

• 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.

---

Contributing

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.

See .github/Contributor_Guide/CONTRIBUTING.md for code-style, review, and release guidance.

---

Roadmap / recommended next contributions:

Suggested high-value items (already tracked in issues):

• 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 & contact

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.

---