feat(UI): initial working frontend UI

web_interface/STARTUP.md

@@ -0,0 +1,177 @@
+# BDFR Web Interface Startup Scripts
+
+This directory contains simple startup scripts to easily run the BDFR web interface application.
+
+## Available Scripts
+
+### 🚀 Quick Start
+
+Choose the appropriate script for your operating system:
+
+- **`start.py`** - Cross-platform Python script (recommended)
+- **`start.sh`** - Unix/Linux/macOS shell script
+- **`start.bat`** - Windows batch script
+
+## Usage
+
+### Option 1: Python Script (Cross-platform)
+
+```bash
+# Navigate to the web_interface directory
+cd web_interface
+
+# Run the startup script
+python start.py
+```
+
+### Option 2: Shell Script (Unix/Linux/macOS)
+
+```bash
+# Navigate to the web_interface directory
+cd web_interface
+
+# Make sure the script is executable
+chmod +x start.sh
+
+# Run the startup script
+./start.sh
+```
+
+### Option 3: Batch Script (Windows)
+
+```cmd
+REM Navigate to the web_interface directory
+cd web_interface
+
+REM Run the startup script
+start.bat
+```
+
+## What the Scripts Do
+
+1. **Check Python version** - Ensures Python 3.8+ is installed
+2. **Install dependencies** - Automatically installs required packages from `requirements.txt`
+3. **Verify BDFR module** - Checks if the BDFR module is available
+4. **Start the server** - Launches the FastAPI application with uvicorn
+
+## Server Information
+
+Once started, the web interface will be available at:
+- **Main interface**: http://localhost:8000
+- **API documentation**: http://localhost:8000/docs
+- **Health check**: http://localhost:8000/health
+
+## Features
+
+- ✅ Automatic dependency management
+- ✅ Cross-platform compatibility
+- ✅ Colored output for better user experience
+- ✅ Error handling and informative messages
+- ✅ Graceful server shutdown
+- ✅ BDFR module availability checking
+
+## Requirements
+
+- Python 3.8 or higher
+- Internet connection (for installing dependencies)
+- BDFR module in Python path (parent directory should contain the BDFR package)
+- Reddit OAuth application (for authentication features)
+
+## Reddit OAuth Setup
+
+To use the authentication features, you need to:
+
+1. **Create a Reddit OAuth Application**:
+   - Go to [Reddit App Preferences](https://www.reddit.com/prefs/apps)
+   - Click "Create App" or "Create Another App"
+   - Choose "web app" as the application type
+   - Set a name (e.g., "BDFR Web Interface")
+   - Set redirect URI to: `http://localhost:8000/auth/callback`
+
+2. **Configure the Redirect URI** (if using a different port or domain):
+   - Run the OAuth setup helper: `python setup_oauth.py`
+   - Or manually copy `.env.example` to `.env`
+   - Update the following in the `.env` file:
+     - `BDFR_REDIRECT_URI` - Your OAuth redirect URI
+     - `BDFR_CLIENT_ID` - Your OAuth client ID (from Reddit app)
+     - `BDFR_CLIENT_SECRET` - Your OAuth client secret (from Reddit app)
+   - Make sure the redirect URI matches exactly what you set in your Reddit OAuth app
+
+3. **Update BDFR Configuration**:
+   - The web interface uses the same OAuth credentials as BDFR
+   - You need to either update your existing Reddit OAuth app or create a new one
+
+## Option A: Update Existing Reddit OAuth App
+
+If you want to use the same OAuth app for both BDFR CLI and web interface:
+
+1. Go to [Reddit App Preferences](https://www.reddit.com/prefs/apps)
+2. Find your existing app (the one with client ID `U-6gk4ZCh3IeNQ`)
+3. Click "edit" and add your redirect URI to the "redirect uris" field:
+   - `http://localhost:8000/auth/callback`
+4. Save the changes
+
+## Option B: Create a New Reddit OAuth App (Recommended)
+
+For better separation between CLI and web interface:
+
+1. Go to [Reddit App Preferences](https://www.reddit.com/prefs/apps)
+2. Click "Create App" or "Create Another App"
+3. Fill in the details:
+   - **Name**: `BDFR Web Interface` (or your preferred name)
+   - **App type**: `web app`
+   - **Description**: `Web interface for BDFR (Bulk Downloader for Reddit)`
+   - **About URL**: (optional)
+   - **Redirect URI**: `http://localhost:8000/auth/callback`
+4. Click "Create app"
+5. Copy the client ID and client secret
+6. Update `bdfr/default_config.cfg` with the new credentials:
+   ```
+   client_id = YOUR_NEW_CLIENT_ID
+   client_secret = YOUR_NEW_CLIENT_SECRET
+   ```
+
+## Troubleshooting
+
+### "BDFR module not found"
+Make sure you're running the script from the correct directory, or ensure the parent directory containing the BDFR package is in your Python path.
+
+### "Python 3.8+ required"
+Install Python 3.8 or higher from the official Python website.
+
+### "Permission denied" (Unix/Linux/macOS)
+Make sure the shell script has execute permissions:
+```bash
+chmod +x start.sh
+```
+
+### "invalid redirect_uri parameter" (OAuth Error)
+This error occurs when the redirect URI doesn't match what you configured in your Reddit OAuth app:
+
+1. **Verify your Reddit OAuth app settings**:
+   - Go to [Reddit App Preferences](https://www.reddit.com/prefs/apps)
+   - Find your app and check the redirect URI
+   - Make sure it exactly matches what you're using
+
+2. **Update the redirect URI**:
+   - Copy `.env.example` to `.env`
+   - Set `BDFR_REDIRECT_URI` to match your Reddit OAuth app
+   - Example: `BDFR_REDIRECT_URI=http://localhost:8000/auth/callback`
+
+3. **Common redirect URI formats**:
+   - Local development: `http://localhost:8000/auth/callback`
+   - With custom port: `http://localhost:3000/auth/callback`
+   - Production: `https://yourdomain.com/auth/callback`
+
+4. **Recreate your OAuth app if needed**:
+   - Delete the existing app in Reddit
+   - Create a new one with the correct redirect URI
+
+## Manual Alternative
+
+If you prefer to run the server manually:
+
+```bash
+cd web_interface
+pip install -r requirements.txt
+python -m uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload