update documentation

docs/ARCHITECTURE.md

@@ -36,10 +36,11 @@
 
 **Key Components:**
 
-- `validator.py`: Path validation against whitelist
-- `drag_interceptor.py`: Drag event handling and conversion
-- `config.py`: Configuration management
-- `errors.py`: Custom exception classes
+- `validator.py`: Path validation against whitelist with security checks
+- `drag_interceptor.py`: Drag event handling and native drag operations
+- `config_manager.py`: Configuration loading from files and caching
+- `url_converter.py`: Azure Blob Storage URL → local path conversion
+- `updater.py`: Update checking via Forgejo API
 
 **Dependencies**: None (only stdlib + pathlib)
 
@@ -49,9 +50,12 @@
 
 **Key Components:**
 
-- `main_window.py`: Main application window
-- `widgets.py`: Reusable custom widgets
-- `styles.py`: UI styling and themes
+- `main_window.py`: Main application window with web engine integration
+- `restricted_web_view.py`: Hardened QWebEngineView with security policies
+- `settings_dialog.py`: Settings UI for configuration
+- `update_manager_ui.py`: Update checking and notification UI
+- `bridge_script_intercept.js`: JavaScript drag interception and WebChannel bridge for Qt communication
+- `download_interceptor.js`: Download handling for web content
 
 **Dependencies**: PySide6, core/
 
@@ -61,9 +65,7 @@
 
 **Key Components:**
 
-- `logging.py`: Logging configuration
-- `constants.py`: Application constants
-- `helpers.py`: General-purpose helper functions
+- `logging.py`: Logging configuration (console + file with rotation)
 
 **Dependencies**: stdlib only
 
@@ -72,34 +74,57 @@
 ### Drag-and-Drop Operation
 
 ```
-User in Web App
+User in Web App (browser)
     ↓
-[dragstart event] → JavaScript sets dataTransfer.text = "Z:\path\file.txt"
+[dragstart event] → bridge_script_intercept.js detects drag
+    ├─ Checks if content is convertible (file path or Azure URL)
+    ├─ Calls window.bridge.start_file_drag(url)
+    └─ preventDefault() → Blocks normal browser drag
+    
     ↓
-[dragend event] → Drag leaves WebEngine widget
+JavaScript → QWebChannel Bridge
     ↓
-DragInterceptor.dragEnterEvent() triggered
+_DragBridge.start_file_drag(path_text) [main_window.py]
+    ├─ Defers execution via QTimer (drag manager safety)
+    └─ Calls DragInterceptor.handle_drag()
+    
     ↓
-Extract text from QMimeData
+DragInterceptor.handle_drag() [core/drag_interceptor.py]
+    ├─ Check if Azure URL: Use URLConverter → local path
+    ├─ Else: Treat as direct file path
+    └─ Validate with PathValidator
+    
     ↓
-PathValidator.is_valid_file(path)
-    ├─ is_allowed(path) → Check whitelist
-    └─ path.exists() and path.is_file() → File system check
+PathValidator.validate(path)
+    ├─ Resolve to absolute path
+    ├─ Check file exists (if configured)
+    ├─ Check is regular file (not directory)
+    └─ Check path within allowed_roots (whitelist)
+    
     ↓
 If valid:
     → Create QUrl.fromLocalFile(path)
-    → Create new QMimeData with URLs
-    → QDrag.exec() → Native file drag
+    → Create QMimeData with file URL
+    → QDrag.exec(Qt.CopyAction) → Native file drag
+    → Emit drag_started signal
     ↓
 If invalid:
-    → event.ignore()
-    → Log warning
+    → Emit drag_failed signal with error
+    → Log validation error
     ↓
 OS receives native file drag
     ↓
-InDesign/Word receives file handle
+Target application (InDesign/Word) receives file handle
 ```
 
+**Key Components in Data Flow:**
+
+1. **bridge_script_intercept.js**: Opens a WebChannel to Qt's _DragBridge
+2. **_DragBridge**: Exposes `start_file_drag()` slot to JavaScript
+3. **DragInterceptor**: Handles validation and native drag creation
+4. **URLConverter**: Maps Azure Blob Storage URLs to local paths via config
+5. **PathValidator**: Security-critical validation against whitelist
+
 ## Security Model
 
 ### Path Validation Strategy