Clean up repo: move docs to docs/, add SECURITY.md, .editorconfig, update README with badges, fix cross-references, correct documentation to reflect actual project state

Co-authored-by: christianlouis <361235+christianlouis@users.noreply.github.com> Agent-Logs-Url: https://github.com/christianlouis/pop_puller_to_gmail/sessions/71f26285-5584-42b2-8255-8ad2c9e9ecb4
2026-03-23 10:57:31 +00:00
parent 88a44dfe73
commit b3a0c4bfd8
22 changed files with 223 additions and 316 deletions
@@ -0,0 +1,195 @@
+# Web Interface Quick Start Guide
+
+The POP3 to Gmail Forwarder now includes a modern web interface built with Next.js, making it easy to manage your email forwarding without API calls.
+
+## 🌐 Accessing the Web Interface
+
+After starting the services with `docker-compose -f docker-compose.new.yml up -d`, the web interface is available at:
+
+**http://localhost:3000**
+
+## 📱 Features
+
+### Landing Page
+- Overview of the service
+- Sign In / Sign Up buttons
+- Feature highlights
+
+### Authentication
+- **Email/Password Registration** - Create a new account
+- **Email/Password Login** - Sign in to existing account
+- **Google OAuth** - One-click sign-in with Google
+
+### Dashboard
+- **Overview Cards** showing:
+  - Total mail accounts
+  - Emails forwarded today
+  - Active accounts
+  - Recent errors
+- **Recent Activity** - Table of recent processing runs
+- **Quick Actions** - Add new account, view all accounts
+
+### Mail Accounts Management
+- **List View** - All your configured mail accounts
+  - Status indicators (active/inactive, errors)
+  - Last checked timestamp
+  - Quick enable/disable toggle
+- **Add Account** 
+  - Auto-detect button for popular providers (Gmail, Outlook, Yahoo, etc.)
+  - Test connection before saving
+  - Configure check intervals and limits
+- **Edit Account** - Update existing account settings
+- **Delete Account** - Remove accounts you no longer need
+
+### Settings
+- **Profile Management** - Update your name and email
+- **Subscription Info** - View your current plan and limits
+- **Notification Settings** - Configure error notifications
+
+## 🚀 Getting Started with the Web Interface
+
+1. **Start the services** (if not already running):
+   ```bash
+   docker-compose -f docker-compose.new.yml up -d
+   ```
+
+2. **Open your browser** to http://localhost:3000
+
+3. **Create an account**:
+   - Click "Sign Up" 
+   - Enter your details
+   - Or use "Sign in with Google"
+
+4. **Add your first mail account**:
+   - Click "Add Mail Account" button
+   - Enter your email address
+   - Click "Auto-Detect" to automatically fill in server settings
+   - Enter your email password (or app password)
+   - Click "Test Connection" to verify
+   - Click "Save"
+
+5. **Monitor your forwarding**:
+   - Dashboard shows real-time statistics
+   - Check the recent activity table for processing history
+   - View detailed logs for each account
+
+## 🎨 Technology Stack
+
+- **Framework**: Next.js 14 with App Router
+- **Language**: TypeScript
+- **Styling**: Tailwind CSS
+- **State Management**: Zustand
+- **Data Fetching**: TanStack Query (React Query)
+- **Icons**: Lucide React
+- **API Client**: Axios
+
+## 🔧 Development
+
+To run the frontend in development mode locally:
+
+```bash
+cd frontend
+npm install
+npm run dev
+```
+
+The development server will start at http://localhost:3000 with hot reload enabled.
+
+## 🐳 Docker Configuration
+
+The frontend is configured in `docker-compose.new.yml`:
+
+```yaml
+frontend:
+  build:
+    context: ./frontend
+    dockerfile: Dockerfile
+  container_name: pop3-frontend
+  ports:
+    - "3000:3000"
+  environment:
+    - NEXT_PUBLIC_API_URL=http://backend:8000
+  depends_on:
+    - backend
+  restart: unless-stopped
+```
+
+## 🌍 Environment Variables
+
+Create a `.env.local` file in the `frontend` directory:
+
+```bash
+# Backend API URL
+NEXT_PUBLIC_API_URL=http://localhost:8000
+```
+
+For production, update this to your actual backend URL.
+
+## 📸 Screenshots
+
+_(Screenshots will be added after deployment)_
+
+### Dashboard
+- Overview with statistics cards
+- Recent processing runs
+
+### Mail Accounts
+- List of all configured accounts
+- Add/Edit account modals
+
+### Authentication
+- Login page
+- Registration page
+- OAuth flow
+
+## 🔐 Security
+
+- All API requests require authentication via JWT tokens
+- Passwords are never stored in the frontend
+- OAuth tokens are managed securely
+- CSRF protection enabled
+- Secure HTTP-only cookies for sensitive data
+
+## 📱 Responsive Design
+
+The interface is fully responsive and works on:
+- Desktop computers
+- Tablets
+- Mobile phones
+
+## 🆘 Troubleshooting
+
+### Cannot connect to backend
+- Ensure backend is running: `docker-compose -f docker-compose.new.yml ps`
+- Check backend logs: `docker-compose -f docker-compose.new.yml logs backend`
+- Verify API URL in `.env.local`
+
+### Authentication not working
+- Clear browser local storage
+- Check backend logs for auth errors
+- Verify Google OAuth credentials (if using OAuth)
+
+### Frontend not loading
+- Check frontend logs: `docker-compose -f docker-compose.new.yml logs frontend`
+- Rebuild frontend: `docker-compose -f docker-compose.new.yml build frontend`
+- Clear browser cache
+
+## 🔄 Updates
+
+To update the frontend:
+
+```bash
+# Pull latest changes
+git pull
+
+# Rebuild and restart
+docker-compose -f docker-compose.new.yml build frontend
+docker-compose -f docker-compose.new.yml restart frontend
+```
+
+## 📞 Support
+
+For issues or questions:
+- Open an issue on GitHub
+- Check the documentation in the `docs` folder
+- Review API documentation at http://localhost:8000/api/docs