# Quick Start Guide

## Project Setup (5 minutes)

### 1. Open in VS Code

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

# Option B: Open the folder
code .
```

### 2. Install Dependencies

```bash
# 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

```bash
# 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](DEVELOPMENT_PLAN.md#phase-5-post-release-months-2-3) for:
- Release candidate testing
- Cross-platform validation
- Performance optimization
- Final packaging and deployment

## Common Tasks

### Running Tests

```bash
# 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

```bash
pytest tests/integration/ -v
```

### Code Quality

```bash
# Format code
tox -e format

# Check formatting
tox -e lint

# Type checking
tox -e type

# All checks at once
tox
```

### Building

```bash
# Windows MSI
python build/scripts/build_windows.py

# macOS DMG
bash build/scripts/build_macos.sh
```

### Documentation

```bash
# 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)

```bash
# 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:

```bash
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
```bash
# Run the full application (requires config)
python -m webdrop_bridge.main
```

### To Run Tests
```bash
# 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](DEVELOPMENT_PLAN.md#phase-5-post-release-months-2-3)
2. **Review** [CHANGELOG.md](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](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](DEVELOPMENT_PLAN.md#phase-5-post-release-months-2-3) Release Candidates