BDFR_Web/web_interface/README.md

# BDFR Web Interface

A modern web interface for the Bulk Downloader for Reddit (BDFR) built with FastAPI, WebSockets, and vanilla JavaScript.

## Features

- **Modern UI**: Clean, responsive design with gradient backgrounds and smooth animations
- **Real-time Progress**: WebSocket-based progress updates for active downloads
- **Subreddit Downloads**: Download posts from any subreddit with customizable limits and sorting
- **User Downloads**: Download posts from specific users
- **Status Monitoring**: Real-time system status and connection monitoring
- **Form Validation**: Client-side validation with visual feedback
- **Error Handling**: Comprehensive error handling with user-friendly notifications

## Project Structure

```
web_interface/
├── app/
│   └── main.py              # FastAPI application
├── static/
│   ├── css/
│   │   └── style.css        # Modern CSS styling
│   └── js/
│       └── app.js           # WebSocket client and form handling
├── templates/
│   └── index.html           # Main web interface
└── requirements.txt         # Python dependencies
```

## Installation

1. **Install Dependencies**:
   ```bash
   cd web_interface
   pip install -r requirements.txt
   ```

2. **Run the Application**:
   ```bash
   cd app
   python main.py
   ```

3. **Access the Interface**:
   Open your browser and navigate to `http://localhost:8000`

## API Endpoints

### Download Endpoints
- `POST /api/download/subreddit` - Start subreddit download
- `POST /api/download/user` - Start user download
- `GET /api/downloads` - List all active downloads
- `GET /api/downloads/{download_id}` - Get specific download status
- `DELETE /api/downloads/{download_id}` - Cancel download

### WebSocket
- `ws://localhost:8000/ws/progress` - Real-time progress updates

### Status Endpoints
- `GET /` - Main web interface
- `GET /health` - Health check
- `GET /api/bdfr/status` - BDFR system status

## Configuration

The application uses the following default settings:
- **Host**: `0.0.0.0`
- **Port**: `8000`
- **WebSocket Path**: `/ws/progress`
- **Static Files**: Served from `/static`

## Docker Support

To run with Docker:

```bash
# Build the image
docker build -t bdfr-web-interface .

# Run the container
docker run -p 8000:8000 bdfr-web-interface
```

## Development

### Adding New Features

1. **Backend Changes**: Modify `app/main.py` to add new endpoints
2. **Frontend Changes**: Update `templates/index.html` for UI changes
3. **Styling**: Modify `static/css/style.css` for visual changes
4. **JavaScript**: Update `static/js/app.js` for client-side functionality

### WebSocket Integration

The WebSocket connection automatically handles:
- Connection establishment and reconnection
- Progress updates from the server
- Error handling and user notifications
- Real-time UI updates

### Form Handling

Both download forms include:
- Input validation
- Loading states
- Success/error notifications
- Automatic form reset on success

## Integration with BDFR

### Direct BDFR API Integration

This interface uses the direct BDFR API integration, eliminating the need for subprocess console parsing:

- `/api/download/subreddit` - Downloads from subreddits using `BDFRManager.download_subreddit()`
- `/api/download/user` - Downloads from users using `BDFRManager.download_user()`
- `/api/bdfr/status` - Returns BDFR system status and capabilities
- `/ws/progress` - Provides real-time progress updates via WebSocket

The web interface imports `BDFRManager` directly from `bdfr.api` and uses structured progress callbacks for seamless integration.

### Migration Notes

**Previous Approach (Subprocess-based)**:
- Used `subprocess.Popen` to start BDFR CLI
- Parsed console output with regex for progress updates
- Required `BDFRRunner` class for process management
- Used `threading.Thread` and `queue.Queue` for coordination

**Current Approach (Direct API)**:
- Direct integration with `BDFRManager` from `bdfr.api`
- Structured `ProgressEvent` callbacks instead of console parsing
- Thread-safe progress tracking with `ProgressCallback` interface
- No subprocess overhead or console output parsing required

The migration provides better error handling, structured progress events, and eliminates console parsing complexity.

## Browser Support

- Modern browsers with WebSocket support
- Chrome 60+
- Firefox 55+
- Safari 11+
- Edge 79+

## Security Considerations

- CORS is enabled for all origins (configure for production)
- Input validation on both client and server
- No authentication implemented (add as needed)
- WebSocket connections are not secured (use WSS in production)

## Production Deployment

For production deployment:

1. Configure CORS for specific origins
2. Add authentication/authorization
3. Use HTTPS/WSS for secure connections
4. Configure proper logging
5. Set up reverse proxy (nginx recommended)
6. Add rate limiting
7. Configure environment variables

## Troubleshooting

### Common Issues

1. **WebSocket Connection Failed**:
   - Check if the server is running
   - Verify firewall settings
   - Check browser console for errors

2. **Downloads Not Starting**:
   - Verify BDFR integration is configured
   - Check server logs for errors
   - Ensure form data is valid

3. **Static Files Not Loading**:
   - Verify static file paths
   - Check file permissions
   - Ensure proper MIME types

### Debug Mode

Run with debug logging:
```bash
python main.py --log-level debug
```

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

## License

This project is part of the BDFR ecosystem. See the main project license for details.