• 📁 Drag & Drop Uploads - Intuitive file upload with progress tracking
• ⬇️ Instant Downloads - Quick file retrieval from any connected device
• 📱 QR Code Access - Scan to connect from mobile devices instantly
• 🔄 Real-Time Sync - WebSocket-powered live updates across all clients

• 🔐 Host/Client Approval - Host authorizes all client connections
• 🔑 PIN Protection - Global and per-file PIN authentication
• 🔒 Secure Filenames - Automatic sanitization prevents path traversal
• 🛡️ Rate Limiting - Built-in protection against abuse
• 🔍 Zeroconf Discovery - Auto-discover WifiX servers on local network (mDNS/Bonjour)

• 🌙 Dark Mode - Toggle between light and dark themes
• 🗑️ Safe Deletion - Confirmation modals prevent accidental removals
• 📈 Upload Progress - Real-time feedback during file transfers
• 💾 File Persistence - Files remain until explicitly deleted

• Python 3.8 or higher
• Node.js 16 or higher
• npm or yarn

# Clone repository
git clone https://github.com/yourusername/WifiX.git
cd WifiX

# Backend setup
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r backend/requirements.txt

# Frontend setup
cd frontend\react
npm install

Terminal 1 - Backend:

python backend/app.py
# Server runs on http://localhost:5000

Terminal 2 - Frontend:

cd frontend\react
npm run dev
# Development server on http://localhost:5173

• Host Dashboard: http://localhost:5173
• Client Access: Scan QR code or use displayed IP address
• Mobile: Scan QR code from any mobile device on same network

🖥️ Desktop App (Recommended for Personal Use):

WifiX can be packaged as a standalone desktop application using Tauri:

# Quick start (after Rust installation)
.\START_TAURI.ps1

# Or manually:
cd frontend\react
npm run tauri:dev      # Development mode
npm run tauri:build    # Build .exe installer

📱 Benefits:

• ✅ Single .exe file (~5 MB)
• ✅ No hosting costs
• ✅ Python backend auto-starts
• ✅ No internet required
• ✅ Users just download and run

📖 Desktop app guide: TAURI_DESKTOP_APP.md

☁️ Cloud Deployment (For Public Access):

For production deployment with Docker, systemd, HTTPS, and more, see DEPLOYMENT.md.

Quick production options:

# Docker deployment
docker-compose up -d

# Linux systemd service
sudo systemctl start wifux

# Production server (Gunicorn)
gunicorn -k eventlet -w 1 --bind 0.0.0.0:5000 backend.app:app

📖 Full deployment guide: DEPLOYMENT.md - Covers Docker, nginx, HTTPS, Zeroconf, monitoring, and more.

WifiX/
├── backend/
│   ├── app.py                      # Flask backend server
│   └── requirements.txt            # Python dependencies for backend
├── backend/uploads/                # File storage directory
├── frontend/
│   └── react/
│       ├── src/
│       │   ├── components/         # React components
│       │   │   ├── Header.jsx
│       │   │   ├── ServerControl.jsx
│       │   │   ├── FileUploadZone.jsx
│       │   │   ├── FileList.jsx
│       │   │   ├── DeleteModal.jsx
│       │   │   ├── ConnectionApprovalModal.jsx
│       │   │   ├── ConnectionStatus.jsx
│       │   │   ├── UploadErrorModal.jsx
│       │   │   ├── DarkModeToggle.jsx
│       │   │   └── Footer.jsx
│       │   ├── hooks/              # Custom React hooks
│       │   │   ├── useSocket.js
│       │   │   ├── useFileUpload.js
│       │   │   └── useAuth.js
│       │   ├── utils/              # Utility functions
│       │   │   ├── api.js
│       │   │   └── constants.js
│       │   ├── App.jsx             # Main React component
│       │   └── main.jsx            # React entry point
│       ├── .env                    # Environment variables
│       ├── package.json            # Node dependencies
│       └── vite.config.js          # Vite configuration
└── README.md

