Datasourceforcryptocurrency-5

Sleeping

App Files Files Community

Datasourceforcryptocurrency-5 / cursor-instructions /START_HERE_INSTRUCTIONS.md

Cursor Agent

Fix AI models pages and add monitoring system

426ef14 2 days ago

preview code

raw

history blame contribute delete

14.8 kB

🚀 START HERE - Instructions for AI Developer

⚠️ CRITICAL: THIS IS AN UPDATE REQUEST, NOT A NEW PROJECT

IMPORTANT: This is a SPACE UPDATE REQUEST for an existing HuggingFace Space. You are NOT creating a new space from scratch. You are UPDATING and ENHANCING an existing deployment to add comprehensive API capabilities.

📋 STEP-BY-STEP READING ORDER

Follow this EXACT ORDER when reading the documentation:

STEP 1: Read the Summary (5 minutes)

📄 File: HF_DEPLOYMENT_SUMMARY.md

Purpose: Get a quick overview of what needs to be done

What to understand:

This is an UPDATE to existing HuggingFace Space
We need to add 30+ API endpoints
Goal is to centralize ALL data requests through HF Space
Current problem: 60+ files making scattered API calls

Key takeaway: Understand the "why" before diving into "how"

STEP 2: Read the Official Request Letter (10 minutes)

📄 File: SEND_TO_HF_TEAM.md

Purpose: Understand the scope and priorities

What to understand:

Request type: UPDATE (not new deployment)
Priority: HIGH
Success criteria
Key requirements overview
Tech stack overview

Key takeaway: Understand project priorities and success metrics

STEP 3: Read Architecture Analysis (30 minutes)

📄 File: DATA_ARCHITECTURE_ANALYSIS_REPORT.md

Purpose: Understand current state and why changes are needed

What to understand:

Current architecture weaknesses
Files that need modification (63 files listed)
Data sources currently used
Proposed new architecture (Data Highway)
Implementation roadmap

Key takeaway: Understand the "before" state to implement the "after" state correctly

STEP 4: Read Complete API Specifications (2-3 hours)

📄 File: HUGGINGFACE_SPACE_DEPLOYMENT_REQUEST.md

Purpose: This is your MAIN REFERENCE for implementation

What to understand:

ALL 30+ API endpoint specifications
Request/Response formats for each endpoint
Query parameters
Path parameters
Error handling formats
WebSocket implementation
Caching strategy
Rate limiting
Data source integration
AI/ML models integration
Deployment configuration
Testing procedures

Key takeaway: This file contains EVERYTHING you need to implement. Read it thoroughly.

⚠️ CRITICAL SECTIONS (Must Read Carefully):

API Specifications (Lines 1-800) ← All endpoint definitions
Technical Requirements (Lines 801-1000) ← Backend code
Data Sources Integration (Lines 1001-1200) ← API integrations
Caching Strategy (Lines 1201-1300) ← Performance
AI/ML Models (Lines 1301-1500) ← AI features
WebSocket Implementation (Lines 1501-1700) ← Real-time
Deployment Config (Lines 1701-1900) ← Dockerfile, requirements.txt
Testing & Verification (Lines 1901-end) ← Quality assurance

STEP 5: Read Engineering Standards (Optional, 1 hour)

📄 File: ENGINEERING_GUIDE.md

Purpose: Understand coding standards and best practices

What to understand:

Code style guidelines
Component architecture
Error handling patterns
Testing requirements
Documentation standards

Key takeaway: Write code that matches project standards

🎯 IMPLEMENTATION CHECKLIST

After reading all documentation, follow this implementation order:

Phase 1: Environment Setup

- [ ] Clone/access existing HuggingFace Space
- [ ] Set up Python 3.9+ environment
- [ ] Install Redis locally for testing
- [ ] Create virtual environment
- [ ] Install all dependencies from requirements.txt

Phase 2: Core API Framework

