webdrop-bridge/QUICKSTART.md

Quick Start Guide

Project Setup (5 minutes)

1. Open in VS Code

# Option A: Open the workspace file directly
code webdrop_bridge.code-workspace

# Option B: Open the folder
code .

2. Install Dependencies

# Create virtual environment
python -m venv venv

# Activate virtual environment
source venv/bin/activate    # macOS/Linux
# venv\Scripts\activate     # Windows

# Install development dependencies
pip install -r requirements-dev.txt

3. Verify Installation

# Run project structure tests
pytest tests/unit/test_project_structure.py -v

# Expected output:
# test_project_structure.py::test_project_structure PASSED
# test_project_structure.py::test_essential_files PASSED
# test_project_structure.py::test_python_package_structure PASSED

Project Structure Overview

webdrop-bridge/
│
├── src/webdrop_bridge/          ← Main application code
│   ├── core/                    ← Business logic (validator, drag interceptor)
│   ├── ui/                      ← UI components (main window, widgets)
│   └── utils/                   ← Utilities (logging, helpers)
│
├── tests/                       ← Test suite
│   ├── unit/                    ← Unit tests
│   ├── integration/             ← Integration tests
│   └── fixtures/                ← Test data
│
├── build/                       ← Build automation
│   ├── windows/                 ← Windows-specific
│   ├── macos/                   ← macOS-specific
│   └── scripts/                 ← Build scripts
│
├── docs/                        ← Documentation
│   └── ARCHITECTURE.md          ← Architecture guide
│
├── webapp/                      ← Embedded web application
│   └── index.html               ← Test drag-drop page
│
├── DEVELOPMENT_PLAN.md          ← Detailed roadmap
├── README.md                    ← User documentation
├── CONTRIBUTING.md              ← Contributing guidelines
└── Makefile                     ← Convenience commands

Current Status

Phase 4 is COMPLETE - All core features and professional features implemented!

What's Already Implemented

Phase 1-3 (Core Features):

• ✅ Configuration system with JSON file support & profiles
• ✅ Path validator with whitelist-based security
• ✅ Drag interceptor for web-to-file conversion
• ✅ Main window with toolbar and WebEngine integration
• ✅ Windows MSIX and macOS DMG build automation
• ✅ 99+ unit tests with 85%+ coverage

Phase 4.1 (Auto-Update System - Feb 2026):

• ✅ Update manager with Forgejo API integration
• ✅ Update UI dialogs and status bar integration
• ✅ Automatic background update checking
• ✅ 76 tests, 79% coverage

Phase 4.2 (Enhanced Logging - Feb 2026):

• ✅ Structured JSON logging with rotation
• ✅ Performance metrics tracking
• ✅ Log archival with 30-day retention
• ✅ 20 tests, 91% coverage

Phase 4.3 (Advanced Configuration - Feb 2026):

• ✅ Configuration profiles (work, personal, etc.)
• ✅ Settings dialog with 5 organized tabs
• ✅ Configuration validation & import/export
• ✅ 43 tests, 87% coverage

Next Steps (Phase 5)

See DEVELOPMENT_PLAN.md Phase 5 for:

• Release candidate testing
• Cross-platform validation
• Performance optimization
• Final packaging and deployment

Common Tasks

Running Tests

# All tests
pytest tests -v

# With coverage
pytest --cov=src/webdrop_bridge

# Specific test type
pytest tests/unit/ -v           # Unit tests
pytest tests/integration/ -v    # Integration tests

Running Integration Tests

pytest tests/integration/ -v

Code Quality

# Format code
tox -e format

# Check formatting
tox -e lint

# Type checking
tox -e type

# All checks at once
tox

Building

# Windows MSI
python build/scripts/build_windows.py

# macOS DMG
bash build/scripts/build_macos.sh

Documentation

# Build Sphinx docs
tox -e docs

# View docs
open docs/_build/html/index.html  # macOS
start docs\_build\html\index.html # Windows

Using Makefile (Convenience)

# List all commands
make help

# Install dependencies
make install-dev

# Run tests
make test

# Code quality
make lint
make format
make type

# Build
make build-windows
make build-macos

# Clean
make clean

VS Code Tips

Debugging

1. Set breakpoint: Click line number
2. Start debugging: F5 (or Run → Run Without Debugging)
3. Step over: F10
4. Step into: F11

Configurations available in .vscode/launch.json:

• Python: Current File
• WebDrop Bridge (main application)

Testing in VS Code

1. Open test file: tests/unit/test_project_structure.py
2. Run test: Click "Run Test" above test function
3. Debug test: Click "Debug Test"

Recommended Extensions

• Python (ms-python.python)
• Pylance (ms-python.vscode-pylance)
• Black Formatter (ms-python.black-formatter)
• Ruff (charliermarsh.ruff)

Configuration

Create .env file from template:

cp .env.example .env

Edit as needed:

• WEBAPP_URL - Web app location
• ALLOWED_ROOTS - Whitelisted directories
• LOG_LEVEL - DEBUG, INFO, WARNING, ERROR

Next Steps

Phase 4 is complete! Here's what you can do:

To Run the Application

# Run the full application (requires config)
python -m webdrop_bridge.main

To Run Tests

# Run all tests
pytest tests -v

# Run with coverage
pytest --cov=src/webdrop_bridge tests

# Run specific test file
pytest tests/unit/test_config.py -v

To Explore Phase 4 Features

1. Auto-Update System → See src/webdrop_bridge/core/updater.py
2. Enhanced Logging → See src/webdrop_bridge/utils/logging.py
3. Configuration Profiles → See src/webdrop_bridge/core/config_manager.py
4. Settings Dialog → See src/webdrop_bridge/ui/settings_dialog.py

To Prepare for Phase 5

1. Read DEVELOPMENT_PLAN.md Phase 5
2. Review CHANGELOG.md for v1.0.0 Phase 4 additions
3. Test on multiple platforms - Windows, macOS
4. Report issues via GitHub/Forgejo issues

To Contribute

1. Review CONTRIBUTING.md
2. Choose a Phase 5 task or bug fix
3. Follow TDD - write tests first
4. Run quality checks → tox

Getting Help

• 📖 Documentation: See README.md, DEVELOPMENT_PLAN.md, docs/
• 🐛 Issues: GitHub Issues tracker
• 💬 Questions: GitHub Discussions
• 🤝 Contributing: See CONTRIBUTING.md

---

Phase 4 Complete! → Next: DEVELOPMENT_PLAN.md Phase 5 Release Candidates