PROJECT OVERVIEW:
Develop a single-page application (SPA) called 'Apfel' designed for macOS users. Apfel aims to enhance user productivity by leveraging local AI capabilities directly on the user's machine. It allows users to interact with their system using natural language commands to perform tasks such as finding files, launching applications, and processing text. The core value proposition is to provide a seamless, intuitive, and private AI assistant that works offline, reducing reliance on cloud-based services for everyday computing tasks. The application should feel like an integrated part of the macOS experience, offering speed and efficiency without compromising user data privacy.
TECH STACK:
- Frontend Framework: React (using Vite for fast development)
- Styling: Tailwind CSS for utility-first styling and rapid UI development.
- State Management: Zustand for efficient and straightforward state management.
- Icons: Lucide React for a comprehensive set of open-source icons.
- Local AI Integration: Utilize a suitable local AI model library (e.g., Ollama, or a WebAssembly-based model if feasible for direct browser integration, though for desktop, Node.js with native bindings might be more robust). For this prompt, we'll assume an abstraction layer that communicates with a local AI service running on the user's machine.
- UI Components: Radix UI for accessible and unstyled primitives, which will be styled with Tailwind CSS.
CORE FEATURES:
1. **Natural Language Command Input:**
* **User Flow:** The user types a command in natural language (e.g., "Find all PDF files created last week", "Summarize this document", "Open VS Code and create a new React project"). The input is processed by the AI. The system identifies the intent (file search, app launch, text processing) and required parameters.
* **Details:** A prominent input field at the center or bottom of the screen. Real-time suggestions or command history might be shown as the user types. Input validation and error feedback are crucial.
2. **File Search & Management:**
* **User Flow:** User issues a command like "Search for 'report.docx' in my Documents folder". Apfel scans the specified directories (or the entire system if not specified) using the local AI's understanding of file metadata and content (if indexed).
* **Details:** Results are displayed in a list format, showing file name, path, last modified date, and potentially a snippet of the content. Actions like opening the file, revealing in Finder, or copying its path should be available.
3. **Application Launch & Control:**
* **User Flow:** User commands, "Launch Safari", "Open System Settings", or "Start a new email in Mail". Apfel identifies the application and executes the corresponding system command.
* **Details:** Requires integration with the operating system's application launching mechanism. For more advanced control (like composing an email), it might open the app with pre-filled information or interact with app-specific APIs if available.
4. **Text Summarization & Explanation:**
* **User Flow:** User selects text from any application (e.g., a webpage, a document) and uses a shortcut or command like "Summarize selected text" or "Explain this concept". The selected text is sent to the local AI model for processing.
* **Details:** The AI returns a concise summary or explanation, which is displayed in a pop-up or a dedicated panel within Apfel. The model should be capable of handling different levels of complexity.
5. **Command History & Snippets:**
* **User Flow:** Users can view their past commands and reuse them. They can also save frequently used or complex commands as 'snippets' for quick access.
* **Details:** A dedicated section or modal to browse, search, and manage command history and saved snippets.
UI/UX DESIGN:
- **Layout:** A clean, minimalist, single-page layout. A central command input area. A collapsible sidebar or panel for history, settings, and snippets. Results are displayed dynamically, often in a modal or a dedicated results panel.
- **Color Palette:** Primarily dark mode with accents of a calming, tech-oriented color (e.g., a shade of blue or teal). Use subtle gradients and shadows for depth. Ensure high contrast for readability.
- **Typography:** Modern, sans-serif font (e.g., Inter, SF Pro). Clear hierarchy using font weights and sizes. Body text should be easily readable, and UI elements should be clearly labeled.
- **Responsive Design:** While primarily desktop-focused, the UI should adapt gracefully to different screen resolutions on macOS. Ensure touch targets are adequately sized if used on a trackpad or touch-enabled device.
- **Visual Feedback:** Use subtle animations and loading indicators to provide feedback on AI processing or system actions.
COMPONENT BREAKDOWN:
- `App.jsx`: Main application component, sets up layout, routing (if needed for settings), and global state providers.
* Props: None
* Responsibilities: Overall app structure, rendering main components.
- `CommandInput.jsx`: The primary input field for natural language commands.
* Props: `onSubmitCommand`, `isLoading`
* Responsibilities: Capturing user input, handling submission, displaying loading state.
- `ResultsDisplay.jsx`: Component to show the output of the AI command (file list, summarized text, etc.).
* Props: `results`, `resultType` (e.g., 'files', 'text', 'apps')
* Responsibilities: Rendering different types of results based on `resultType`, displaying actions for each result item.
- `HistoryPanel.jsx`: Displays the list of past commands.
* Props: `commands`, `onCommandSelect`
* Responsibilities: Listing commands, allowing selection to repaste or re-execute.
- `SettingsPanel.jsx`: For configuring application settings (AI model path, directories to index, etc.).
* Props: `settings`, `onSettingsChange`
* Responsibilities: Managing user preferences and application configuration.
- `ResultItem.jsx`: Renders a single item within the results list (e.g., a file, an app suggestion).
* Props: `item`, `type`
* Responsibilities: Displaying details of a single result and associated actions.
- `IconButton.jsx`: Reusable button component with an icon.
* Props: `icon`, `onClick`, `label`
* Responsibilities: Consistent button styling and interaction.
DATA MODEL:
- **State Structure (Zustand Store):**
```javascript
{
inputQuery: '',
isProcessing: false,
results: [],
resultType: null, // 'files', 'apps', 'text', 'error'
history: [], // Array of command objects { id, query, timestamp, processedResult }
snippets: [], // Array of snippet objects { id, name, command }
settings: {
aiModelPath: '/path/to/local/model', // Placeholder
indexedDirectories: ['~/Documents', '~/Downloads'],
privacyMode: 'local-only' // 'local-only', 'cloud-sync-optional'
}
}
```
- **Mock Data Formats:**
* **File Result:** `{ id: 'file-1', name: 'report_final.docx', path: '/Users/user/Documents/report_final.docx', modifiedDate: '2023-10-27T10:00:00Z', type: 'file', snippet: 'Final version of the Q3 report...'}`
* **App Result:** `{ id: 'app-1', name: 'Finder', path: '/System/Library/CoreServices/Finder.app', type: 'app'}`
* **Text Result:** `{ id: 'text-1', summary: 'This is a concise summary of the provided text...', originalText: 'Long original text...'}`
* **History Item:** `{ id: 'hist-1', query: 'Find my project files', timestamp: '2023-10-27T11:30:00Z', processedResult: { type: 'files', data: [...] } }`
* **Snippet:** `{ id: 'snip-1', name: 'New React App', command: 'npx create-react-app my-app' }`
ANIMATIONS & INTERACTIONS:
- **Input Focus:** Subtle glow effect on the command input field when focused.
- **Processing Indicator:** A smooth pulsing animation on an icon or text near the input field when `isProcessing` is true.
- **Result Appearance:** New results fade in or slide up gently into the results area.
- **Hover Effects:** Buttons and clickable items in the results list have subtle background color changes or scale-up effects on hover.
- **Transitions:** Smooth transitions between different states (e.g., loading to loaded, showing/hiding panels).
- **Command Execution Feedback:** Visual confirmation (e.g., a checkmark animation) upon successful execution of a command.
EDGE CASES:
- **No Results Found:** Display a clear message like "No results found for your query."
- **AI Model Not Found/Ready:** Inform the user if the local AI model is not accessible and provide guidance on how to set it up or point to the correct path in settings.
- **Permissions Errors:** Handle cases where Apfel might not have permission to access certain files or launch applications. Prompt the user for necessary permissions.
- **Empty Input:** Prevent submitting an empty command.
- **Ambiguous Commands:** If a command is unclear, the AI could prompt the user for clarification instead of guessing.
- **Error Handling:** Gracefully catch and display errors from the AI model or system interactions. Log errors for debugging.
- **Accessibility (a11y):** Ensure all interactive elements are keyboard navigable. Use ARIA attributes where necessary. Maintain sufficient color contrast. Provide alternative text for icons where appropriate.
SAMPLE DATA:
1. `{ id: 'file-101', name: 'apfel_concept_v2.md', path: '/Users/arthur/Documents/Projects/Apfel/docs/apfel_concept_v2.md', modifiedDate: '2023-10-26T14:30:00Z', type: 'file', snippet: 'Detailed concept document for the Apfel AI assistant...'}`
2. `{ id: 'app-55', name: 'Terminal', path: '/Applications/Utilities/Terminal.app', type: 'app' }`
3. `{ id: 'text-202', summary: 'The user wants to find files modified this week related to 'budget'. The system should scan the Documents and Projects directories.', originalText: 'Hey Apfel, can you find all budget-related files I worked on this week?' }`
4. `{ id: 'hist-5', query: 'Show me screenshots from yesterday', timestamp: '2023-10-26T18:05:00Z', processedResult: { type: 'files', data: [ { id: 'file-102', name: 'screenshot_2023-10-26_1530.png', path: '/Users/arthur/Pictures/Screenshots/screenshot_2023-10-26_1530.png', modifiedDate: '2023-10-26T15:30:00Z', type: 'file' } ] } }`
5. `{ id: 'snip-3', name: 'Git Clone Repo', command: 'git clone {{url}}' }`
6. `{ id: 'file-103', name: 'resume_latest.pdf', path: '/Users/arthur/Documents/resume_latest.pdf', modifiedDate: '2023-09-15T09:00:00Z', type: 'file', snippet: 'Current professional resume.' }`
7. `{ id: 'app-60', name: 'Notes', path: '/System/Applications/Notes.app', type: 'app' }`
8. `{ id: 'text-203', summary: 'Summary of the Hacker News post about Apfel, highlighting its local AI capabilities and privacy benefits.', originalText: 'Show HN: Apfel – The free AI already on your Mac...' }`
9. `{ id: 'file-104', name: 'invoice_october.pdf', path: '/Users/arthur/Documents/Invoices/invoice_october.pdf', modifiedDate: '2023-10-01T11:00:00Z', type: 'file', snippet: 'Invoice for October services.' }`
10. `{ id: 'hist-6', query: 'Open VS Code', timestamp: '2023-10-27T09:15:00Z', processedResult: { type: 'app', data: [ { id: 'app-1', name: 'Visual Studio Code', path: '/Applications/Visual Studio Code.app' } ] } }`
DEPLOYMENT NOTES:
- **Build Tool:** Vite is recommended for its speed and ease of configuration.
- **Environment Variables:** Use `.env` files to manage configurations like the path to the local AI service or API keys if any cloud features are added later. `VITE_AI_SERVICE_URL` could be an example.
- **Local AI Service:** The prompt assumes a separate local AI service is running. The React app communicates with this service via a local HTTP API (e.g., running on `http://localhost:11434` if using Ollama). Instructions for setting up and running the local AI backend should be provided separately or in documentation.
- **Performance:** Optimize bundle size. Use code splitting if the app grows significantly. Ensure efficient state updates using Zustand. Lazy load components where appropriate.
- **Packaging:** For distribution on macOS, consider packaging the application using tools like Electron, Tauri, or native Node.js packaging to bundle the React app with the necessary local AI runtime or integration layer.
- **Error Reporting:** Integrate a simple error reporting mechanism for uncaught exceptions, especially during AI processing or system calls.