- [ ] Set up FastAPI application structure
- [ ] Configure CORS middleware
- [ ] Set up Redis connection
- [ ] Create health check endpoint (/health)
- [ ] Test basic server startup

Phase 3: Data Sources Integration

- [ ] Implement CoinGecko API client
- [ ] Implement Binance API client
- [ ] Implement NewsAPI client
- [ ] Implement CryptoPanic client
- [ ] Implement Alternative.me client
- [ ] Create fallback mechanism
- [ ] Test each data source individually

Phase 4: Market Data Endpoints

- [ ] Implement GET /api/market
- [ ] Implement GET /api/price/{symbol}
- [ ] Implement GET /api/ohlcv
- [ ] Implement GET /api/ticker/{symbol}
- [ ] Add caching for each endpoint
- [ ] Test all market endpoints

Phase 5: News & Sentiment Endpoints

- [ ] Implement GET /api/news/latest
- [ ] Implement GET /api/sentiment/global
- [ ] Implement GET /api/sentiment/symbol/{symbol}
- [ ] Integrate Fear & Greed Index
- [ ] Test all news endpoints

Phase 6: Trading Endpoints

- [ ] Implement GET /api/exchange-info
- [ ] Implement GET /api/orderbook/{symbol}
- [ ] Implement GET /api/trades/{symbol}
- [ ] Test all trading endpoints

Phase 7: AI/ML Integration

- [ ] Load BERT sentiment model (ElKulako/cryptobert)
- [ ] Implement sentiment analysis function
- [ ] Implement price prediction model
- [ ] Implement GET /api/ai/signals
- [ ] Implement POST /api/ai/predict
- [ ] Implement GET /api/ai/analysis/{symbol}
- [ ] Test all AI endpoints

Phase 8: Blockchain Endpoints

- [ ] Implement GET /api/blockchain/transactions/{address}
- [ ] Implement GET /api/blockchain/whale-alerts
- [ ] Test blockchain endpoints

Phase 9: Statistics Endpoints

- [ ] Implement GET /api/stats
- [ ] Implement GET /api/stats/dominance
- [ ] Implement GET /api/history/price/{symbol}
- [ ] Test statistics endpoints

Phase 10: WebSocket Implementation

- [ ] Create WebSocket connection manager
- [ ] Implement WS /ws/ticker
- [ ] Implement WS /ws/trades
- [ ] Create broadcast mechanism
- [ ] Test WebSocket connections
- [ ] Test subscribe/unsubscribe

Phase 11: Performance & Optimization

- [ ] Implement caching layer (Redis)
- [ ] Implement rate limiting
- [ ] Add request deduplication
- [ ] Optimize database queries (if any)
- [ ] Test performance under load

Phase 12: Error Handling & Logging

- [ ] Implement consistent error format
- [ ] Add logging for all endpoints
- [ ] Add error tracking
- [ ] Test error scenarios

Phase 13: Testing

- [ ] Test all 30+ endpoints individually
- [ ] Test error handling
- [ ] Test fallback mechanisms
- [ ] Test caching
- [ ] Test rate limiting
- [ ] Test WebSocket stability
- [ ] Load test with 100+ concurrent users

Phase 14: Documentation

- [ ] Verify /docs endpoint works (FastAPI auto-docs)
- [ ] Add API examples to README
- [ ] Document authentication (if added)
- [ ] Document rate limits

Phase 15: Deployment

- [ ] Create Dockerfile
- [ ] Test Docker build locally
- [ ] Configure environment variables in HF Space
- [ ] Push to HuggingFace Space
- [ ] Verify deployment
- [ ] Test all endpoints in production
- [ ] Monitor for 24 hours

🔑 CRITICAL REMINDERS

⚠️ THIS IS AN UPDATE

YOU ARE NOT CREATING A NEW SPACE!
YOU ARE UPDATING AN EXISTING SPACE!

