---
sdk: docker
emoji: 🚀
colorFrom: red
colorTo: yellow
pinned: true
---
# 🚀 Crypto API Monitor - Real-time Dashboard

یک داشبورد مانیتورینگ حرفه‌ای برای ارزهای دیجیتال با قابلیت نمایش داده‌های Real-time

A professional monitoring dashboard for cryptocurrencies with real-time data display capabilities

## 📋 فهرست مطالب / Table of Contents

- [ویژگی‌ها / Features](#ویژگی‌ها--features)
- [نصب و راه‌اندازی / Installation](#نصب-و-راه‌اندازی--installation)
- [استفاده / Usage](#استفاده--usage)
- [ساختار پروژه / Project Structure](#ساختار-پروژه--project-structure)
- [API Endpoints](#api-endpoints)
- [تنظیمات / Configuration](#تنظیمات--configuration)
- [مشکلات رایج / Troubleshooting](#مشکلات-رایج--troubleshooting)

## ✨ ویژگی‌ها / Features

### فارسی
- 📊 **داشبورد Real-time**: نمایش زنده قیمت ارزهای دیجیتال
- 🔌 **WebSocket**: اتصال دوطرفه برای به‌روزرسانی لحظه‌ای
- 📈 **نمودارهای تعاملی**: نمایش گرافیکی داده‌های بازار
- 🏥 **مانیتورینگ سلامت سیستم**: نظارت بر وضعیت سرورها و APIها
- 🔔 **سیستم هشدار**: اعلان‌های خودکار برای رویدادهای مهم
- 💼 **مدیریت Providers**: نظارت بر وضعیت صرافی‌ها و منابع داده
- 🎨 **رابط کاربری مدرن**: طراحی زیبا و کاربرپسند
- 🌐 **پشتیبانی از چندین منبع**: Binance, CoinGecko, Coinbase و بیشتر

### English
- 📊 **Real-time Dashboard**: Live cryptocurrency price display
- 🔌 **WebSocket**: Bidirectional connection for instant updates
- 📈 **Interactive Charts**: Graphical display of market data
- 🏥 **System Health Monitoring**: Server and API status tracking
- 🔔 **Alert System**: Automatic notifications for important events
- 💼 **Provider Management**: Exchange and data source monitoring
- 🎨 **Modern UI**: Beautiful and user-friendly interface
- 🌐 **Multi-source Support**: Binance, CoinGecko, Coinbase and more

## 🛠️ نصب و راه‌اندازی / Installation

### پیش‌نیازها / Prerequisites

#### ویندوز / Windows:
1. **Python 3.8 یا بالاتر**
   - دانلود از: https://www.python.org/downloads/
   - ⚠️ حتماً گزینه "Add Python to PATH" را فعال کنید

2. **مرورگر مدرن**
   - Chrome, Firefox, Edge یا Safari

### روش نصب / Installation Steps

#### روش اول: استفاده از فایل Batch (توصیه می‌شود) / Method 1: Using Batch File (Recommended)

```bash
# فقط دابل کلیک روی start.bat
# Just double-click on start.bat
```

این فایل به صورت خودکار:
- محیط مجازی Python را ایجاد می‌کند
- تمام پکیج‌های مورد نیاز را نصب می‌کند
- سرور را راه‌اندازی می‌کند

#### روش دوم: نصب دستی / Method 2: Manual Installation

```bash
# 1. ایجاد محیط مجازی / Create virtual environment
python -m venv venv

# 2. فعال‌سازی محیط مجازی / Activate virtual environment
# Windows:
venv\Scripts\activate

# 3. نصب پکیج‌ها / Install packages
pip install -r requirements.txt

# 4. اجرای سرور / Run server
python app.py
```

## 🎯 استفاده / Usage

### راه‌اندازی سریع / Quick Start

1. **اجرای برنامه / Run the application**:
   ```bash
   # دابل کلیک روی start.bat یا
   # Double-click start.bat or:
   python app.py
   ```

2. **باز کردن داشبورد / Open Dashboard**:
   - مرورگر خود را باز کنید
   - به آدرس زیر بروید:
   ```
   http://localhost:8000/dashboard
   ```

3. **مشاهده مستندات API / View API Documentation**:
   ```
   http://localhost:8000/docs
   ```

### قابلیت‌های داشبورد / Dashboard Features

#### صفحه اصلی / Main Dashboard
- **KPIs**: نمایش آمارهای کلیدی سیستم
- **وضعیت سیستم**: نمایش سلامت کلی
- **WebSocket Status**: وضعیت اتصال Real-time

#### بخش Providers
- لیست تمام منابع داده
- وضعیت هر Provider
- زمان پاسخ و Uptime
- تعداد درخواست‌های روزانه

#### بخش Categories
- دسته‌بندی ارزهای دیجیتال
- ارزش بازار هر دسته
- تغییرات 24 ساعته

#### بخش Rate Limits
- محدودیت‌های API
- مقدار باقیمانده
- زمان بازنشانی

#### بخش Logs
- لاگ‌های سیستم
- پیام‌های خطا و هشدار
- تاریخچه رویدادها

## 📁 ساختار پروژه / Project Structure

```
crypto-monitor/
│
├── app.py                  # FastAPI backend اصلی
├── index.html             # فرانت‌اند داشبورد
├── requirements.txt       # وابستگی‌های Python
├── start.bat             # فایل راه‌اندازی ویندوز
├── README.md             # مستندات (این فایل)
│
└── venv/                 # محیط مجازی Python (خودکار ایجاد می‌شود)
```

## 🔌 API Endpoints

### Health & Status
```
GET  /health              # وضعیت سلامت سیستم
GET  /api/health         # (Alternative)
GET  /status             # وضعیت کلی
GET  /info               # اطلاعات سیستم
```

### Providers
```
GET  /api/providers      # لیست تمام Providers
GET  /providers          # (Alternative)
```

### Cryptocurrency Data
```
GET  /api/crypto/prices/top?limit=10        # قیمت ارزها
GET  /api/crypto/market-overview            # خلاصه بازار
```

### Categories & Limits
```
GET  /api/categories     # دسته‌بندی ارزها
GET  /api/rate-limits    # محدودیت‌های API
```

### Logs & Alerts
```
GET  /api/logs?limit=50  # لاگ‌های سیستم
GET  /api/alerts         # هشدارهای فعال
```

### Hugging Face Integration
```
GET   /api/hf/health     # وضعیت HF
POST  /api/hf/refresh    # بروزرسانی داده
GET   /api/hf/registry   # لیست مدل‌ها
POST  /api/hf/search     # جستجوی مدل
POST  /api/hf/run-sentiment  # تحلیل احساسات
```

### WebSocket
```
WS   /ws/live            # اتصال Real-time
WS   /ws                 # (Alternative)
```

## ⚙️ تنظیمات / Configuration

### تغییر پورت / Changing Port

در فایل `app.py` خط آخر را تغییر دهید:

```python
uvicorn.run(
    "app:app",
    host="0.0.0.0",
    port=8000,  # پورت را اینجا تغییر دهید / Change port here
    reload=True,
    log_level="info"
)
```

### تنظیمات WebSocket

در فایل `index.html` بخش Configuration:

```javascript
const config = {
    apiBaseUrl: '',
    wsUrl: 'ws://localhost:8000/ws/live',
    autoRefreshInterval: 30000,  // 30 ثانیه / 30 seconds
    maxRetries: 3
};
```

## 🐛 مشکلات رایج / Troubleshooting

### مشکل 1: Python پیدا نمی‌شود
**حل:**
1. Python را از python.org نصب کنید
2. هنگام نصب "Add to PATH" را فعال کنید
3. سیستم را Restart کنید

### مشکل 2: پورت 8000 در حال استفاده است
**حل:**
```bash
# پیدا کردن پروسس
netstat -ano | findstr :8000

# بستن پروسس (Windows)
taskkill /PID <شماره_پروسس> /F
```

یا پورت را در `app.py` تغییر دهید.

### مشکل 3: pip install موفق نمی‌شود
**حل:**
```bash
# آپدیت pip
python -m pip install --upgrade pip

# نصب مجدد با verbose
pip install -r requirements.txt --verbose
```

### مشکل 4: WebSocket متصل نمی‌شود
**حل:**
1. بررسی کنید سرور در حال اجرا باشد
2. Firewall را چک کنید
3. Cache مرورگر را پاک کنید
4. از مرورگر دیگری امتحان کنید

### مشکل 5: داده‌ها نمایش داده نمی‌شوند
**حل:**
1. Console مرورگر را باز کنید (F12)
2. ارورها را بررسی کنید
3. بررسی کنید API Endpoints پاسخ می‌دهند:
   ```
   http://localhost:8000/health
   ```

## 📊 نمونه داده‌ها / Sample Data

این پروژه از داده‌های Mock (تقلبی) استفاده می‌کند برای نمایش قابلیت‌ها.

برای اتصال به API واقعی:
1. فایل `app.py` را ویرایش کنید
2. توابع `generate_*` را با API calls واقعی جایگزین کنید
3. کلیدهای API خود را اضافه کنید

## 🔒 امنیت / Security

### توصیه‌های امنیتی:
- از Environment Variables برای API Keys استفاده کنید
- HTTPS را در Production فعال کنید
- Rate Limiting را پیاده‌سازی کنید
- Input Validation را اضافه کنید

## 📈 گسترش پروژه / Extending

### اضافه کردن Provider جدید:

```python
# در app.py توابع generate_providers_data()
providers.append({
    "name": "YourProvider",
    "type": "Exchange",
    "status": "operational",
    # ...
})
```

### اضافه کردن Endpoint جدید:

```python
@app.get("/api/your-endpoint")
async def your_endpoint():
    return {"data": "your data"}
```

## 🤝 مشارکت / Contributing

برای مشارکت در پروژه:
1. Fork کنید
2. Branch جدید بسازید
3. تغییرات را Commit کنید
4. Pull Request بزنید

## 📄 لایسنس / License

این پروژه تحت لایسنس MIT منتشر شده است.

## 👨‍💻 سازنده / Developer

**Niema**
- متخصص در سیستم‌های Trading و AI
- تجربه در Full-stack Development
- تخصص در React/TypeScript و FastAPI

## 📞 پشتیبانی / Support

برای مشکلات و سوالات:
- Issue باز کنید در GitHub
- ایمیل بزنید
- مستندات را مطالعه کنید

## 🎓 یادگیری بیشتر / Learn More

### منابع مفید:
- [FastAPI Documentation](https://fastapi.tiangolo.com/)
- [WebSocket Guide](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket)
- [Chart.js Documentation](https://www.chartjs.org/docs/)
- [Python Async/Await](https://docs.python.org/3/library/asyncio.html)

---

## 🚀 Ready to Start?

```bash
# فقط این دستور را اجرا کنید:
# Just run this command:

start.bat
```

**و داشبورد شما آماده است! 🎉**
**Your dashboard is ready! 🎉**

---

**ساخته شده با ❤️ برای کامیونیتی ارز دیجیتال**
**Made with ❤️ for the Crypto Community**