feat(UI): initial working frontend UI

2025-10-09 17:12:55 +13:00
parent e8972cae38
commit 9e61d18bf6
26 changed files with 6885 additions and 3 deletions
@@ -0,0 +1,202 @@
+# 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.