1. Create and activate Python virtual environment:

   cd D:\Projects\WifiX
   python -m venv .venv
   .\.venv\Scripts\Activate.ps1

2. Install Python dependencies:

   pip install -r backend/requirements.txt

3. Configure environment variables (optional):

   # Create a .env file or set environment variables
   $env:ACCESS_PIN = "1234"              # Enable PIN authentication
   $env:CORS_ORIGINS = "http://localhost:5173,http://localhost:5174"
   $env:FILE_TTL_SECONDS = "0"           # 0 = files persist until deleted
   $env:SECRET_KEY = "your-secret-key"   # Session encryption key

4. Run the Flask backend:

   python backend/app.py

   Backend will start on http://localhost:5000

Note: uploaded files are now stored in backend/uploads/. During the migration the original top-level uploads/ directory was copied and the original was renamed to uploads_backup_20251111154617/ in the repo root as a safety backup — delete it only after you verify everything is present.

1. Navigate to frontend directory:

   cd frontend\react

2. Install Node dependencies:

   npm install

3. Configure environment variables: Create or edit .env file:

   VITE_API_URL=http://localhost:5000
   

4. Run the Vite dev server:

   npm run dev

   Frontend will start on http://localhost:5173 (or 5174 if 5173 is in use).

Comprehensive documentation is available in the docs/ folder:

• Features Guide - Detailed feature documentation
• Usage Guide - How to use WifiX
• API Documentation - REST & WebSocket API reference
• Architecture - System design and architecture
• Troubleshooting - Common issues and solutions
• Contributing Guide - How to contribute
• Changelog - Version history
• Security Policy - Security guidelines

WifiX/
├── backend/
│   ├── app.py                   # Flask application
│   ├── requirements.txt         # Python dependencies
│   └── uploads/                 # File storage (gitignored)
├── frontend/
│   └── react/
│       ├── src/
│       │   ├── components/      # React components
│       │   ├── hooks/           # Custom hooks
│       │   ├── utils/           # Utility functions
│       │   ├── App.jsx          # Main app component
│       │   └── main.jsx         # Entry point
│       ├── package.json         # Node dependencies
│       └── vite.config.js       # Vite configuration
├── docs/                        # Documentation
│   ├── INDEX.md                 # Documentation index
│   ├── ARCHITECTURE.md          # System architecture
│   ├── TROUBLESHOOTING.md       # Problem solving
│   └── USAGE.md                 # Usage guide
├── CONTRIBUTING.md              # Contribution guidelines
├── CHANGELOG.md                 # Version history
├── SECURITY.md                  # Security policies
├── API.md                       # API documentation
├── LICENSE                      # MIT License
└── README.md                    # This file

Backend (backend/.env or system):

ACCESS_PIN=1234                    # Optional: Enable PIN authentication
SECRET_KEY=your-secret-key-here    # Session encryption (auto-generated if not set)
CORS_ORIGINS=http://localhost:5173 # Allowed origins (comma-separated)
FILE_TTL_SECONDS=0                 # File auto-cleanup (0=disabled)
CLEANUP_INTERVAL_SECONDS=60        # Cleanup check interval

Frontend (frontend/react/.env):

VITE_API_URL=http://localhost:5000  # Backend API URL

Modify in backend/app.py:

app.config['MAX_CONTENT_LENGTH'] = 1024 * 1024 * 1024  # 1GB default

WifiX includes multiple security layers:

• Host Approval - All client connections require host authorization
• PIN Authentication - Optional global and per-file PIN protection
• Rate Limiting - Prevents abuse (10 uploads/min, 20 deletes/min)
• Secure Filenames - Automatic sanitization prevents path traversal
• Session Management - Secure, HTTP-only cookies
• CORS Protection - Configurable origin restrictions

For security issues, see SECURITY.md.

Client → Server:

• become_host - Register as host
• stop_host - Stop hosting
• request_connect - Request connection
• approve_request - Approve client (host only)
• deny_request - Deny client (host only)

Server → Client:

