Product Requirements Document: FocusTauri (v1.0)

1. Executive Summary

FocusTauri is a high-performance, cross-platform desktop application designed to eliminate digital distractions for knowledge workers, students, and creators. By leveraging the Tauri v2.9 framework, FocusTauri provides a native, low-overhead environment that combines a customizable Pomodoro timer with aggressive system-level application blocking. Unlike Electron-based competitors, FocusTauri prioritizes system efficiency (targeting <50MB RAM) and local-first data privacy, with optional cloud synchronization for multi-device workflows.

2. Problem Statement

Knowledge workers and students face a constant barrage of digital distractions (e.g., Slack, Discord, Social Media). Existing solutions are often easily bypassed (browser extensions), consume excessive system resources (Electron apps), or lack the native integration required to effectively monitor and restrict system-level processes without impacting battery life or system performance.

3. Goals & Success Metrics

• Performance: Maintain idle RAM usage under 50MB and CPU usage under 0.1% during background monitoring.
• Efficacy: Reduce unauthorized application launches during "Focus Mode" to zero.
• Retention: Achieve a 30% Week-4 retention rate through "Streak" gamification and goal setting.
• Adoption: Secure 5,000+ active users within the first 6 months across Windows, macOS, and Linux.

4. User Personas

1. The "Deep Work" Developer: Needs to block communication tools (Slack/Teams) during coding sprints but requires low CPU overhead to keep IDE performance high.
2. The Focused Student: Needs to block entertainment (YouTube/Twitch) and requires weekly analytics to track study progress.
3. The Freelance Writer: Uses "Zen Mode" to hide desktop icons and minimize distractions while drafting content.

5. User Stories

• As a user, I want to define a list of "distraction apps" so that FocusTauri can automatically close them when I start a session.
• As a power user, I want to use a system-tray flyout so that I can manage my timer without switching window contexts.
• As a privacy-conscious user, I want my session data stored in a local SQLite database so that my productivity habits aren't sold to third parties.
• As a student, I want to see a visual streak of my focused days so that I stay motivated to maintain my study habit.

6. Functional Requirements

6.1 Timer Core

