CONTRIBUTING.md

Contributing to QuantIQ

Thank you for your interest in contributing to QuantIQ! We welcome developers of all backgrounds to help us build a premium quantitative research terminal.

This document details the project architecture, developer setup, code guidelines, and deployment workflows.

---

📂 Project Structure Map

• backend/ — FastAPI core server. Exposes GraphQL/REST APIs and WebSocket channels.
• frontend/ — React / TypeScript client built with Vite and Tailwind CSS.
• worker/ — Tick ingestion service. Periodically polls Yahoo Finance and dispatches ticks to Redpanda Cloud.
• alembic/ — Database migrations for watchlists, strategy records, and user targets.
• assets/ — UI mockups, database schemas, and documentation images.
• train.py — Offline model training script that generates indicator features and exports model.onnx.
• deploy_hf.ps1 — Automated deployment pipeline script for Hugging Face Spaces.

---

🛠️ Local Development Setup

1. Ingest Ingestion & Backend Setup

Prerequisites: Make sure you have uv and Docker Desktop installed.

# Sync python virtual environment and lock file
uv sync

# Copy the environment template and configure keys
cp .env.example .env

# Spin up local PostgreSQL (NeonDB replica) and Redis containers
docker-compose up -d

# Execute database migrations
uv run alembic upgrade head

# Start the local FastAPI server
uv run uvicorn backend.app.main:app --reload

2. Start Background Services

# Start the ingestion worker (fetches stock ticks every 5 seconds)
uv run python worker/worker.py

# Start Celery worker with beat enabled (logs ML predictions and outcomes)
uv run celery -A backend.app.services.celery_app worker --beat --loglevel=info

3. Frontend Dashboard Setup

cd frontend
npm install
npm run dev

---

🚀 Deployment Workflow (Hugging Face Spaces & GitHub)

Hugging Face Spaces hosting requires a custom metadata block (YAML frontmatter) at the very top of README.md. To keep the GitHub repository clean while pushing updates to Hugging Face, you must use the automated deployment script:

Hugging Face Deployment Procedure:

1. Ensure your changes are committed on your local branch.
2. In PowerShell, execute the deployment script from the project root:

   .\deploy_hf.ps1
   

3. What this script does automatically:
   • Prepends the YAML frontmatter configuration block to README.md.
   • Commits the change (chore: add HF Space config for deployment).
   • Pushes the commit to the Hugging Face space repository (git push hf main).
   • Automatically restores the clean README.md file back to its default state.
   • Commits the cleanup (chore: restore clean README for GitHub).
4. Finally, push your clean branch changes directly to GitHub:

   git push origin main
   

---

🧼 Code Quality & Style Guidelines

To keep the pipeline green, verify the following standards locally before opening a pull request:

🐍 Python (Backend / Worker)

• Linter & Formatter: We use ruff. Run the check locally:

  uv run ruff check .
  

⚛️ TypeScript & React (Frontend)

• Formatters: Ensure typescript compiling (tsc) and Vite bundling compile cleanly:

  cd frontend
  npm run build
  

---

🎯 Open Development Goals

Check out our active GitHub Issues page or pick one of these tasks to start:

1. [Backend] Model Metadata Endpoint: Expose GET /api/v1/ml/metadata to parse and return properties from the loaded model.onnx.
2. [Frontend] RSI Reference Boundaries: Use the Lightweight Charts API to draw Overbought (70) and Oversold (30) reference price lines.
3. [Backend] Discord/Slack webhook price alerts: Build a dispatcher service sending real-time stock crossings directly to webhook endpoints.