QuantYield is a fixed income analytics platform: a Django REST Framework backend for bond pricing, yield curve modeling, portfolio risk, and scenario analysis, with a genuine React web dashboard that the platform's own documentation didn't previously mention at all. Advanced forecasting and volatility models (a Transformer, an LSTM, GARCH/EGARCH, XGBoost credit-spread prediction) are real, working implementations that degrade gracefully to simpler fallbacks (an AR(1) model, historical volatility) when their optional dependency (PyTorch, arch, or XGBoost) isn't installed, since none of the three is a hard requirement of the base install.
- Overview
- Project Structure
- Feature Status
- Technology Stack
- Architecture
- Installation and Setup
- Running the Stack
- API Surface
- Testing
- CI/CD Pipeline
- Documentation
- Contributing
- License
QuantYield demonstrates a fixed income analytics workflow across a real, runnable codebase. The Django backend and its five apps (core, bonds, portfolios, curves, analytics) are wired and covered by tests, with JWT authentication and an auto-generated OpenAPI schema. A React web dashboard exists as a full, working client with its own login, register, and analytics pages, but earlier documentation for this project never mentioned it.
QuantYield/
├── code/
│ ├── backend/ # Django REST Framework application
│ │ ├── quantyield/ # Project config: settings (base/dev/prod), urls, asgi/wsgi
│ │ ├── apps/ # core (auth), bonds, portfolios, curves, analytics
│ │ ├── services/ # Pricing and curve-building service layer
│ │ └── tests/ # Backend test suite
│ └── ml_services/ # Forecasting, volatility, credit spread, regime,
│ # and PCA factor models (framework-agnostic,
│ # advanced dependencies optional with fallbacks)
├── frontend/ # React (Vite) web dashboard, not covered by
│ # earlier documentation for this project
├── docs/ # Numbered documentation set (01 through 08)
├── infrastructure/ # Backend-only Dockerfile and compose variant, nginx
├── docker-compose.yml # Full stack: db, redis, api, nginx
└── README.md
| Component | Details |
|---|---|
| API | Django REST Framework, versioned under /api/v1/, with JWT auth (obtain, refresh, register, me) and an auto-generated OpenAPI schema (drf-spectacular) served at /docs/. |
| Bond pricing | Dirty and clean price, a Brent-method YTM solver, accrued interest, and cash flow generation. |
| Duration and spreads | Macaulay, modified, and DV01 duration, key rate duration across 10 tenors, Z-spread, and a Monte Carlo OAS calculation for callable bonds. |
| Yield curves | Nelson-Siegel, Svensson, bootstrap, and cubic spline curve construction. |
| Portfolio risk | Market value, duration, and convexity aggregation, DV01, and sector, rating, and maturity allocation breakdowns. |
| Scenario analysis and VaR | 10 standard scenarios plus custom parallel, twist, and credit shifts; historical (overlapping-window) and parametric VaR/CVaR. |
| Forecasting (optional PyTorch) | A real Transformer and LSTM implementation for rate forecasting with Monte Carlo confidence bands, used if PyTorch is installed; falls back to an AR(1) model otherwise. |
| Volatility (optional arch) | GARCH(1,1) and EGARCH via the arch library if installed; falls back to a historical volatility term structure otherwise. |
| Credit spreads (optional XGBoost) | XGBoost-based OAS prediction by rating, sector, and macro environment if XGBoost is installed, with a fallback estimator otherwise. |
| Regime detection and curve factors | An ML ensemble classifying yield curve regimes (normal, inverted, flat, steep, humped), and PCA decomposition into level, slope, and curvature factors (via scikit-learn if installed). |
| Web dashboard | React app (Vite, plain JavaScript) with React Router, Recharts, and Framer Motion, covering a landing page, login, register, dashboard, bonds, portfolios, curves, ML, and analytics pages. |
| Area | Technology |
|---|---|
| Web framework | Django 5, Django REST Framework, drf-spectacular (OpenAPI 3.0) |
| Auth | djangorestframework-simplejwt |
| Database | SQLite in development, PostgreSQL in production |
| Cache | Local memory by default, configurable to Redis via CACHE_URL |
| Numerical core | NumPy, SciPy, pandas |
| Deep learning (optional) | PyTorch, for the Transformer and LSTM forecasters |
| ML ensemble (optional) | scikit-learn (regime detection, PCA), XGBoost (credit spreads) |
| Volatility (optional) | The arch library, for GARCH and EGARCH |
| Web frontend | React 18, Vite, React Router, Recharts, Framer Motion, date-fns |
| Deployment | Docker Compose, Uvicorn/Gunicorn, Nginx |
| CI/CD | GitHub Actions |
| Testing | pytest (backend, ML services); Vitest and Testing Library (frontend) |
Client
└── frontend (React, Vite) ── HTTP/JSON ──┐
▼
Backend (Django REST Framework, /api/v1)
├── Apps core (auth), bonds, portfolios, curves, analytics
├── Services pricing, curve building
└── Data layer PostgreSQL/SQLite, cache (local memory or Redis)
ML services (code/ml_services, imported by the analytics app)
forecaster (Transformer/LSTM, optional PyTorch, AR(1) fallback)
volatility_model (GARCH/EGARCH, optional arch, historical fallback)
credit_spread_model (XGBoost, optional, with a fallback estimator)
regime_classifier · pca_factor_model (optional scikit-learn)
See the numbered documentation set for detail, starting with docs/01_overview.md.
Prerequisites: Python 3.11+ and Node.js 18+.
git clone https://github.com/quantsingularity/QuantYield.git
cd QuantYield
# Backend
cd code/backend
pip install -r requirements.txt
cp ../../.env.example .env
# Optional: advanced ML models
pip install torch arch xgboost scikit-learn
# Frontend
cd ../../frontend
npm install# Backend (from code/backend)
python manage.py migrate
python manage.py seed_data
python manage.py runserver # http://localhost:8000
# Frontend (from frontend)
npm run devAPI docs at http://localhost:8000/docs/; the Django admin at http://localhost:8000/admin/.
Full stack in containers:
cp .env.example .env
docker compose up --buildFor a backend-only container setup, see infrastructure/docker-compose.backend-only.yml.
Base URL http://localhost:8000/api/v1/.
| Group | Prefix | Highlights |
|---|---|---|
| Auth | /api/v1/auth |
token, token/refresh, register, me |
| Bonds | /api/v1/bonds |
Pricing, duration, spread, and cash flow endpoints |
| Portfolios | /api/v1/portfolios |
Portfolio risk, allocation, VaR, and scenario endpoints |
| Curves | /api/v1/curves |
Curve construction and factor decomposition |
| Analytics | /api/v1/analytics |
Forecasting, volatility, credit spread, and regime endpoints |
Full request and response schemas are in docs/02_api_reference.md, and interactively at /docs/ once the API is running.
# Backend (from code/backend)
pytest
# ML services (from code/ml_services)
pytest
# Frontend (from frontend)
npm test| Test file | Test count |
|---|---|
test_pricing.py (service layer, no database) |
19 |
test_curve_builder.py (service layer, no database) |
17 |
test_bonds_api.py (API integration) |
16 |
test_portfolios_api.py (API integration) |
12 |
test_auth_api.py (API integration) |
15 |
That's 79 test functions across 5 files. See docs/08_testing.md for how to run and extend the suite.
The ML services have their own pytest suite of 126 tests across 6 files:
| Test file | Test count |
|---|---|
tests/test_pca_factor_model.py (curve decomposition) |
22 |
tests/test_volatility_model.py (GARCH and historical volatility) |
15 |
tests/test_forecaster.py (AR(1) rate forecaster, caching) |
21 |
tests/test_regime_classifier.py (regime features, rules, ensemble) |
35 |
tests/test_credit_spread_model.py (credit spread ensemble) |
25 |
tests/test_schemas.py (result types and package exports) |
8 |
Three of those tests are strict expected failures (xfail) that record known defects: multi-day EGARCH forecasts fall back to historical volatility, a constant rate series produces NaN forecasts, and the rule-based regime fallback returns probabilities that sum to 1.2. They fail the run as soon as the defect is fixed, which is the cue to remove the marker.
The frontend has its own Vitest suite of 72 tests across 6 files:
| Test file | Test count |
|---|---|
src/lib/apiClient.test.js (HTTP client) |
14 |
src/context/AuthContext.test.jsx (login, session) |
20 |
src/context/ToastContext.test.jsx (notifications) |
7 |
src/pages/Login.test.jsx (sign in form) |
5 |
src/pages/Register.test.jsx (registration form) |
10 |
src/App.test.jsx (routing and route guards) |
16 |
GitHub Actions (.github/workflows/cicd.yml) runs four jobs on push, pull request, and manual dispatch:
| Job | Depends on | What it does |
|---|---|---|
| Code Quality Checks | - | Formatter checks across the repository |
| Backend Test & Build | Code Quality Checks | Runs the pytest suite with coverage and uploads the report as an artifact, then builds the backend Docker image and smoke tests the container |
| ML Services Tests & Validation | Code Quality Checks | Byte-compiles the ML services, checks that every module imports cleanly, then runs the pytest suite with coverage (uploaded as an artifact) |
| Frontend Test & Build | Code Quality Checks | Installs dependencies, runs the Vitest suite with coverage (uploaded as an artifact), then produces the production web build and uploads it |
| Document | Contents |
|---|---|
| docs/01_overview.md | Architecture, capabilities, technology stack |
| docs/02_api_reference.md | Endpoint reference with request/response schemas |
| docs/03_quant_models.md | Mathematical models: pricing, duration, curves, VaR |
| docs/04_ml_ai_models.md | AI models: Transformer, LSTM, GARCH, XGBoost, PCA |
| docs/05_deployment.md | Production deployment, Docker, environment setup |
| docs/06_configuration.md | Configuration reference for all settings |
| docs/07_data_models.md | Database schema: tables, fields, constraints, indexes |
| docs/08_testing.md | Test suite, running tests, adding tests, CI |
Open a pull request.
This project is licensed under the MIT License - see the LICENSE file for details.