• Pomodoro Logic: Support for "Work," "Short Break," and "Long Break" intervals.
• Customization: Users can modify durations and the number of cycles before a long break.
• Persistence: The timer must remain accurate if the UI is minimized or if the system enters sleep mode (leveraging Rust's monotonic clocks).

6.2 Application Blocking (High-Performance)

• Block List: A user-defined list of process names (e.g., discord.exe, Slack.app).
• Enforcement: Immediate termination or suspension of blacklisted processes upon session start and during the session.
• Detection: Use of event-driven OS hooks (NSWorkspace for Mac, WMI/ETW for Windows) to detect new process launches with zero polling overhead.

6.3 Dashboard & Analytics

• Data Visualization: Daily/Weekly/Monthly charts showing total "Focus Time."
• Session History: Searchable log of all completed and aborted sessions.
• Rust-Side Aggregation: Analytics must be calculated in the Rust backend to avoid IPC bottlenecks.

6.4 Zen Mode

• Environment Clean-up: On activation, hide all desktop icons and minimize non-essential windows.
• Native Integration: Trigger "Do Not Disturb" (macOS) or "Focus Session" (Windows 11) via native APIs.

7. Technical Requirements

7.1 Tech Stack (2026 Standards)

• Framework: Tauri v2.9.5 (utilizing the new Capability-based security model).
• Frontend: React 19 with Vite 6 and Tailwind CSS 4.
• State Management: Zustand for UI state, TanStack Query v5 for data fetching.
• Backend: Rust 1.75+.
• Database: SQLite 3.40+ via tauri-plugin-sql (WAL mode enabled).
• Auth (Optional): Supabase Auth with PKCE flow and deep linking.

7.2 Native Integrations

• System Tray: tauri-plugin-tray-icon for flyout menus.
• Notifications: tauri-plugin-notification for session end alerts.
• Deep Linking: tauri-plugin-deep-link for OAuth callbacks.
• Security: tauri-plugin-keyring for storing Supabase tokens in the OS Keychain/Credential Manager.

8. Data Model

8.1 FocusSession

| Field | Type | Description | | :--- | :--- | :--- | | id | UUID | Primary Key | | start_time | INTEGER | Unix Epoch | | end_time | INTEGER | Unix Epoch | | duration | INTEGER | Target seconds | | type | STRING | 'work' | 'break' | | status | STRING | 'completed' | 'aborted' |

8.2 BlockList

| Field | Type | Description | | :--- | :--- | :--- | | id | UUID | Primary Key | | process_name | STRING | Case-sensitive binary name | | is_active | BOOLEAN | Toggle for the rule |

9. API Specification (Tauri Commands)

start_session(duration: u32, type: SessionType)

• Request: Duration in seconds, enum for session type.
• Action: Triggers Rust-side timer and initiates event-driven process monitoring.

get_analytics_summary(period: "day" | "week")

• Response: [{ date: string, focus_minutes: number }].
• Logic: Aggregated in Rust using SQL window functions.

10. UI/UX Requirements

• Tray-First Design: The application should primarily live in the tray. Clicking the tray icon opens a small "Flyout" (using tauri-plugin-positioner).
• React 19 Patterns: Use <Activity mode="hidden" /> for the analytics dashboard to ensure instant tab switching without background re-renders.
• Visual Feedback: Use a progress ring in the tray icon (dynamic SVG) to show remaining time at a glance.

11. Non-Functional Requirements

• Performance: Memory footprint must stay <50MB RSS during idle.
• Security: Define granular permissions in src-tauri/capabilities/main.json. No allow-all permissions.
• Offline First: The app must be fully functional without an internet connection.
• Accessibility: Support keyboard shortcuts (e.g., Cmd+Shift+F) to start/stop sessions and full screen-reader support for the timer.

12. Out of Scope

• Native Mobile Apps (Android/iOS) - deferred to v2.0.
• Web-based Dashboard (Local-first only for v1.0).
• Direct Spotify/Apple Music playback controls (External integration only).

13. Risks & Mitigations

| Risk | Severity | Mitigation | | :--- | :--- | :--- | | Process blocking bypassed by renaming .exe | Medium | Monitor process hash/signature (v1.5) or block by window title. | | OS Updates breaking ETW/WMI hooks | Low | Fallback to optimized sysinfo polling every 2 seconds. | | High IPC overhead with large history | Medium | Perform all data heavy-lifting in Rust; return only summarized JSON. |

14. Implementation Tasks

Phase 1: Project Setup

• [ ] Initialize project with Tauri v2.9.5 and React 19.
• [ ] Configure Tailwind CSS 4 and Vite 6.
• [ ] Set up tauri-plugin-sql and initialize SQLite migrations.
• [ ] Define capabilities JSON to restrict command access.

Phase 2: Core Timer & Tray

• [ ] Implement Rust-side monotonic timer logic.
• [ ] Build the System Tray flyout with tauri-plugin-tray-icon.
• [ ] Integrate tauri-plugin-positioner for tray-snapping.
• [ ] Implement native notifications for session completion.

Phase 3: High-Performance Blocking

• [ ] Implement Windows ETW / WMI event listener for process launches.
• [ ] Implement macOS NSWorkspaceDidLaunchApplicationNotification listener.
• [ ] Create Rust Command to "Suspend" or "Kill" processes from the BlockList.
• [ ] Optimize sysinfo fallback for Linux (Netlink Connector).

Phase 4: Dashboard & Analytics

• [ ] Implement React 19 <Activity /> for dashboard tab management.
• [ ] Write Rust-side SQL aggregators for daily/weekly metrics.
• [ ] Build chart components using Recharts or D3 (with useTransition for smoothness).
• [ ] Implement "Streak" logic in SQLite.

Phase 5: Zen Mode & Polish

• [ ] Implement IFolderView2 COM interface to hide Windows icons.
• [ ] Implement NSUserDefaults toggle for macOS Finder icon visibility.
• [ ] Add tauri-plugin-keyring for secure token storage.
• [ ] Conduct memory leak audit to ensure <50MB target.