# AI Master Prompt for MenuTail MVP
## 1. PROJECT OVERVIEW
**Project Title:** MenuTail
**Problem:** Newer MacBook models feature a display "notch" in the center of the top bezel. When many menu bar applications are running, their icons can be pushed into this notch, becoming hidden and inaccessible. macOS provides no native overflow mechanism for menu bar icons, leading to user frustration and a degraded user experience. Users cannot easily see or click hidden icons without closing other applications or resorting to complex workarounds.
**Solution:** MenuTail is a macOS native application designed to intelligently manage and make accessible hidden menu bar icons. It provides users with a clear overview of hidden icons, allows them to manage their visibility, and offers smart solutions to ensure all essential menu bar items remain accessible, especially around the notch area.
**Value Proposition:** Regain control of your macOS menu bar. MenuTail ensures your vital app icons are always visible and accessible, eliminating the frustration of the notch hiding your tools. Enjoy a seamless, productive, and fully customizable menu bar experience.
**Target Audience:** macOS users with notch-equipped MacBooks (M1/M2/M3 Pro/Max, newer Air models) who frequently run multiple menu bar applications and experience icon visibility issues. This includes developers, designers, power users, and anyone who values efficient access to their system and application status icons.
**Core Goal:** Develop a fully functional, visually appealing, and user-friendly MVP of MenuTail using Next.js, enabling users to manage hidden menu bar icons effectively.
## 2. TECH STACK
* **Framework:** Next.js (App Router)
* **Language:** TypeScript
* **Styling:** Tailwind CSS
* **UI Components:** shadcn/ui (for pre-built, accessible components)
* **State Management:** Zustand or React Context API for global state, local component state as needed.
* **ORM:** Drizzle ORM with a PostgreSQL or SQLite (for local dev/simplicity) database.
* **Authentication:** NextAuth.js (for user accounts and session management)
* **Database:** PostgreSQL (production) / SQLite (local development)
* **Deployment:** Vercel
* **Icon Library:** Lucide React (for consistent icons)
* **Utilities:** `react-hook-form` (for form handling), `clsx` (for conditional class merging).
## 3. DATABASE SCHEMA
We'll focus on a minimal schema for the MVP, primarily managing users and their custom configurations.
**`users` table:**
* `id` (UUID, Primary Key)
* `name` (VARCHAR, Nullable)
* `email` (VARCHAR, Unique, Not Null)
* `emailVerified` (TIMESTAMP, Nullable)
* `image` (VARCHAR, Nullable)
* `createdAt` (TIMESTAMP, Default NOW())
* `updatedAt` (TIMESTAMP, Default NOW())
**`user_preferences` table:**
* `id` (UUID, Primary Key)
* `userId` (UUID, Foreign Key to `users.id`, Unique, Not Null)
* `hiddenIconThreshold` (INTEGER, Default 5, Not Null) - Max icons before hiding starts.
* `managementStrategy` (VARCHAR, Default 'auto_cascade', Not Null) - e.g., 'auto_cascade', 'manual_reorder', 'shadow_menu'.
* `shadowMenuEnabled` (BOOLEAN, Default false, Not Null)
* `shadowMenuPosition` (VARCHAR, Default 'right', Not Null) - e.g., 'right', 'left'.
* `enabledApps` (JSONB, Nullable) - Array of app identifiers to specifically manage/track.
* `createdAt` (TIMESTAMP, Default NOW())
* `updatedAt` (TIMESTAMP, Default NOW())
**`managed_icons` table (Potentially for more advanced features, MVP might simplify this):**
* `id` (UUID, Primary Key)
* `userId` (UUID, Foreign Key to `users.id`, Not Null)
* `appName` (VARCHAR, Not Null) - e.g., 'Tailscale', 'Slack', 'Spotify'.
* `iconIdentifier` (VARCHAR, Not Null) - A unique identifier for the icon (e.g., internal name).
* `status` (VARCHAR, Not Null) - e.g., 'visible', 'hidden', 'managed'.
* `preferredOrder` (INTEGER, Nullable) - For manual reordering.
* `createdAt` (TIMESTAMP, Default NOW())
* `updatedAt` (TIMESTAMP, Default NOW())
*Note: For MVP, `user_preferences` is the key table. `managed_icons` might be simplified to just tracking which apps the user wants MenuTail to actively monitor based on `user_preferences.enabledApps`.*
## 4. CORE FEATURES & USER FLOW
**Feature 1: Initial Setup & Authentication**
* **User Flow:**
1. User launches MenuTail application (simulated via a web interface for this Next.js app).
2. User is presented with a welcome screen explaining the app's purpose.
3. User clicks "Sign Up" or "Log In".
4. User is redirected to a NextAuth.js powered authentication page (e.g., using Google, GitHub, or Email/Password providers).
5. Upon successful authentication, the user is redirected to the main Dashboard.
6. If it's a new user, they might be prompted for initial setup (e.g., setting `hiddenIconThreshold`).
**Feature 2: Icon Monitoring & Dashboard Display**
* **Core Logic (Conceptual - requires native macOS integration not fully replicable in web MVP):** The *actual* MenuTail app would need macOS APIs to monitor menu bar items. For the *web MVP*, we will simulate this.
* **MVP Simulation:** The dashboard will display a list of potential menu bar apps. The user can toggle which apps they want MenuTail to "monitor". Based on the `hiddenIconThreshold` preference, the UI will visually indicate which icons *would be* hidden.
* **User Flow:**
1. User navigates to the Dashboard.
2. A list of common macOS menu bar apps is displayed (e.g., Tailscale, Slack, Spotify, Cloud Services, Calendar, Clock, etc.).
3. User can select/deselect apps to be actively monitored by MenuTail.
4. A visual indicator (e.g., a colored dot, a status label) shows the current "visibility" status of each app's icon based on the simulated threshold. e.g., "Visible", "Potentially Hidden".
5. The UI clearly shows the current `hiddenIconThreshold` value.
**Feature 3: Preference Management**
* **User Flow:**
1. User navigates to the "Settings" page.
2. User can adjust the `hiddenIconThreshold` slider/input.
3. User can select the `managementStrategy` (e.g., dropdown: 'Cascade', 'Manual Reorder', 'Shadow Menu').
4. If 'Shadow Menu' is selected, options to enable/disable and set its position ('left'/'right') appear.
5. User can edit the `enabledApps` list (e.g., add/remove app identifiers).
6. A "Save" button applies the changes, updating the `user_preferences` table via an API call.
**Feature 4: Simulated Icon Reordering/Shadow Menu**
* **User Flow (Cascade/Manual Reorder - Simulated):**
1. On the Dashboard, if 'Manual Reorder' is selected, the "Potentially Hidden" icons gain drag handles.
2. User can drag-and-drop these icons to reorder them in a designated area *above* the threshold.
3. Changes are visually reflected and can be saved.
* **User Flow (Shadow Menu - Simulated):**
1. If 'Shadow Menu' is enabled, a new button/icon appears in the main menu bar area (simulated by a button on the webpage).
2. Clicking this button reveals a dropdown/panel containing the "hidden" icons, laid out according to user preference.
3. This panel would be styled to look like a natural menu extension.
## 5. API & DATA FETCHING
* **Authentication API:** Handled by NextAuth.js (`/api/auth/[...nextauth]`).
* **User Preferences API (`/api/preferences`):**
* `GET /api/preferences`: Fetches the current user's preferences.
* `PUT /api/preferences`: Updates the current user's preferences. Expects a JSON body with fields from `user_preferences` table. Returns updated preferences or success/error status.
* **Simulated Icon Status API (`/api/icons/status`):**
* `GET /api/icons/status`: Returns a simulated list of apps and their status ('visible', 'hidden', 'managed') based on dummy data or simple logic for the MVP.
* **Data Fetching:** Use Server Components where possible for initial data load (e.g., dashboard, settings). Use Client Components with `useEffect` and `fetch` or a library like SWR/React Query for dynamic updates (e.g., saving preferences, fetching icon status if it were real-time).
## 6. COMPONENT BREAKDOWN (Next.js App Router Structure)
* **(App Router Structure)**
* `app/
* (auth)/
* layout.tsx (Auth layout for Sign In/Up pages)
* signin/
* page.tsx (Sign in form using NextAuth.js adapter)
* (main)/
* layout.tsx (Main app layout with Sidebar/Header)
* dashboard/
* page.tsx (Displays app list, simulated status, threshold)
* components/DashboardOverview.tsx (Shows current icon count vs threshold)
* components/AppList.tsx (Renders list of apps, checkboxes for monitoring)
* components/StatusIndicator.tsx (Visual cue for icon status)
* settings/
* page.tsx (Contains all preference settings)
* components/ThresholdSlider.tsx
* components/StrategySelector.tsx
* components/ShadowMenuConfig.tsx
* components/AppManagementForm.tsx
* components/Sidebar.tsx (Navigation links)
* components/Header.tsx (Includes user profile dropdown, logout button)
* page.tsx (Landing Page - explaining MenuTail, CTA to sign up)
* layout.tsx (Root layout - setting up providers, global styles)
* **Key Components:**
* `AuthButton.tsx` (Login/Logout functionality)
* `IconCard.tsx` (Represents a single app icon in lists)
* `PreferenceForm.tsx` (A reusable form component for settings)
* `NotificationBanner.tsx` (For success/error messages after saving preferences)
* `LoadingSpinner.tsx` (For API calls and transitions)
* **State Management:**
* User authentication state managed by NextAuth.js context.
* Global preferences fetched once and stored in Zustand store or Context.
* Local UI state for form inputs, modal open/close, etc.
## 7. UI/UX DESIGN & VISUAL IDENTITY
* **Design Style:** "Minimalist Clean with Subtle Tech Accents"
* **Color Palette:**
* Primary: `#0A0A0A` (Dark Background)
* Secondary: `#F5F5F5` (Light Text & Elements)
* Accent: `#3B82F6` (Tailwind Blue - for interactive elements, links, buttons)
* Subtle Accent: `#8B5CF6` (Tailwind Purple - for secondary highlights, hover states)
* Success: `#10B981` (Green)
* Error: `#EF4444` (Red)
* **Typography:** System fonts for macOS feel. `Inter` or `SF Pro Display` (if available/simulated).
* Headings: Semi-bold, 24-36px
* Body: Regular, 14-16px
* Captions: Regular, 12px
* **Layout:**
* Main application area uses a two-column layout: Fixed Sidebar (navigation) and Main Content Area.
* Dashboard: Card-based UI, clear visual hierarchy, status indicators.
* Settings: Grouped sections with clear headings, form elements aligned.
* Responsive: Primarily designed for desktop/laptop screen sizes. Sidebar may collapse on smaller screens.
* **Visual Elements:** Clean lines, ample whitespace, subtle use of `shadcn/ui`'s card and input styles. Focus on clarity and ease of use.
## 8. SAMPLE/MOCK DATA
* **User Preferences (Example):**
```json
{
"id": "user-uuid-123",
"userId": "user-uuid-123",
"hiddenIconThreshold": 7,
"managementStrategy": "auto_cascade",
"shadowMenuEnabled": false,
"shadowMenuPosition": "right",
"enabledApps": ["tailscale", "slack", "discord", "spotify", "calendar"]
}
```
* **Simulated Icon Status (Example):**
```json
[
{"appName": "Finder", "status": "visible", "isManaged": false},
{"appName": "System Preferences", "status": "visible", "isManaged": false},
{"appName": "Tailscale", "status": "visible", "isManaged": true},
{"appName": "Slack", "status": "hidden", "isManaged": true},
{"appName": "Discord", "status": "hidden", "isManaged": true},
{"appName": "Spotify", "status": "hidden", "isManaged": true},
{"appName": "Calendar", "status": "visible", "isManaged": true},
{"appName": "Clock", "status": "visible", "isManaged": true},
{"appName": "Cloud Sync", "status": "hidden", "isManaged": true},
{"appName": "VPN Client", "status": "hidden", "isManaged": true}
]
```
*(Note: In a real app, "status" would be dynamically determined. Here, "hidden" means it exceeds the threshold.)*
* **Mock User Data (for Auth):**
```json
{
"id": "clxyz123abc",
"name": "Alex Chen",
"email": "alex.chen@example.com",
"image": "/avatars/alex.png"
}
```
## 9. TURKISH TRANSLATIONS (Key UI Elements)
* **App Title:** Menü Yönlendirme (MenuTail)
* **Welcome Screen:**
* Title: "Menü Çubuğunuzu Kontrol Altına Alın"
* Subtitle: "macOS çentiği nedeniyle gizlenen ikonları yönetin ve erişilebilir kılın."
* Button: "Başla" (Get Started)
* **Dashboard:**
* Title: "Gösterge Paneli"
* Subtitle: "Uygulama ikonlarınızın görünürlüğünü izleyin."
* "Potentially Hidden Icons": "Potansiyel Olarak Gizli İkonlar"
* "Managed Apps": "Yönetilen Uygulamalar"
* "Visibility Threshold": "Görünürlük Eşiği"
* **Settings:**
* Title: "Ayarlar"
* "Icon Management Strategy": "İkon Yönetim Stratejisi"
* "Auto Cascade": "Otomatik Zincirleme"
* "Manual Reorder": "Manuel Yeniden Sıralama"
* "Shadow Menu": "Gölge Menü"
* "Enable Shadow Menu": "Gölge Menüyü Etkinleştir"
* "Shadow Menu Position": "Gölge Menü Konumu"
* "Left": "Sol"
* "Right": "Sağ"
* "Manage Specific Apps": "Belirli Uygulamaları Yönet"
* "Add App": "Uygulama Ekle"
* "Save Changes": "Değişiklikleri Kaydet"
* **Buttons:**
* "Sign Up": "Kayıt Ol"
* "Log In": "Giriş Yap"
* "Save": "Kaydet"
* "Cancel": "İptal"
* "Edit": "Düzenle"
* **Labels/Placeholders:**
* "Search apps...": "Uygulamalarda ara..."
* "Enter email": "E-posta girin"
* **Notifications:**
* "Settings saved successfully!": "Ayarlar başarıyla kaydedildi!"
* "Error saving settings.": "Ayarlar kaydedilirken hata oluştu."
## 10. ANIMATIONS & TRANSITIONS
* **Page Transitions:** Subtle fades between main sections using Next.js's built-in features or a library like `Framer Motion` for more elaborate transitions (e.g., slide-in from the side).
* **Hover Effects:** Gentle scaling or color changes on buttons and interactive elements using Tailwind CSS transitions (`hover:scale-105`, `hover:bg-opacity-80`).
* **Loading States:** Use `shadcn/ui`'s `Skeleton` component or a simple `Spinner` component for API data loading. Disable buttons during submission with visual feedback.
* **Drag and Drop:** Smooth visual feedback when dragging icons in the manual reorder mode.
* **Shadow Menu Reveal:** A quick, smooth dropdown animation for the shadow menu when activated.
## 11. EDGE CASES & VALIDATION
* **Authentication:** Handle "not authenticated" state gracefully. Redirect to login page. Ensure session management is robust.
* **Empty States:** Dashboard should display a helpful message if no apps are being monitored or if the user has just signed up. Settings page should clearly present all options even if defaults are active.
* **Form Validation:** Implement client-side and server-side validation for all input fields (e.g., email format, threshold within reasonable bounds) using `react-hook-form` and Drizzle ORM checks.
* **API Errors:** Display user-friendly error messages for failed API requests (e.g., saving preferences fails). Use the `NotificationBanner` component.
* **Threshold Logic:** Ensure the threshold calculation correctly identifies icons that *would* be hidden based on a simulated count. Handle cases where `hiddenIconThreshold` is 0 or very high.
* **App/Icon Identification:** In a real app, robust identification of menu bar items is crucial. For the MVP, rely on user selection and clear naming.
* **macOS Specifics:** Acknowledge that the MVP is a web simulation. The true value and complexity lie in native macOS integration (which is outside the scope of this Next.js MVP prompt but should be mentioned as the target for a real product).