PROJECT OVERVIEW:
The project is a single-page web application called 'Otomatikleştir' (Automate), designed to empower macOS users by providing a user-friendly interface for creating and managing complex system automations without requiring traditional coding knowledge. It bridges the gap between powerful scripting engines like Lua (as seen in Hammerspoon) and the average user. The core value proposition is to significantly enhance user productivity on macOS by simplifying the creation of custom workflows, automating repetitive tasks, and providing intuitive control over the operating system's functionalities.
TECH STACK:
- Frontend Framework: React.js (with Create React App or Vite for a modern setup)
- Styling: Tailwind CSS for rapid UI development and utility-first styling.
- State Management: Zustand for efficient and simple global state management.
- Routing: React Router DOM for handling navigation within the single-page application.
- Icons: React Icons for a wide variety of SVG icons.
- UI Components: Potentially a lightweight component library like Headless UI or Radix UI for accessibility and unstyled primitives, allowing deep customization with Tailwind CSS.
- Local Storage: For persisting user preferences, automation drafts, and settings locally in the browser.
- Potentially a backend (for future scaling, e.g., user accounts, cloud sync): Node.js with Express.js and a database like PostgreSQL or MongoDB. (MVP will focus on local-first).
- Build Tool: Vite (preferred for speed) or Webpack.
CORE FEATURES & USER FLOW:
1. **Dashboard**: The landing page after login/initial load. Displays a list of user-created automations, quick access to create new ones, and potentially a feed of popular community templates. User flow: User lands on Dashboard -> sees existing automations -> clicks 'Create New Automation' or browses templates.
2. **Automation Builder (Visual/Low-Code)**: A drag-and-drop interface or a guided workflow builder allowing users to chain actions. For example: Trigger (e.g., Keyboard Shortcut 'Cmd+Alt+A') -> Action 1 (e.g., 'Focus Window Title Containing "Project"') -> Action 2 (e.g., 'Move Window to Monitor 2, Position Top-Left') -> Action 3 (e.g., 'Launch Application "Terminal"'). User flow: User enters Builder -> selects Trigger type -> adds/configures Actions sequentially -> saves automation.
3. **Template Library**: A curated collection of pre-built automation recipes users can import and customize. Categories could include Window Management, File Operations, Application Launching, System Settings, etc. User flow: User navigates to Template Library -> browses/searches for a template -> clicks 'Import' -> template appears in their automations list ready for customization.
4. **Automation Editor (Code - Lua)**: For advanced users, a code editor interface (like Monaco Editor or CodeMirror) where they can directly write, edit, and debug Lua scripts that interact with macOS APIs exposed by the Hammerspoon-like engine. User flow: User selects an existing automation -> switches to 'Code Editor' view -> writes/modifies Lua script -> saves changes -> tests script.
5. **Settings**: User preferences, theme selection (light/dark), shortcut key management, link to documentation and support.
UI/UX DESIGN:
- **Layout**: A clean, modern, and intuitive dashboard layout. Sidebar navigation for Dashboard, Automation Builder, Template Library, Settings. Main content area displays relevant information. Emphasis on clarity and ease of use, especially in the visual builder.
- **Color Palette**: Primary: A professional, calming blue (#4A90E2). Secondary: A neutral gray (#F5F5F5 for background, #A0A0A0 for secondary text). Accent: A vibrant green (#50E3C2) or orange for calls-to-action and highlights. Dark mode variant available.
- **Typography**: Use a clean, readable sans-serif font like Inter or Poppins for headings and body text. Ensure good hierarchy and legibility.
- **Responsive Design**: Primarily designed for desktop use on macOS. However, the interface should be responsive enough to adapt to different screen sizes and resolutions gracefully. Key interactions should remain accessible.
- **Visual Builder Aesthetics**: Use clear icons for actions, logical flow connectors, and intuitive controls for configuration.
COMPONENT BREAKDOWN:
- **`App.jsx`**: Main application component, sets up routing and global layout.
- **`Sidebar.jsx`**: Navigation component with links to different app sections.
- **`Dashboard.jsx`**: Displays user's automations, provides 'Create New' button.
- `AutomationList.jsx`: Renders a list of `AutomationCard` components.
- `AutomationCard.jsx`: Displays individual automation details (name, trigger, actions summary), provides edit/delete options. Props: `automation` (object), `onEdit` (function), `onDelete` (function).
- **`AutomationBuilder.jsx`**: The core visual editor.
- `TriggerSelector.jsx`: Component to choose the automation trigger.
- `ActionList.jsx`: Displays currently added actions.
- `ActionItem.jsx`: Represents a single action in the builder, allows configuration/reordering/deletion. Props: `action` (object), `index` (number), `onConfigure` (function), `onDelete` (function), `onMove` (function).
- `ActionPalette.jsx`: Drawer/panel showing available actions to drag and drop.
- **`CodeEditor.jsx`**: Integrates a code editor (e.g., Monaco Editor) for Lua scripting.
- Props: `initialCode` (string), `onChange` (function).
- **`TemplateLibrary.jsx`**: Displays available automation templates.
- `TemplateCard.jsx`: Displays individual template details, provides 'Import' button.
- **`Settings.jsx`**: User settings and preferences page.
- **`Modal.jsx`**: Generic modal component for confirmations or detailed configuration.
DATA MODEL (using Zustand for global state):
- **`automationStore`**: { automations: Automation[], activeAutomationId: string | null, addAutomation: (auto: Automation) => void, updateAutomation: (id: string, updates: Partial<Automation>) => void, deleteAutomation: (id: string) => void, setActiveAutomation: (id: string | null) => void }
- **`Automation` interface**: { id: string, name: string, enabled: boolean, trigger: Trigger, actions: Action[], script?: string // for code editor view }
- **`Trigger` interface**: { type: 'shortcut' | 'time' | 'app_launch' | 'manual', config: ShortcutConfig | TimeConfig | AppLaunchConfig | ManualConfig }
- **`Action` interface**: { id: string, type: string, config: any } // e.g., { type: 'move_window', config: { monitor: 'primary', position: 'top-left', size: '50%' } }
- **`uiStore`**: { isDarkMode: boolean, sidebarCollapsed: boolean, setDarkMode: (isDark: boolean) => void }
MOCK DATA FORMATS:
- **Automation Object**: `{ "id": "uuid-123", "name": "Organize Desktop", "enabled": true, "trigger": { "type": "shortcut", "config": { "keys": ["cmd", "alt", "o"] } }, "actions": [ { "id": "action-abc", "type": "move_files", "config": { "source_folder": "~/Desktop", "destination_folder": "~/Documents/Organized", "rules": "*.png -> Images/" } } ] }`
- **Template Object**: `{ "id": "template-xyz", "name": "Focus Mode Window Manager", "description": "Quickly arrange windows for focused work.", "trigger": { "type": "shortcut", "config": { "keys": ["cmd", "shift", "f"] } }, "actions": [ ... ] }`
ANIMATIONS & INTERACTIONS:
- **Page Transitions**: Subtle fade or slide transitions between major sections using React Router's `TransitionGroup` or similar techniques.
- **Hover Effects**: Slight scaling or background color changes on interactive elements like buttons and cards.
- **Loading States**: Skeleton loaders or spinners when fetching templates or saving automations.
- **Micro-interactions**: Visual feedback when adding/removing/reordering actions in the builder. Button press animations. Smooth expand/collapse for accordions or drawers.
- **Drag and Drop**: Visual cues during drag-and-drop in the builder (e.g., ghost element, drop zone highlighting).
EDGE CASES:
- **Empty States**: Dashboard shows a welcoming message and a prominent 'Create New' button if no automations exist. Template library shows a 'No templates found' message if search yields no results.
- **Error Handling**: Graceful error handling for API calls (if backend is introduced) or issues during automation execution. Display user-friendly error messages. Validation for trigger/action configurations (e.g., ensure required fields are filled, shortcut keys are unique).
- **Automation Conflicts**: Implement checks or warnings for potentially conflicting shortcut keys.
- **macOS Permissions**: Guide users on necessary macOS permissions (e.g., Accessibility, Automation) required for certain actions.
- **Local Storage Full/Unavailable**: Handle cases where local storage might be full or disabled.
- **Accessibility (a11y)**: Use semantic HTML, ARIA attributes where necessary, ensure keyboard navigability, sufficient color contrast, and screen reader compatibility.
SAMPLE DATA (Mock):
1. **Automation 1 (Dashboard)**: `{ "id": "auto-001", "name": "Daily Report Organizer", "enabled": true, "trigger": { "type": "time", "config": { "time": "09:00", "days": ["Mon", "Tue", "Wed", "Thu", "Fri"] } }, "actions": [ { "id": "act-001a", "type": "open_folder", "config": { "path": "~/Documents/DailyReports" } }, { "id": "act-001b", "type": "run_script", "config": { "script_content": "print('Daily reports opened')" } } ] }`
2. **Automation 2 (Dashboard)**: `{ "id": "auto-002", "name": "Code Snippet Launcher", "enabled": false, "trigger": { "type": "shortcut", "config": { "keys": ["cmd", "shift", "c"] } }, "actions": [ { "id": "act-002a", "type": "launch_app", "config": { "app_path": "/Applications/Visual Studio Code.app" } } ] }`
3. **Template 1 (Library)**: `{ "id": "tmpl-win01", "name": "Quadrant Window Split", "description": "Divides the screen into four equal quadrants.", "trigger": { "type": "shortcut", "config": { "keys": ["cmd", "alt", "q"] } }, "actions": [ { "id": "act-tmpl01a", "type": "resize_window", "config": { "position": "top-left", "size": "50% 50%" } }, { "id": "act-tmpl01b", "type": "resize_window", "config": { "position": "top-right", "size": "50% 50%" } }, { "id": "act-tmpl01c", "type": "resize_window", "config": { "position": "bottom-left", "size": "50% 50%" } }, { "id": "act-tmpl01d", "type": "resize_window", "config": { "position": "bottom-right", "size": "50% 50%" } } ] }`
4. **Template 2 (Library)**: `{ "id": "tmpl-file01", "name": "Download Folder Cleaner", "description": "Moves old files from Downloads to Archived.", "trigger": { "type": "manual" }, "actions": [ { "id": "act-tmpl02a", "type": "move_files", "config": { "source_folder": "~/Downloads", "destination_folder": "~/Archive/Downloads", "rules": "*.pdf, *.zip -> Old/" } }, { "id": "act-tmpl02b", "type": "notify", "config": { "message": "Downloads folder cleaned.", "title": "Cleaner Bot" } } ] }`
5. **Automation Example (Code View)**: `{ "id": "auto-003", "name": "Custom Script Example", "enabled": true, "trigger": { "type": "shortcut", "config": { "keys": ["cmd", "." ] } }, "script": "local currentWindow = hs.window.focusedWindow()\nif currentWindow then\n local title = currentWindow:title()\n hs.alert.show('Focused window: ' .. title)\nelse\n hs.alert.show('No window focused')\nend" }`
6. **Configuration for 'Move Window' Action**: `{ "type": "move_window", "config": { "target_window_identifier": "window_title_regex: '.*Untitled.*'", "monitor": "2", "position": "top-right", "size": "40% 60%" } }`
7. **Configuration for 'Send Notification' Action**: `{ "type": "notify", "config": { "title": "Task Reminder", "message": "Remember to follow up on the project proposal." } }`
DEPLOYMENT NOTES:
- **Build Configuration**: Use Vite's production build command (`npm run build` or `yarn build`). Ensure `base` path is correctly set if deploying to a subdirectory.
- **Environment Variables**: Utilize `.env` files for managing environment variables (e.g., `NODE_ENV`, API keys if a backend is used). Ensure sensitive variables are not hardcoded.
- **Performance Optimizations**: Code splitting with React.lazy and Suspense for efficient loading. Image optimization. Memoization using `React.memo` and `useMemo`/`useCallback` where appropriate. Minimize re-renders.
- **Static Site Hosting**: Suitable for hosting on platforms like Netlify, Vercel, GitHub Pages, or AWS S3/CloudFront for the frontend MVP.
- **Cross-Platform Considerations**: While targeting macOS, ensure the UI elements and interactions are standard web technologies. Future integration with a native macOS app or helper service would be needed for full system control, script execution.
- **Error Tracking**: Integrate a service like Sentry for monitoring runtime errors in production.