PROJECT OVERVIEW:
The project is to develop a single-page application (SPA) for a smart desk designed for individuals who work from home with cats. The core problem addressed is the disruption and space invasion cats often cause in their owners' home workspaces. The 'Neko House Desk' concept, though physical, inspires a software solution that complements a smart desk. Our application aims to provide a seamless experience for managing the smart desk's features, monitoring the cat's interaction with the workspace, and ensuring a harmonious work-from-home environment for both owner and feline. The value proposition lies in enhancing productivity, maintaining workspace order, and strengthening the human-animal bond through thoughtful technology integration.
TECH STACK:
- Frontend Framework: React (using Create React App for simplicity in this SPA context)
- Styling: Tailwind CSS for rapid and utility-first styling
- State Management: Zustand for lightweight and efficient global state management
- Routing: React Router DOM for navigation within the SPA
- Icons: React Icons for a variety of scalable vector icons
- Animations: Framer Motion for smooth UI animations and transitions
- Local Storage: For persisting user preferences and potentially basic settings offline.
- Optional: For camera integration, WebRTC might be considered for future development, but for MVP, we'll focus on the desk's IoT features and app control.
CORE FEATURES:
1. **Smart Drawer Control**:
* **User Flow**: User navigates to the 'Desk Controls' section. They see options to control the smart drawer (e.g., feed cat, provide water, dispense toy). User selects an action, optionally sets a schedule or triggers it immediately. The app sends a command to the desk's hardware (simulated via local state/API for now). A visual indicator on the UI confirms the action or shows a loading state.
* **Details**: Immediate trigger button, scheduling functionality (time, days of week), preset options for 'Food', 'Water', 'Toy'. Visual feedback for successful execution or errors.
2. **Cat Perch Management**:
* **User Flow**: In the 'Desk Controls' or 'Workspace View' section, the user can see the status of the cat perch (e.g., 'Available', 'Occupied', 'Retracted'). They can manually retract or extend the perch if the hardware supports it, or simply view its status. If the perch has sensors, this status updates automatically.
* **Details**: Toggle button for manual extension/retraction, visual status indicator, safety information (e.g., 'Do not extend while occupied').
3. **Activity Monitoring**:
* **User Flow**: User navigates to the 'Activity Log' section. The app displays a chronological list or graph of cat interactions with the desk (e.g., drawer usage, perch occupancy). Users can filter logs by date or activity type.
* **Details**: Timestamped events, type of interaction (drawer opened, perch used), duration of perch use. Summary statistics (e.g., 'Cat used perch 3 times today').
4. **Settings & Customization**:
* **User Flow**: User navigates to the 'Settings' page. They can configure desk parameters (e.g., drawer auto-close timer, perch sensitivity if applicable), set notification preferences, and customize the app's appearance (light/dark mode).
* **Details**: Input fields for timers, toggles for notifications, theme selector (Light/Dark/System), profile settings.
UI/UX DESIGN:
- **Layout**: Single-page application with a clean, modern dashboard layout. Main navigation (e.g., sidebar or top nav) includes: Dashboard (overview), Desk Controls, Activity Log, Settings. Content area displays the selected section.
- **Color Palette**: Primary: Soft, calming blues and greens (#A0D2DB, #84A98C). Accent: Warm, friendly orange or coral (#F5CAC3, #EE6C4F) for interactive elements and alerts. Neutrals: Off-white (#F8F9FA) and dark grey (#343A40) for backgrounds and text.
- **Typography**: sans-serif font family like 'Inter' or 'Poppins' for readability. Clear hierarchy using font weights and sizes.
- **Responsive Design**: Mobile-first approach. Layout adapts fluidly to different screen sizes (mobile, tablet, desktop). Use Tailwind's responsive modifiers (sm:, md:, lg:). Ensure touch targets are adequately sized on mobile.
- **Visual Metaphors**: Subtle use of cat-paw icons, gentle curves in UI elements, and calming background imagery (optional, subtle gradients).
COMPONENT BREAKDOWN:
- `App.js`: Main application component, sets up routing and global context/state providers.
- `Layout.js`: Contains the main structure (navbar, sidebar, content area). Handles responsive layout shifts.
- `Dashboard.js`: Overview page. Displays summary of desk status, recent activity, quick controls.
* `DeskStatusWidget.js`: Shows current state of the desk (drawer status, perch status).
* `QuickActions.js`: Buttons for immediate desk actions (e.g., open drawer).
* `RecentActivityFeed.js`: Displays the latest few entries from the activity log.
- `DeskControls.js`: Page dedicated to controlling the smart desk features.
* `DrawerControlCard.js`: Component for controlling the smart drawer. Props: `isOpen`, `onToggle`, `onSchedule`.
* `PerchControlCard.js`: Component for controlling the cat perch. Props: `isExtended`, `onToggle`, `status`.
* `Scheduler.js`: Sub-component for setting time-based triggers for the drawer.
- `ActivityLog.js`: Page displaying the detailed activity history.
* `ActivityFilter.js`: Component for filtering logs by date/type.
* `ActivityTable.js`: Renders the list/table of activities. Props: `logs`.
* `ActivityChart.js`: Visual representation of activity data (optional).
- `Settings.js`: Configuration page.
* `SettingItem.js`: Reusable component for a single setting (label, control, description). Props: `label`, `controlElement`, `description`.
* `ThemeSelector.js`: Component for choosing app theme.
- `Navigation.js`: Navigation component (Sidebar or Navbar).
- `Button.js`: Reusable custom button component. Props: `onClick`, `children`, `variant`, `size`, `isLoading`.
- `Modal.js`: Reusable modal/dialog component. Props: `isOpen`, `onClose`, `children`.
- `Icon.js`: Wrapper for icons. Props: `name`, `size`, `color`.
DATA MODEL:
- **Desk State**: `deskState = { drawer: { isOpen: boolean, isScheduled: boolean, scheduleTime: string | null }, perch: { isExtended: boolean, isOccupied: boolean } }`
- **Activity Log**: `logs = [{ id: string, timestamp: string, type: 'drawer_opened' | 'perch_used' | 'perch_released', duration?: number }]`
- **Settings**: `settings = { theme: 'light' | 'dark' | 'system', notificationsEnabled: boolean, drawerAutoCloseTimer: number }`
- **Mock Data**: Stored in `src/data/mockData.js`.
ANIMATIONS:
- **Page Transitions**: Use Framer Motion's `AnimatePresence` and `motion.div` for fade-in/slide-in transitions between pages/sections.
- **Button Interactions**: Subtle scale or background color change on hover/press.
- **Loading States**: Skeleton loaders or spinners within components when fetching data or waiting for hardware response. Use `AnimatePresence` to show/hide loading indicators smoothly.
- **Drawer/Perch Toggles**: Smooth slide or rotation animations when the drawer opens/closes or the perch extends/retracts.
- **Notifications**: Toast notifications for successful actions or errors should animate in and out.
EDGE CASES:
- **Initial State**: When the app loads for the first time or if local storage is empty, display default states and potentially a welcome/setup guide. Activity log should show an empty state message.
- **Hardware Disconnected/Error**: Display clear error messages and disable controls if the desk hardware is unresponsive. Provide troubleshooting steps or a 'reconnect' option.
- **Validation**: Ensure schedule times are valid, timers are positive numbers.
- **Accessibility (a11y)**: Use semantic HTML, ARIA attributes where necessary (e.g., for dynamic content updates), ensure sufficient color contrast, keyboard navigability for all interactive elements.
- **Empty States**: Design user-friendly empty states for the activity log and potentially the dashboard if no actions have been taken.
SAMPLE DATA:
```javascript
// src/data/mockData.js
export const mockDeskState = {
drawer: { isOpen: false, isScheduled: true, scheduleTime: '09:00' },
perch: { isExtended: true, isOccupied: false }
};
export const mockActivityLog = [
{ id: 'log1', timestamp: '2023-10-27T08:30:00Z', type: 'drawer_opened' },
{ id: 'log2', timestamp: '2023-10-27T09:15:00Z', type: 'perch_used', duration: 1200 }, // Duration in seconds
{ id: 'log3', timestamp: '2023-10-27T10:05:00Z', type: 'drawer_opened' },
{ id: 'log4', timestamp: '2023-10-26T14:00:00Z', type: 'perch_used', duration: 1800 },
{ id: 'log5', timestamp: '2023-10-26T14:30:00Z', type: 'perch_released' },
{ id: 'log6', timestamp: '2023-10-25T11:00:00Z', type: 'drawer_opened' }
];
export const mockSettings = {
theme: 'dark',
notificationsEnabled: true,
drawerAutoCloseTimer: 30 // seconds
};
// Example of how to generate more mock data for testing charts/lists
export const generateMockLog = (count = 5) => {
const types = ['drawer_opened', 'perch_used', 'perch_released'];
const logs = [];
let baseTime = new Date();
for (let i = 0; i < count; i++) {
const randomType = types[Math.floor(Math.random() * types.length)];
logs.push({
id: `mock_${i}_${Date.now()}`,
timestamp: new Date(baseTime.getTime() - Math.random() * 1000 * 60 * 60 * 24 * 3).toISOString(), // Random date within last 3 days
type: randomType,
...(randomType === 'perch_used' && { duration: Math.floor(Math.random() * 1200) + 60 })
});
}
return logs;
};
// Add more mock data for different scenarios as needed (e.g., empty states, error states)
```
DEPLOYMENT NOTES:
- **Build**: Use `npm run build` (or `yarn build`). Ensure the `homepage` property is set correctly in `package.json` if deploying to a sub-path.
- **Environment Variables**: Use `.env` files (e.g., `.env.development`, `.env.production`) for configuration like API endpoints if external services are integrated later. Prefix variables with `REACT_APP_`.
- **Performance**: Optimize images, use code splitting if the app grows beyond a single page, lazy load components, and memoize expensive calculations using `React.memo` or `useMemo`/`useCallback`.
- **HTTPS**: Ensure deployment uses HTTPS for security, especially if any sensitive data or user accounts were to be added.
- **Favicon/Manifest**: Include a favicon and a web app manifest for better PWA experience and branding.
- **Service Workers**: For offline capabilities and caching, consider implementing a service worker (e.g., using Workbox with CRA).