deployment-guide.md

# 🚀 Deployment Guide for Hugging Face Spaces

This guide explains how to deploy the updated Wildberries Analytics Dashboard to Hugging Face Spaces.

## 📋 Prerequisites

- Hugging Face account
- Wildberries API token (optional for demo mode)
- Git installed locally

## 🛠️ Step-by-Step Deployment

### 1. Create a New Space

1. Go to [Hugging Face Spaces](https://huggingface.co/spaces)
2. Click **"Create new Space"**
3. Configure your space:
   - **Space name**: `wildberries-analytics` (or your preferred name)
   - **License**: MIT
   - **SDK**: **Gradio**
   - **Hardware**: CPU Basic (free tier)
   - **Visibility**: Public or Private

### 2. Clone Your Space

```bash
git clone https://huggingface.co/spaces/YOUR_USERNAME/wildberries-analytics
cd wildberries-analytics
```

### 3. Add Project Files

Copy all the updated project files to your space directory:

```
wildberries-analytics/
├── app.py                    # Main application
├── requirements.txt          # Dependencies
├── README.md                 # Space documentation
├── config.py                 # Configuration management
├── wildberries_client.py     # API client
├── forecasting.py            # Forecasting algorithms
├── dashboard.py              # Visualization components
├── utils.py                  # Utilities and demo data
├── .gitignore               # Git ignore patterns
└── examples/
    └── sample_data.json     # Sample data for demo
```

### 4. Configure Environment Variables (Optional)

If you have a Wildberries API token:

1. Go to your Space page
2. Click **Settings** tab
3. Scroll to **Repository secrets**
4. Add a new secret:
   - **Name**: `WILDBERRIES_API_TOKEN`
   - **Value**: Your Wildberries API token

### 5. Commit and Push

```bash
git add .
git commit -m "Initial deployment of Wildberries Analytics Dashboard"
git push
```

### 6. Wait for Build

- Hugging Face will automatically build your space
- Check the **Logs** tab to monitor the build process
- Build typically takes 2-5 minutes

## ⚙️ Configuration Options

### Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `WILDBERRIES_API_TOKEN` | No | Your Wildberries API token for real data |
| `DEBUG` | No | Set to `true` for debug mode |
| `GRADIO_THEME` | No | Gradio theme (`soft`, `default`, etc.) |

### Wildberries API Token Setup

1. **Get your token**:
   - Log into your Wildberries seller account
   - Go to Settings → Access to API
   - Generate token with permissions:
     - ✅ Analytics
     - ✅ Statistics
     - ✅ Marketplace

2. **Token permissions needed**:
   ```
   Bit 2: Access to Analytics
   Bit 5: Access to Statistics
   Bit 4: Access to Marketplace
   ```

## 🔧 Customization

### Changing the Theme

Edit `app.py` line with `gr.themes.Soft()`:

```python
# Available themes:
gr.themes.Default()
gr.themes.Soft()
gr.themes.Monochrome()
gr.themes.Glass()
```

### Adding More Languages

Update the `README.md` metadata:

```yaml
language:
- en
- ru
```

### Custom Domain (Pro Feature)

For custom domains, upgrade to a Pro space and configure in Settings.

## 🚨 Troubleshooting

### Common Issues

**1. Build Fails with Dependencies**
```bash
# Check requirements.txt for version conflicts
# Pin specific versions if needed
gradio==5.7.1
pandas>=2.0.3
```

**2. Import Errors**
```python
# Ensure all modules are in the same directory
# Check for typos in import statements
```

**3. API Connection Issues**
- Verify token is correctly set in Spaces secrets
- Check token permissions in Wildberries dashboard
- Review API rate limits (300 requests/minute)

**4. Demo Mode Not Working**
- Check if `utils.py` contains demo data functions
- Verify `examples/sample_data.json` exists

### Checking Logs

1. Go to your Space page
2. Click **Settings** tab
3. View **Container logs** for detailed error messages

### Performance Optimization

**For better performance**:
1. Upgrade to CPU Upgrade hardware ($0.03/hour)
2. Use persistent storage for data caching
3. Optimize data processing in batch operations

## 📊 Monitoring Usage

### Space Analytics

- View usage statistics in Space settings
- Monitor monthly compute costs
- Track user interactions

### API Rate Limiting

The dashboard automatically handles Wildberries API rate limits:
- 300 requests per minute maximum
- Exponential backoff on 429 errors
- Graceful fallback to demo mode

## 🔄 Updates and Maintenance

### Updating the Application

1. Make changes locally
2. Test with demo mode
3. Commit and push to update Space:

```bash
git add .
git commit -m "Update: description of changes"
git push
```

### Monitoring API Changes

- Subscribe to Wildberries API updates
- Test regularly with your API token
- Update error handling as needed

## 🆘 Support

### Getting Help

1. **Hugging Face Community**: [discuss.huggingface.co](https://discuss.huggingface.co)
2. **Gradio Documentation**: [gradio.app/docs](https://gradio.app/docs)
3. **Wildberries API Docs**: [dev.wildberries.ru](https://dev.wildberries.ru/en/openapi/api-information)

### Community Resources

- Example Spaces: Browse similar analytics dashboards
- Gradio Components: Explore advanced UI components
- API Integration Patterns: Study other marketplace integrations

## 📈 Advanced Features

### Adding More Marketplaces

Extend the dashboard to support additional marketplaces:

1. Create new API client modules
2. Update configuration for multiple tokens
3. Add marketplace selection in UI

### Data Persistence

For storing historical data:

1. Upgrade to persistent storage
2. Implement database integration
3. Add data export features

### Real-time Updates

For live dashboard updates:

1. Implement WebSocket connections
2. Add auto-refresh functionality
3. Use Gradio's live update features

---

**🎉 Congratulations!** Your Wildberries Analytics Dashboard is now live on Hugging Face Spaces!

Visit your space URL to start analyzing your marketplace data: `https://huggingface.co/spaces/YOUR_USERNAME/wildberries-analytics`