# WebDrop Bridge - Project Guidelines for AI Assistants

## Project Context

WebDrop Bridge is a professional Qt-based desktop application that converts web-based drag-and-drop text paths into native file operations. It's designed for production deployment on Windows and macOS with professional-grade testing, documentation, and CI/CD.

## Architecture Overview

- **Framework**: PySide6 (Qt bindings for Python)
- **Structure**: Modular (core/, ui/, utils/)
- **Testing**: pytest with unit, integration, and fixture-based tests
- **Distribution**: PyInstaller → MSI (Windows), DMG (macOS)

## Key Files & Their Purpose

| File | Purpose |
|------|---------|
| `src/webdrop_bridge/main.py` | Application entry point |
| `src/webdrop_bridge/config.py` | Configuration management |
| `src/webdrop_bridge/core/validator.py` | Path validation and security |
| `src/webdrop_bridge/core/drag_interceptor.py` | Drag-and-drop handling |
| `src/webdrop_bridge/core/updater.py` | Update check and release management |
| `src/webdrop_bridge/ui/main_window.py` | Main Qt window |
| `tests/` | Pytest-based test suite |
| `pyproject.toml` | Modern Python packaging |
| `tox.ini` | Test automation config |

## Code Standards

### Python Style
- **Formatter**: Black (100 character line length)
- **Linter**: Ruff
- **Type Hints**: Required for all public APIs
- **Docstrings**: Google-style format

### Example
```python
def validate_path(path: Path, allowed_roots: List[Path]) -> bool:
    """Validate path against allowed roots.

    Args:
        path: File path to validate
        allowed_roots: List of allowed root directories

    Returns:
        True if path is valid, False otherwise
    """
    pass
```

## Before Making Changes

1. **Check the development plan**: See `DEVELOPMENT_PLAN.md` for current phase and priorities
2. **Understand the architecture**: Read `docs/ARCHITECTURE.md`
3. **Follow the structure**: Keep code organized in appropriate modules (core/, ui/, utils/)
4. **Write tests first**: Use TDD approach - write tests before implementing

## Making Changes

1. **Run existing tests first**: `pytest tests -v`
2. **Create test file**: `tests/unit/test_*.py`
3. **Write failing test**: Verify it fails before implementing
4. **Implement feature**: Follow code standards above
5. **Run tests**: `pytest tests -v --cov`
6. **Run quality checks**: `tox -e lint,type`
7. **Update docs**: Add docstrings and update README if needed

## Development Environment

**Virtual Environment**: `.venv` (already created)
- Activate: `.venv\Scripts\activate` (Windows) or `source .venv/bin/activate` (macOS/Linux)
- All Python commands automatically use this environment through VS Code integration

## Common Commands

```bash
# Setup (one-time)
pip install -r requirements-dev.txt

# Testing (uses .venv automatically)
pytest tests -v
pytest tests --cov=src/webdrop_bridge --cov-report=html

# Quality checks
tox -e lint      # Ruff + Black checks
tox -e type      # mypy type checking
tox -e format    # Auto-format code
tox              # All checks

# Building
python build/scripts/build_windows.py  # Windows
bash build/scripts/build_macos.sh      # macOS
```

## Important Decisions

### Path Validation
- Whitelist-based: Only allow configured root directories
- All paths resolved to absolute before checking
- Files must exist and be regular files

### Web Engine Security
- `LocalContentCanAccessFileUrls`: True (required for drag)
- `LocalContentCanAccessRemoteUrls`: False (prevent phishing)

### Update Flow
- UpdateManager checks for new releases via Forgejo API.
- Caching is used to avoid redundant network calls.
- Only newer versions trigger update signals.
- Release notes and assets are parsed and preserved.

### Cross-Platform
- Use PySide6 APIs that work on both Windows and macOS
- Test on both platforms when possible
- Mark platform-specific tests with `@pytest.mark.windows` or `@pytest.mark.macos`

## Testing Strategy

```python
# Unit tests: Isolated component testing
tests/unit/test_validator.py
tests/unit/test_drag_interceptor.py

# Integration tests: Component interaction and update flow
tests/integration/test_drag_workflow.py
tests/integration/test_end_to_end.py
tests/integration/test_update_flow.py

# Fixtures: Reusable test data
tests/conftest.py
tests/fixtures/
```

Target: 80%+ code coverage

## Performance Considerations

- Drag event handling: < 50ms total
- Application startup: < 1 second
- Memory baseline: < 200MB

## Documentation Requirements

- **Public APIs**: Docstrings required
- **Modules**: Add docstring at top of file
- **Features**: Update README.md and docs/
- **Integration tests**: Reference and document in README.md and docs/ARCHITECTURE.md
- **Breaking changes**: Update DEVELOPMENT_PLAN.md

## Git Workflow

```bash
# Create feature branch
git checkout -b feature/my-feature

# Commit message format
git commit -m "feat: add feature description

- Detailed explanation
- Bullet points for changes"

# Push to fork and create PR
git push origin feature/my-feature
```

## Review Checklist

- [ ] Tests pass (100% on CI)
- [ ] Code follows black/ruff standards
- [ ] Type hints added for public APIs
- [ ] Documentation updated
- [ ] No security concerns
- [ ] Cross-platform compatibility verified (if applicable)

## When You're Stuck

1. **Check DEVELOPMENT_PLAN.md**: Current phase and architecture decisions
2. **Look at tests**: Existing tests show expected behavior
3. **Read docstrings**: Functions document their contracts
4. **Check docs/ARCHITECTURE.md**: Design patterns and data flow

## What NOT to Do

❌ Change architecture without discussion
❌ Add dependencies without updating pyproject.toml
❌ Merge without tests passing
❌ Remove type hints or docstrings
❌ Commit without running `tox -e lint,type`
❌ Add platform-specific code without tests

## Notes for Modifications

- This is a production-quality application, not a PoC
- Code quality and testing are non-negotiable
- Cross-platform support (Windows + macOS) is required
- User security (path validation) is critical
- Documentation must keep pace with code

---

**Current Status**: Pre-release development (Phase 1-2)
**Last Updated**: January 2026