This means:
✅ Use existing space repository
✅ Keep existing functionality (if any)
✅ ADD new endpoints
✅ ENHANCE existing features
✅ Don't break existing integrations

⚠️ PRIORITY ORDER

1. MUST HAVE (implement first):
   - GET /api/market
   - GET /api/ohlcv
   - GET /api/news/latest
   - GET /api/sentiment/global
   - GET /api/ai/signals

2. SHOULD HAVE (implement second):
   - All other REST endpoints
   - WebSocket /ws/ticker

3. NICE TO HAVE (implement if time):
   - Advanced AI features
   - WebSocket /ws/trades
   - Blockchain endpoints

⚠️ QUALITY STANDARDS

✅ ALL endpoints must return valid JSON
✅ ALL errors must follow the standard format
✅ ALL endpoints must have caching
✅ ALL responses must include timestamp
✅ ALL endpoints must handle timeouts gracefully
✅ ALL data sources must have fallbacks

⚠️ PERFORMANCE REQUIREMENTS

Response Times:
- Price endpoints: < 100ms
- Market data: < 500ms
- News/Sentiment: < 1s
- AI predictions: < 2s

Caching TTL:
- Prices: 5 seconds
- OHLCV: 60 seconds
- News: 5 minutes
- AI signals: 2 minutes

Rate Limits:
- Per IP: 100 requests/minute
- Per endpoint: Varies (see specs)

📚 QUICK REFERENCE GUIDE

When you need to find...

Endpoint specifications → HUGGINGFACE_SPACE_DEPLOYMENT_REQUEST.md (Section: "DETAILED API SPECIFICATIONS")

Request/Response formats → HUGGINGFACE_SPACE_DEPLOYMENT_REQUEST.md (Each endpoint section)

Backend code examples → HUGGINGFACE_SPACE_DEPLOYMENT_REQUEST.md (Section: "TECHNICAL REQUIREMENTS")

Data source integration → HUGGINGFACE_SPACE_DEPLOYMENT_REQUEST.md (Section: "Data Sources Integration")

Caching implementation → HUGGINGFACE_SPACE_DEPLOYMENT_REQUEST.md (Section: "Caching Strategy")

AI model code → HUGGINGFACE_SPACE_DEPLOYMENT_REQUEST.md (Section: "AI/ML Models Integration")

WebSocket code → HUGGINGFACE_SPACE_DEPLOYMENT_REQUEST.md (Section: "WebSocket Implementation")

Deployment files → HUGGINGFACE_SPACE_DEPLOYMENT_REQUEST.md (Section: "DEPLOYMENT CONFIGURATION")

Testing procedures → HUGGINGFACE_SPACE_DEPLOYMENT_REQUEST.md (Section: "VERIFICATION CHECKLIST")

Current architecture → DATA_ARCHITECTURE_ANALYSIS_REPORT.md

Project overview → HF_DEPLOYMENT_SUMMARY.md

🚨 COMMON MISTAKES TO AVOID

❌ DON'T:

❌ Create a new HuggingFace Space (it already exists!)
❌ Remove existing functionality
❌ Hard-code API keys in the code
❌ Skip error handling
❌ Ignore caching requirements
❌ Skip testing
❌ Deploy without local testing
❌ Use synchronous code (use async/await)
❌ Return inconsistent response formats
❌ Ignore rate limiting

✅ DO:

✅ Update the existing Space
✅ Use environment variables for secrets
✅ Implement proper error handling
✅ Add caching to every endpoint
✅ Test locally before deploying
✅ Use async/await throughout
✅ Follow the standard response format
✅ Implement rate limiting
✅ Add fallback mechanisms
✅ Log all errors

📞 QUESTIONS & CLARIFICATIONS

If you're unsure about something:

Check the main spec file first - HUGGINGFACE_SPACE_DEPLOYMENT_REQUEST.md has 120+ pages of details
Look at code examples - The spec file includes complete Python code
Review architecture report - DATA_ARCHITECTURE_ANALYSIS_REPORT.md explains the "why"
Check the summary - HF_DEPLOYMENT_SUMMARY.md might answer quick questions

