You are an expert AI developer tasked with building a single-page application (SPA) for 'Fare Kontrol: Gelişmiş Mouse Yazılımı' (Mouse Control: Advanced Mouse Software). This application aims to provide an open-source, user-friendly alternative to proprietary mouse control software like Logitech Options Plus, specifically addressing issues such as high CPU usage and unnecessary telemetry. The goal is to offer a performant, lightweight, and privacy-conscious solution for mouse customization.
**1. PROJECT OVERVIEW:**
Fare Kontrol is a desktop application designed to give users granular control over their mouse peripherals without the performance overhead and privacy concerns often associated with manufacturer-specific software. It targets users experiencing issues like high CPU consumption from background processes, battery drain on laptops, or those who simply prefer an open-source, transparent solution. The core value proposition is providing essential mouse customization features in a lightweight, efficient, and privacy-focused package, empowering users with control over their hardware and data.
**2. TECH STACK:**
- **Frontend Framework:** React.js (using Create React App or Vite for setup)
- **Styling:** Tailwind CSS for rapid UI development and utility-first styling.
- **State Management:** Zustand or Jotai for efficient and simple global state management. Given the SPA nature and potentially moderate complexity, a lightweight solution is preferred over Redux.
- **Iconography:** React Icons for a variety of icons.
- **Persistence:** LocalStorage API for saving user preferences and settings directly on the user's machine. No backend server is required for MVP.
- **Cross-Platform Compatibility:** Electron.js to package the React application into a cross-platform desktop app (Windows, macOS, Linux). This will allow direct interaction with system-level mouse settings and background process management.
- **Build Tools:** Vite (if not using CRA) for fast development server and optimized production builds.
**3. CORE FEATURES:**
* **Button Remapping:**
* **User Flow:** User navigates to the 'Button Mapping' section. They see a visual representation of their mouse (e.g., a generic 3-button mouse with scroll wheel). Each button is selectable. Clicking a button opens a modal or dropdown to select a new function. Options include: Default, Left Click, Right Click, Middle Click, Scroll Up/Down, Back, Forward, Copy, Paste, Open Application (with file picker), Disable.
* **Implementation:** This will require Electron's inter-process communication (IPC) to send commands to the main process, which will then use OS-level APIs (e.g., `node-keyboard-hook`, `global-shortcut`, or platform-specific APIs via native modules) to intercept and remap mouse events. For MVP, focus on common buttons (Left, Right, Middle, Scroll Up/Down, Back, Forward).
* **Scroll Speed & Sensitivity:**
* **User Flow:** User navigates to 'Scroll Settings'. Sliders are presented for 'Scroll Speed' (how many lines scroll per tick) and 'Pointer Sensitivity' (overall mouse movement speed). Changes are applied in real-time or upon clicking an 'Apply' button.
* **Implementation:** Again, Electron IPC will be used. The main process will need to adjust system-level mouse settings. This might involve native modules or OS-specific commands.
* **DPI Settings (Conditional):**
* **User Flow:** If the system detects a mouse model known to support DPI adjustments via software (this is complex and might be deferred post-MVP or handled via community contributions for specific models), a 'DPI Settings' section appears. A slider or predefined options (e.g., 800, 1200, 1600 DPI) are available.
* **Implementation:** This is highly hardware-dependent. For MVP, it's safer to omit or provide a placeholder stating "DPI adjustment is hardware-dependent and not supported by this basic version." If pursued, it would require specific libraries or vendor SDKs, making it less of an open-source generic solution.
* **Application-Specific Profiles:**
* **User Flow:** User goes to 'Profiles'. They can create a new profile, name it, and assign it to specific applications (e.g., 'Photoshop Profile', 'Gaming Profile'). When a selected application becomes active, the corresponding profile's button mappings and settings are automatically loaded. A button to 'Add Application' opens a file browser. A list of active profiles and their assigned applications is displayed.
* **Implementation:** The main Electron process needs to monitor active applications. When a match is found, it triggers the loading of the associated profile's configuration (stored in LocalStorage) and applies the settings via IPC.
* **Performance Optimization:**
* **User Flow:** This is an underlying principle, not a direct user-facing feature. Users should notice significantly lower CPU usage compared to Logitech software. A small, unobtrusive system tray icon indicates the application is running efficiently.
* **Implementation:** Achieved by using efficient state management, avoiding unnecessary re-renders, and optimizing the Electron main process's event listeners and background tasks. Minimize polling; use event-driven approaches where possible.
**4. UI/UX DESIGN:**
* **Layout:** Single-Page Application (SPA) with a clear navigation sidebar (or top bar). Main content area displays the settings for the selected section (e.g., Button Mapping, Scroll Settings).
* **Sidebar:** Icons and text for: Dashboard/Overview, Button Mapping, Scroll Settings, Profiles, Settings.
* **Main Content:** Card-based design for different setting groups. Use clear headings, descriptive labels, and intuitive controls (sliders, dropdowns, buttons).
* **Color Palette:** Clean, modern, and accessible. Primary: A calm blue (#3b82f6 - Tailwind's blue-500). Secondary: A neutral gray for backgrounds and borders (#f3f4f6 - Tailwind's gray-100). Accent: A subtle green for active states or success messages (#10b981 - Tailwind's green-500). Text: Dark gray/black (#1f2937 - Tailwind's gray-800). Use white for text on dark backgrounds.
* **Typography:** Sans-serif font like Inter or Poppins for readability. Use appropriate font weights (e.g., 400 for body, 600 for headings) and sizes (e.g., 16px base, 24px H1, 20px H2).
* **Responsive Design:** Primarily designed for desktop use. Ensure elements scale appropriately. No mobile view needed for MVP as it's a desktop app. Use Tailwind's responsive prefixes (sm:, md:, lg:) for adaptability within desktop resolutions.
* **Visual Elements:** Use clear icons. Visual representation of the mouse in the Button Mapping section. Progress indicators or subtle spinners for actions that take time.
**5. COMPONENT BREAKDOWN:**
* **`App.jsx`:** Main application component. Sets up routing (if using React Router, though for SPA it might be simple conditional rendering), initializes state, and renders the main layout.
* **Props:** None (manages its own state).
* **`Layout.jsx`:** Contains the main structure: Sidebar and the content area. Handles overall page layout.
* **Props:** `children` (the content to display).
* **`Sidebar.jsx`:** Navigation menu component. Displays links to different sections.
* **Props:** `activeSection` (string), `setActiveSection` (function).
* **`ButtonMapping.jsx`:** Manages the button remapping UI.
* **Props:** None (interacts with global state).
* **Sub-Components:** `MouseVisualizer.jsx` (shows mouse diagram), `ButtonSelector.jsx` (dropdown/modal for function selection).
* **`ScrollSettings.jsx`:** UI for scroll speed and sensitivity sliders.
* **Props:** None.
* **Sub-Components:** `SliderInput.jsx` (reusable slider component).
* **`ProfileManager.jsx`:** UI for creating, managing, and assigning application profiles.
* **Props:** None.
* **Sub-Components:** `ProfileCard.jsx`, `ApplicationSelector.jsx`.
* **`Settings.jsx`:** General application settings (e.g., auto-start on login, check for updates).
* **Props:** None.
* **`SystemTray.jsx` (Electron Main Process):** Manages the system tray icon and context menu.
* **Props:** None (managed in main.js).
* **`IpcHandler.js` (Electron Main Process):** Handles IPC communication between renderer and main processes.
* **Props:** None.
**6. DATA MODEL:**
* **State Structure (Zustand/Jotai):**
```javascript
{
profileName: 'Default',
buttonMappings: {
'left': 'leftClick',
'right': 'rightClick',
'middle': 'middleClick',
'scroll_up': 'scrollUp',
'scroll_down': 'scrollDown',
'side_button_1': 'forward', // Example: Logitech 'Back'
'side_button_2': 'back' // Example: Logitech 'Forward'
},
scrollSpeed: 3,
pointerSensitivity: 1.0,
profiles: [
{
id: 'profile-1',
name: 'Gaming',
appPath: '/Applications/SomeGame.app',
mappings: { /* specific mappings */ },
scrollSpeed: 5,
pointerSensitivity: 1.2
}
],
settings: {
autoStart: false,
// ... other settings
}
}
```
* **Mock Data Format:** The state structure above serves as the mock data. LocalStorage will store this object, stringified.
**7. ANIMATIONS & INTERACTIONS:**
* **Hover Effects:** Subtle background color changes or slight scaling on sidebar links and buttons when hovered.
* **Transitions:** Smooth transitions for sidebar opening/closing (if applicable), modal popups, and section changes. Use Tailwind's transition utilities (`transition-all`, `duration-300`).
* **Loading States:** For actions like applying settings or loading profiles, display a subtle spinner or progress indicator using a component like `react-spinners` or a custom SVG spinner.
* **Micro-interactions:** Visual feedback when a button mapping is successfully changed (e.g., a brief checkmark animation).
* **Real-time Updates:** Sliders should provide immediate visual feedback, potentially applying the change temporarily until a confirmation button is pressed or directly applying it if the user interaction implies finality.
**8. EDGE CASES:**
* **Empty State:** When no profiles are created, the Profile Manager section should display a message encouraging the user to create their first profile.
* **Error Handling:**
* If an application fails to launch due to a remapped button, show a non-intrusive error toast.
* If system settings cannot be changed (e.g., due to permissions), inform the user clearly.
* Handle potential errors during LocalStorage read/write operations.
* **Validation:** Ensure profile names are unique. Validate file paths for application-specific profiles.
* **Permissions:** Electron app will need appropriate permissions to control input devices and potentially auto-start on login. The app should gracefully handle cases where permissions are denied and guide the user on how to grant them.
* **Accessibility (a11y):** Use semantic HTML5 elements. Ensure sufficient color contrast. Make all interactive elements focusable and navigable via keyboard. Use ARIA attributes where necessary.
* **Multiple Mice:** For MVP, assume a single primary mouse. Handling multiple mice simultaneously would add significant complexity.
**9. SAMPLE DATA:**
* **Initial State Mock:**
```json
{
"profileName": "Default",
"buttonMappings": {
"left": "leftClick", "right": "rightClick", "middle": "middleClick",
"scroll_up": "scrollUp", "scroll_down": "scrollDown",
"side_button_1": "forward", "side_button_2": "back"
},
"scrollSpeed": 3,
"pointerSensitivity": 1.0,
"profiles": [],
"settings": {"autoStart": false}
}
```
* **Profile Mock:**
```json
{
"id": "prof-123",
"name": "Code Editor",
"appPath": "/Applications/Visual Studio Code.app",
"mappings": {
"left": "leftClick", "right": "rightClick", "middle": "middleClick",
"scroll_up": "scrollUp", "scroll_down": "scrollDown",
"side_button_1": "copy", "side_button_2": "paste"
},
"scrollSpeed": 2,
"pointerSensitivity": 0.9
}
```
* **Button Mapping Options Mock:**
```json
[
{"value": "leftClick", "label": "Left Click"},
{"value": "rightClick", "label": "Right Click"},
{"value": "copy", "label": "Copy"},
{"value": "paste", "label": "Paste"},
{"value": "openApp", "label": "Open Application", "requiresPath": true},
{"value": "disable", "label": "Disable"}
]
```
**10. DEPLOYMENT NOTES:**
* **Build Process:** Use Vite/Create React App for the React frontend build. Use Electron Forge or Electron Builder for packaging the application into installers for Windows (.exe), macOS (.dmg), and Linux (.AppImage, .deb, etc.).
* **Environment Variables:** Use `.env` files for managing build-time variables (e.g., application name, version). Electron's main process can access these.
* **Code Signing:** For distribution, especially on macOS and Windows, code signing is crucial to avoid security warnings and allow installation. This requires obtaining developer certificates.
* **Performance Optimization:**
* Code Splitting (if complexity increases beyond basic features).
* Memoization of components (`React.memo`) where appropriate.
* Efficient state updates.
* Minimize Electron main process work; offload heavy tasks if necessary (though for MVP, keep it simple).
* **Auto-Updater:** Implement an auto-updater using Electron's `autoUpdater` module for seamless updates.
* **CI/CD:** Set up a CI/CD pipeline (e.g., GitHub Actions) to automate testing, building, and releasing new versions.