Add initial project structure and documentation
- Created architecture documentation outlining high-level design, module organization, data flow, security model, performance considerations, testing strategy, and deployment architecture. - Added pyproject.toml for project metadata and dependencies management. - Introduced requirements files for development and production dependencies. - Set up testing configuration with pytest and tox. - Established basic directory structure for source code and tests, including __init__.py files. - Implemented a sample web application (index.html) for drag-and-drop functionality. - Configured VS Code workspace settings for Python development.
This commit is contained in:
commit
61aa33633c
34 changed files with 5342 additions and 0 deletions
270
README.md
Normal file
270
README.md
Normal file
|
|
@ -0,0 +1,270 @@
|
|||
# WebDrop Bridge
|
||||
|
||||
> Professional Qt-based desktop application for intelligent drag-and-drop file handling between web applications and desktop clients (InDesign, Word, Notepad++, etc.)
|
||||
|
||||
  
|
||||
|
||||
## Overview
|
||||
|
||||
WebDrop Bridge is a sophisticated desktop bridge application that intercepts text-based drag-and-drop operations from embedded web applications and converts them into native file-drag operations recognized by professional desktop applications.
|
||||
|
||||
### The Problem
|
||||
Modern web applications can transmit file paths via drag-and-drop, but desktop applications expect native file handles. Traditional solutions fail because:
|
||||
- Browsers sandbox cross-origin drag-and-drop
|
||||
- Web apps can't access the file system directly
|
||||
- Native apps need OS-level file handles (CF_HDROP on Windows, NSFilenamesPboardType on macOS)
|
||||
|
||||
### The Solution
|
||||
WebDrop Bridge embeds a web application in a Qt container with full filesystem access, intelligently intercepting and converting drag operations at the OS boundary.
|
||||
|
||||
## Features
|
||||
|
||||
- ✅ **Qt-based Architecture** - Native Windows & macOS support via PySide6
|
||||
- ✅ **Embedded Web App** - QtWebEngine provides Chromium without browser limitations
|
||||
- ✅ **Drag Interception** - Converts text paths to native file operations
|
||||
- ✅ **Path Whitelist** - Security-conscious file system access control
|
||||
- ✅ **Professional Build Pipeline** - MSI for Windows, DMG for macOS
|
||||
- ✅ **Comprehensive Testing** - Unit, integration, and end-to-end tests
|
||||
- ✅ **CI/CD Ready** - GitHub Actions workflows included
|
||||
|
||||
## Quick Start
|
||||
|
||||
### Requirements
|
||||
- Python 3.10+
|
||||
- Windows 10/11 or macOS 12+
|
||||
- 100 MB disk space
|
||||
|
||||
### Installation from Source
|
||||
|
||||
```bash
|
||||
# Clone repository
|
||||
git clone https://github.com/yourusername/webdrop-bridge.git
|
||||
cd webdrop-bridge
|
||||
|
||||
# Create virtual environment
|
||||
python -m venv venv
|
||||
source venv/bin/activate # macOS/Linux
|
||||
# venv\Scripts\activate # Windows
|
||||
|
||||
# Install dependencies
|
||||
pip install -r requirements.txt
|
||||
|
||||
# Run application
|
||||
python -m webdrop_bridge.main
|
||||
```
|
||||
|
||||
### Development Setup
|
||||
|
||||
```bash
|
||||
# Install development dependencies
|
||||
pip install -r requirements-dev.txt
|
||||
|
||||
# Run tests
|
||||
pytest
|
||||
|
||||
# Run linting checks
|
||||
tox -e lint
|
||||
|
||||
# Build for your platform
|
||||
tox -e build-windows # Windows
|
||||
tox -e build-macos # macOS
|
||||
```
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
webdrop-bridge/
|
||||
├── src/webdrop_bridge/ # Main application package
|
||||
│ ├── core/ # Core logic (drag interception, config)
|
||||
│ ├── ui/ # UI components (main window, widgets)
|
||||
│ ├── utils/ # Utilities (logging, validation)
|
||||
│ ├── main.py # Entry point
|
||||
│ └── config.py # Configuration management
|
||||
├── tests/
|
||||
│ ├── unit/ # Unit tests
|
||||
│ ├── integration/ # Integration tests
|
||||
│ ├── fixtures/ # Test data and fixtures
|
||||
│ └── conftest.py # Pytest configuration
|
||||
├── build/
|
||||
│ ├── windows/ # Windows-specific build configs
|
||||
│ ├── macos/ # macOS-specific build configs
|
||||
│ └── scripts/ # Build automation scripts
|
||||
├── webapp/ # Embedded web application
|
||||
├── resources/
|
||||
│ ├── icons/ # Application icons
|
||||
│ └── stylesheets/ # Qt stylesheets
|
||||
├── docs/ # Documentation
|
||||
├── pyproject.toml # Modern Python packaging
|
||||
├── pytest.ini # Test configuration
|
||||
├── tox.ini # Test automation
|
||||
└── README.md # This file
|
||||
```
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
┌────────────────────────────────────────┐
|
||||
│ Qt Main Window (PySide6) │
|
||||
│ ┌──────────────────────────────────┐ │
|
||||
│ │ QtWebEngineView │ │
|
||||
│ │ ┌────────────────────────────┐ │ │
|
||||
│ │ │ Web Application (HTML/JS) │ │ │
|
||||
│ │ │ • Drag with file paths │ │ │
|
||||
│ │ │ • Native drag operations │ │ │
|
||||
│ │ └────────────────────────────┘ │ │
|
||||
│ └──────────────────────────────────┘ │
|
||||
│ ↓ Drag Leave Event │
|
||||
│ ┌──────────────────────────────────┐ │
|
||||
│ │ DragInterceptor │ │
|
||||
│ │ • Validates path (whitelist) │ │
|
||||
│ │ • Creates QUrl + QMimeData │ │
|
||||
│ │ • Starts native file drag │ │
|
||||
│ └──────────────────────────────────┘ │
|
||||
└────────────────────────────────────────┘
|
||||
↓ Native File Drag
|
||||
┌─────────────────┐
|
||||
│ InDesign/Word │
|
||||
│ (receives file) │
|
||||
└─────────────────┘
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
Create `.env` file from `.env.example`:
|
||||
|
||||
```bash
|
||||
cp .env.example .env
|
||||
```
|
||||
|
||||
Key settings:
|
||||
- `WEBAPP_URL` - Local or remote web app URL
|
||||
- `ALLOWED_ROOTS` - Comma-separated whitelist of allowed directories
|
||||
- `LOG_LEVEL` - DEBUG, INFO, WARNING, ERROR
|
||||
- `WINDOW_WIDTH` / `WINDOW_HEIGHT` - Initial window size
|
||||
|
||||
## Testing
|
||||
|
||||
```bash
|
||||
# Run all tests
|
||||
pytest
|
||||
|
||||
# Run specific test type
|
||||
pytest tests/unit/ # Unit tests only
|
||||
pytest tests/integration/ # Integration tests only
|
||||
|
||||
# With coverage report
|
||||
pytest --cov=src/webdrop_bridge --cov-report=html
|
||||
|
||||
# Run on specific platform marker
|
||||
pytest -m windows # Windows-specific tests
|
||||
pytest -m macos # macOS-specific tests
|
||||
```
|
||||
|
||||
## Building Installers
|
||||
|
||||
### Windows MSI
|
||||
|
||||
```bash
|
||||
pip install pyinstaller
|
||||
python build/scripts/build_windows.py
|
||||
```
|
||||
|
||||
Output: `build/dist/WebDropBridge.exe`
|
||||
|
||||
### macOS DMG
|
||||
|
||||
```bash
|
||||
pip install pyinstaller
|
||||
bash build/scripts/build_macos.sh
|
||||
```
|
||||
|
||||
Output: `build/dist/WebDropBridge.dmg`
|
||||
|
||||
## Development Workflow
|
||||
|
||||
1. **Create feature branch**
|
||||
```bash
|
||||
git checkout -b feature/my-feature
|
||||
```
|
||||
|
||||
2. **Write tests first**
|
||||
```bash
|
||||
pytest tests/unit/test_my_feature.py
|
||||
```
|
||||
|
||||
3. **Implement feature**
|
||||
```bash
|
||||
# Edit src/webdrop_bridge/...
|
||||
```
|
||||
|
||||
4. **Run quality checks**
|
||||
```bash
|
||||
tox -e lint,type # Run linting and type checking
|
||||
```
|
||||
|
||||
5. **Submit pull request**
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Application won't start
|
||||
- Ensure Python 3.10+ is installed
|
||||
- Check `logs/webdrop_bridge.log` for errors
|
||||
- Verify all dependencies: `pip list`
|
||||
|
||||
### Drag-and-drop not working
|
||||
- Verify paths in `.env` are valid
|
||||
- Check `ALLOWED_ROOTS` whitelist includes your test directory
|
||||
- On macOS, check System Preferences → Security & Privacy → Accessibility
|
||||
|
||||
### Build errors
|
||||
- Clean build directory: `rm -rf build/temp build/dist`
|
||||
- Reinstall dependencies: `pip install --force-reinstall -r requirements.txt`
|
||||
- Check platform-specific requirements (Windows SDK, Xcode for macOS)
|
||||
|
||||
## Platform Support
|
||||
|
||||
| Platform | Version | Status | Notes |
|
||||
|----------|---------|--------|-------|
|
||||
| Windows | 10, 11 | ✅ Full | Tested on x64 |
|
||||
| macOS | 12, 13, 14 | ✅ Full | Intel & Apple Silicon |
|
||||
| Linux | Ubuntu 22.04+ | ⚠️ Partial | Limited testing |
|
||||
|
||||
## Contributing
|
||||
|
||||
We welcome contributions! Please:
|
||||
|
||||
1. Fork the repository
|
||||
2. Create a feature branch
|
||||
3. Write/update tests
|
||||
4. Submit a pull request
|
||||
5. Ensure CI passes
|
||||
|
||||
See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
|
||||
|
||||
## License
|
||||
|
||||
MIT License - see [LICENSE](LICENSE) file for details
|
||||
|
||||
## Credits
|
||||
|
||||
- Built with [PySide6](https://wiki.qt.io/Qt_for_Python)
|
||||
- Inspired by professional desktop integration practices
|
||||
- Special thanks to the Qt community
|
||||
|
||||
## Roadmap
|
||||
|
||||
- [ ] v1.0 - Stable Windows & macOS release
|
||||
- [ ] v1.1 - Advanced filtering and logging UI
|
||||
- [ ] v1.2 - API for custom handlers
|
||||
- [ ] v2.0 - Plugin architecture
|
||||
- [ ] v2.1 - Cloud storage integration (OneDrive, Google Drive)
|
||||
|
||||
## Support
|
||||
|
||||
- 📖 [Documentation](https://webdrop-bridge.readthedocs.io)
|
||||
- 🐛 [Issue Tracker](https://github.com/yourusername/webdrop-bridge/issues)
|
||||
- 💬 [Discussions](https://github.com/yourusername/webdrop-bridge/discussions)
|
||||
|
||||
---
|
||||
|
||||
**Status**: Alpha Development | **Last Updated**: January 2026
|
||||
Loading…
Add table
Add a link
Reference in a new issue