Travis Vasceannie
af1285b181
- Introduced .python-version for Python version management. - Added AGENTS.md for documentation on agent usage and best practices. - Created alembic.ini for database migration configurations. - Implemented main.py as the entry point for the application. - Established pyproject.toml for project dependencies and configurations. - Initialized README.md for project overview. - Generated uv.lock for dependency locking. - Documented milestones and specifications in docs/milestones.md and docs/spec.md. - Created logs/status_line.json for logging status information. - Added initial spike implementations for UI tray hotkeys, audio capture, ASR latency, and encryption validation. - Set up NoteFlow core structure in src/noteflow with necessary modules and services. - Developed test suite in tests directory for application, domain, infrastructure, and integration testing. - Included initial migration scripts in infrastructure/persistence/migrations for database setup. - Established security protocols in infrastructure/security for key management and encryption. - Implemented audio infrastructure for capturing and processing audio data. - Created converters for ASR and ORM in infrastructure/converters. - Added export functionality for different formats in infrastructure/export. - Ensured all new files are included in the repository for future development.
4.5 KiB
4.5 KiB
Spike 1: UI + Tray + Hotkeys - FINDINGS
Status: Implementation Complete, Requires Display Server
System Requirements
X11 or Wayland display server is required for pystray and pynput:
# pystray on Linux requires X11 or GTK AppIndicator
# pynput requires X11 ($DISPLAY must be set)
# Running from terminal with display:
export DISPLAY=:0 # If not already set
python -m spikes.spike_01_ui_tray_hotkeys.demo
Implementation Summary
Files Created
protocols.py- Defines TrayController, HotkeyManager, Notifier protocolstray_impl.py- PystrayController implementation with icon stateshotkey_impl.py- PynputHotkeyManager for global hotkeysdemo.py- Interactive Flet + pystray demo
Key Design Decisions
- Flet for UI: Modern Python UI framework with hot reload
- pystray for Tray: Cross-platform system tray (separate thread)
- pynput for Hotkeys: Cross-platform global hotkey capture
- Queue Communication: Thread-safe event passing between tray and UI
Architecture: Flet + pystray Integration
┌─────────────────────────────────────────┐
│ Main Thread │
│ ┌─────────────────────────────────┐ │
│ │ Flet Event Loop │ │
│ │ - UI rendering │ │
│ │ - Event polling (100ms) │ │
│ │ - State updates │ │
│ └─────────────────────────────────┘ │
│ ▲ │
│ │ Queue │
│ │ │
└───────────────────┼─────────────────────┘
│
┌───────────────────┼─────────────────────┐
│ ┌────────────────▼────────────────┐ │
│ │ Event Queue │ │
│ │ - "toggle" -> toggle state │ │
│ │ - "quit" -> cleanup + exit │ │
│ └────────────────┬────────────────┘ │
│ │ │
│ ┌────────────────┴────────────────┐ │
│ │ pystray Thread (daemon) │ │
│ │ pynput Thread (daemon) │ │
│ │ - Tray icon & menu │ │
│ │ - Global hotkey listener │ │
│ └─────────────────────────────────┘ │
│ Background Threads │
└─────────────────────────────────────────┘
Exit Criteria Status
- Protocol definitions complete
- Implementation complete
- Flet window opens and displays controls (requires display)
- System tray icon appears on Linux (requires X11)
- Tray menu has working items (requires X11)
- Global hotkey works when window not focused (requires X11)
- Notifications display (requires X11)
Cross-Platform Notes
- Linux: Requires X11 or AppIndicator; Wayland support limited
- macOS: Requires Accessibility permissions for global hotkeys
- System Preferences > Privacy & Security > Accessibility
- Add Terminal or the app to allowed list
- Windows: Should work out of box
Running the Demo
With a display server running:
python -m spikes.spike_01_ui_tray_hotkeys.demo
Features:
- Flet window with Start/Stop recording buttons
- System tray icon (gray = idle, red = recording)
- Global hotkey: Ctrl+Shift+R to toggle
- Notifications on state changes
Known Limitations
- pystray Threading: Must run in separate thread, communicate via queue
- pynput on macOS: Marked "experimental" - may require Accessibility permissions
- Wayland: pynput only receives events from X11 apps via Xwayland
Next Steps
- Test with X11 display server
- Verify cross-platform behavior
- Add window hide-to-tray functionality
- Implement notification action buttons