• file_uploaded - New file available
• file_deleted - File removed
• incoming_request - Connection request (host)
• request_approved - Connection approved
• request_denied - Connection denied

See API.md for complete documentation.

• Python 3.8+
• Node.js 16+
• Git

# Clone repository
git clone https://github.com/yourusername/WifiX.git
cd WifiX

# Backend
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r backend/requirements.txt

# Frontend
cd frontend\react
npm install

Terminal 1 - Backend (with auto-reload):

$env:FLASK_ENV="development"
python backend/app.py

Terminal 2 - Frontend (with HMR):

cd frontend\react
npm run dev

cd frontend\react
npm run build
# Build output in dist/ folder

See CONTRIBUTING.md for contribution guidelines. npm run build npm run preview # Preview production build

### Lint Frontend Code

```powershell
cd frontend\react
npm run lint

• ✅ Environment-based CORS configuration
• ✅ Comprehensive logging system
• ✅ Enhanced error handling with user feedback
• ✅ Rate limiting on critical endpoints
• ✅ File size validation (100MB limit)
• ✅ Modular component architecture
• ✅ Custom React hooks for reusability
• ✅ Constants file for configuration
• ✅ Improved error messages
• ✅ Delete confirmation modal
• ✅ Upload progress tracking
• ✅ File persistence (no auto-cleanup by default)

• TypeScript migration for better type safety
• Unit tests (pytest for backend, vitest for frontend)
• Docker support for easy deployment
• HTTPS support for production
• Toast notifications (react-hot-toast)
• Virtual scrolling for large file lists
• File search and filtering
• Multi-file upload
• Folder support
• Download all as ZIP

For detailed troubleshooting, see docs/TROUBLESHOOTING.md.

Port Already in Use:

• Vite auto-selects next available port (5174, 5175...)
• Update CORS_ORIGINS in backend if needed

Socket.IO Connection Errors:

• Ensure CORS_ORIGINS includes frontend dev server URL
• Check firewall/antivirus settings
• Verify backend is running

Upload Failures:

• Check file size limit (1GB default)
• Verify rate limits (10 uploads/min)
• Check backend logs for errors

Files Not Showing:

• Verify PIN authentication (if enabled)
• Check host approval (if client)
• Refresh browser or reconnect

We welcome contributions! Please see CONTRIBUTING.md for:

• Code of Conduct
• Development setup
• Coding standards
• Pull request process
• Issue guidelines

Quick contribution steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/AmazingFeature)
3. Commit changes (git commit -m 'Add AmazingFeature')
4. Push to branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

This project is licensed under the MIT License - see the LICENSE file for details.

• ✅ Core file sharing functionality
• ✅ Host/Client approval system
• ✅ PIN authentication
• ✅ QR code generation
• ✅ Real-time updates via WebSocket
• ✅ Dark mode support
• ✅ Rate limiting

• Docker support (see DEPLOYMENT.md)
• Zeroconf/mDNS auto-discovery
• Database integration (SQLite/PostgreSQL)
• File search and filtering
• Batch file operations
• Enhanced mobile UI

• TypeScript migration
• Unit and integration tests
• Folder upload/download
• ZIP archive creation
• HTTPS/SSL by default
• Multi-language support
• Room codes for easy connections

See CHANGELOG.md for version history and GitHub Issues for tracking.

Built with amazing open-source tools:

• Flask - Web framework
• React - UI library
• Vite - Build tool
• Tailwind CSS - Styling framework
• DaisyUI - Component library
• Socket.IO - Real-time communication
• Lucide - Icon library

• 📚 Documentation: Browse GitHub Pages
• 🐛 Issues: Report bugs on GitHub Issues
• 💬 Discussions: Join GitHub Discussions
• 🔒 Security: Report vulnerabilities via SECURITY.md

Contributions are welcome! Please open an issue or submit a pull request.

Note: This application is designed for trusted local networks. For production use on untrusted networks, implement additional security measures (HTTPS, stronger authentication, network isolation, etc.).