docs/DOCUMENTATION_INDEX.md

Quantum Hybrid Portfolio — Documentation Index

This is the master index for all Quantum Hybrid Portfolio documentation.

Getting started

Document	Description
README.md	Project overview and quick start
GETTING_STARTED.md	Canonical install, API, dashboard, env, troubleshooting
guides/HOW_TO_RUN.md	Detailed run commands and troubleshooting
guides/QUICKSTART.md	Quick start companion
../.env.example	Environment variable reference

Public demo & hosting

Document	Description
PUBLIC_DEMO.md	Audience, 60s story, disclaimer, operational expectations
HUGGINGFACE_SPACES.md	Hugging Face Spaces (Docker, port 7860)

Architecture & design

Document	Description
ARCHITECTURE.md	System architecture and data flow
TECHNICAL_PAPER.md	Technical background and research
project/DIRECTORY_GUIDE.md	Project directory structure
project/PROJECT_OVERVIEW.md	High-level product overview
project/SYSTEM_SUMMARY.md	System summary
project/TECHNICAL_DOCUMENTATION.md	Technical documentation

Migration & refactoring plans

Document	Description
plans/README.md	Hub: Next.js + API + pipeline migration
plans/MIGRATION_PHASES_AND_CHECKPOINTS.md	Phases 0–7, checkpoints, verification tests
plans/WORKSTREAM_BREAKDOWN.md	Parallel workstreams (web, API, pipeline)

API documentation

Document	Description
API_REFERENCE.md	Complete API endpoint reference
API_PRODUCT_GUIDE.md	API usage patterns and best practices
/api/docs/openapi	OpenAPI/Swagger spec (when API is running)

Dashboard documentation

Document	Description
DASHBOARD_GUIDE.md	Canonical dashboard user guide (tabs, modes, controls)
dashboard/DASHBOARD_README.md	Short landing + pointers

Archived / supplementary (redirect to DASHBOARD_GUIDE.md)

Document	Note
dashboard/DASHBOARD_FEATURE_SUMMARY.md	Consolidated
dashboard/DASHBOARD_FEATURE_GUIDE.md	Consolidated
dashboard/DASHBOARD_CUSTOMIZATION_FEATURES.md	Consolidated
dashboard/DASHBOARD_FULL_README.md	Consolidated
dashboard/DASHBOARD_VISUAL_GUIDE.md	Consolidated
dashboard/DASHBOARD_WALKTHROUGH_REPORT.md	Consolidated
dashboard/DASHBOARD_TEST_SUMMARY.md	Consolidated
frontend/frontend-guide.md	Frontend dev notes
frontend/ui-design.md	UI design notes

Planning & roadmaps

Document	Description
next-phase/README.md	Next phase (hub) — tracks A–C checklists, verification; links to plans/ (Track D)
planning/ENHANCEMENT_PLAN.md	Enhancement plan
planning/ENHANCEMENT_SUMMARY.md	Enhancement summary
planning/ENHANCED_FEATURES_README.md	Enhanced features
planning/ENHANCED_IMPLEMENTATION_DOCS.md	Enhanced implementation
planning/ENHANCED_SYSTEM_SUMMARY.md	Enhanced system summary
planning/NEXT_STEPS_INDUSTRY_STANDARD.md	Industry next steps
planning/PORTFOLIO_CUSTOMIZATION_ROADMAP.md	Customization roadmap
planning/PRODUCTION_FEATURES.md	Production features
planning/PRODUCTION_READINESS_PLAN.md	Production readiness
planning/QUANTUM_INTEGRATION_ROADMAP.md	Quantum integration roadmap
planning/WALKTHROUGH_SUMMARY.md	Walkthrough summary

Other

Document	Description
misc/qwen.md	Supplementary notes

Examples & tutorials

File	Description
../examples/basic_qsw_example.py	Basic QSW optimization
../examples/advanced_quantum_methods.py	Advanced quantum techniques
../examples/quantum_integration_example.py	Full integration example

Deployment

Document	Description
HUGGINGFACE_SPACES.md	Deploy to Hugging Face Spaces
../deploy_production.sh	Production deployment script
../deploy_hf_spaces.sh	HF Spaces deployment script
../docker-compose.yml	Docker Compose configuration

Development

Document	Description
NEXT_STEPS.md	Development roadmap and tasks
../demo_dashboard_features.sh	Dashboard feature demo script

Testing

File	Description
../tests/test_api_integration.py	API integration tests
../tests/test_api.py	API unit tests
../tests/test_api_productization.py	API productization tests
../tests/test_braket_backend.py	Braket backend tests

📋 Configuration Reference

Environment Variables

See .env.example for all available variables:

Category	Variables
Application	FLASK_ENV, LOG_LEVEL, PORT
Security	SECRET_KEY, JWT_SECRET_KEY, API_KEY, ADMIN_API_KEY
Database	DATABASE_URL, DB_PASSWORD
Redis	REDIS_HOST, REDIS_PORT, REDIS_PASSWORD
Rate Limiting	RATELIMIT_ENABLED, MAX_REQUESTS_PER_MINUTE
Portfolio	MAX_ASSETS, MAX_EVOLUTION_TIME, QUANTUM_COMPUTE_TIMEOUT
Market Data	YFINANCE_RATE_LIMIT, YFINANCE_TIMEOUT
AWS Braket	AWS_REGION, BRAKET_DEVICE_ARN
Caching	CACHE_TTL
CORS	CORS_ORIGINS
Monitoring	SENTRY_DSN
Jobs	JOB_WORKERS

QSW Configuration

Parameter	Default	Description
default_omega	0.3	Coupling strength
evolution_time	10	Evolution duration
max_turnover	0.15	Maximum portfolio turnover
stability_blend_factor	0.7	Stability vs optimization blend
max_weight	0.10	Maximum weight per asset
min_weight	0.01	Minimum weight per asset

📚 Research & Citations

Key Papers

• Chang et al. (2025) — Quantum Stochastic Walks for portfolio optimization
• López de Prado (2016) — Hierarchical Risk Parity (SSRN 2708678)
• Farhi et al. (2014) — Quantum Approximate Optimization Algorithm (QAOA)
• Peruzzo et al. (2014) — Variational Quantum Eigensolver (VQE)

Citing This Project

@software{quantum_hybrid_portfolio,
  author = {Quantum Global Group},
  title = {Quantum Hybrid Portfolio: Quantum-Inspired Optimization},
  year = {2026},
  url = {https://github.com/Quantum-Global-Group/quantum-hybrid-portfolio}
}

🔗 External Resources

• AWS Braket Documentation
• yfinance Documentation
• Flask Documentation
• React Documentation

📞 Support

• GitHub Issues: Report bugs or request features
• API Health: GET /api/health when running the API
• Metrics: GET /metrics for Prometheus metrics

---

Last updated: March 2026