🎯 SUCCESS CRITERIA

You'll know you're done when:

✅ All 30+ endpoints return valid responses ✅ WebSocket connections are stable ✅ Caching improves response times ✅ Fallback mechanisms work ✅ AI models generate predictions ✅ /docs endpoint shows interactive API documentation ✅ Health check endpoint works ✅ All endpoints tested in production ✅ No errors in logs for 24 hours ✅ Response times meet requirements

🚀 READY TO START?

Your first 3 actions should be:

Read HF_DEPLOYMENT_SUMMARY.md (5 min)
Read SEND_TO_HF_TEAM.md (10 min)
Read HUGGINGFACE_SPACE_DEPLOYMENT_REQUEST.md (2-3 hours)

Then:

Set up local environment
Start with Phase 1 of implementation
Follow the checklist above
Test everything
Deploy

📋 FILE STRUCTURE OVERVIEW

📁 Project Documentation/
│
├── 📄 START_HERE_INSTRUCTIONS.md          ← YOU ARE HERE
│   └── Read this first for navigation
│
├── 📄 HF_DEPLOYMENT_SUMMARY.md            ← Step 1: Quick overview (5 min)
│   └── What we're building and why
│
├── 📄 SEND_TO_HF_TEAM.md                  ← Step 2: Official request (10 min)
│   └── Scope, priorities, success criteria
│
├── 📄 DATA_ARCHITECTURE_ANALYSIS_REPORT.md ← Step 3: Architecture (30 min)
│   └── Current state, problems, solution
│
├── 📄 HUGGINGFACE_SPACE_DEPLOYMENT_REQUEST.md ← Step 4: MAIN SPEC (2-3 hours)
│   └── Complete API specifications + code
│
└── 📄 ENGINEERING_GUIDE.md                 ← Step 5: Standards (optional, 1 hour)
    └── Coding standards and best practices

⏱️ TIME ESTIMATE

Reading: 3-4 hours
Setup: 1-2 hours
Implementation: 3-5 days (full-time)
Testing: 1-2 days
Deployment: 1 day

Total: 5-8 days for complete implementation

🎓 LEARNING PATH

If you're new to any of these technologies:

FastAPI: Read official docs at https://fastapi.tiangolo.com/
Redis: Read caching guide at https://redis.io/docs/
WebSockets: Read FastAPI WebSocket guide
HuggingFace Spaces: Read deployment guide
CCXT: Read crypto exchange library docs

📌 FINAL REMINDER

THIS IS AN UPDATE REQUEST! 🔄

NOT creating new space ❌
UPDATING existing space ✅

NOT a new project ❌
ENHANCING existing project ✅

NOT starting from zero ❌
BUILDING on existing foundation ✅

✅ PRE-FLIGHT CHECKLIST

Before you start coding, confirm:

I have read HF_DEPLOYMENT_SUMMARY.md
I have read SEND_TO_HF_TEAM.md
I have read DATA_ARCHITECTURE_ANALYSIS_REPORT.md
I have read HUGGINGFACE_SPACE_DEPLOYMENT_REQUEST.md completely
I understand this is an UPDATE, not a new project
I understand the priority order (MUST/SHOULD/NICE TO HAVE)
I have access to the existing HuggingFace Space
I have Python 3.9+ installed
I have Redis installed (or know how to use cloud Redis)
I have API keys for: CoinGecko, Binance, NewsAPI, etc.
I understand the success criteria
I am ready to start Phase 1

🚀 GO!

Start with: HF_DEPLOYMENT_SUMMARY.md

Then proceed through the reading order above.

Good luck! 🎯

Version: 1.0
Last Updated: December 5, 2025
Project: Dreammaker Crypto Trading Platform - HF Space Update
Status: 🟢 Ready for Implementation