## AI Master Prompt for Vitruvian Flow MVP Development
**PROJECT OVERVIEW:**
Vitruvian Flow is a Desktop Application Launcher and Customization SaaS designed to bring the philosophy of VitruvianOS (inspired by BeOS) to users of Windows, macOS, and Linux. The core problem it solves is the "clutter" and lack of personalized efficiency in modern desktop environments. Users often struggle to quickly access their most-used applications and tools, and default interfaces can feel restrictive. Vitruvian Flow offers a highly integrated, intuitive, and customizable "dashboard" where users can pin favorite applications, add useful widgets (like clock, weather, notes, system stats), and apply custom themes. It embodies the principles of "KISS" (Keep It Simple, Stupid) and "Home Rule" (your computer, your rules, no data collection). The value proposition is a faster, more focused, and deeply personalizable desktop experience, boosting productivity and user comfort, all "Out Of The Box" with minimal setup.
**TECH STACK:**
- **Frontend Framework:** React (Next.js App Router)
- **Styling:** Tailwind CSS (v3+)
- **UI Component Library:** shadcn/ui (for accessible, re-usable components)
- **State Management:** React Context API / Zustand (for global state like auth, theme)
- **ORM:** Drizzle ORM (for type-safe database interactions)
- **Database:** PostgreSQL (recommended for Drizzle ORM, scalable)
- **Authentication:** NextAuth.js (for robust authentication)
- **Form Handling & Validation:** React Hook Form + Zod
- **API Layer:** Next.js API Routes (App Router) or Server Actions
- **Deployment:** Vercel (recommended for Next.js)
**DATABASE SCHEMA (Drizzle ORM - PostgreSQL):**
```sql
-- Users Table
users (
id TEXT PRIMARY KEY,
name TEXT,
email TEXT UNIQUE NOT NULL,
emailVerified TIMESTAMP(3),
image TEXT,
-- Add other user-specific fields like created_at, updated_at if needed
-- FOREIGN KEY references auth.accounts.provider_account_id if using NextAuth.js with linked accounts
);
-- Accounts Table (for NextAuth.js)
accounts (
id serialized PRIMARY KEY,
userId TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
type TEXT NOT NULL, -- e.g., "oauth", "email", "credentials"
provider TEXT NOT NULL,
providerAccountId TEXT NOT NULL,
refresh_token TEXT,
access_token TEXT,
expires_at BIGINT,
token_type TEXT,
scope TEXT,
id_token TEXT,
session_state TEXT,
UNIQUE(provider, providerAccountId)
);
-- Sessions Table (for NextAuth.js)
sessions (
sessionToken TEXT PRIMARY KEY,
userId TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
expires TIMESTAMP(3) NOT NULL
);
-- Verification Tokens Table (for NextAuth.js)
verification_tokens (
identifier TEXT NOT NULL,
token TEXT NOT NULL,
expires TIMESTAMP(3) NOT NULL,
PRIMARY KEY (identifier, token)
);
-- Themes Table
themes (
id SERIAL PRIMARY KEY,
userId TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
name TEXT NOT NULL,
backgroundColor TEXT,
textColor TEXT,
primaryColor TEXT,
secondaryColor TEXT,
fontFamily TEXT,
isDarkMode BOOLEAN DEFAULT FALSE,
UNIQUE(userId, name) -- Ensure a user cannot have two themes with the same name
);
-- Widgets Table
widgets (
id SERIAL PRIMARY KEY,
userId TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
type VARCHAR(50) NOT NULL, -- e.g., "clock", "weather", "notes", "system_stats"
positionX INT NOT NULL,
positionY INT NOT NULL,
width INT NOT NULL,
height INT NOT NULL,
config JSONB -- Stores widget-specific settings (e.g., for weather: location, for notes: content)
);
-- Shortcuts Table
shortcuts (
id SERIAL PRIMARY KEY,
userId TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
name TEXT NOT NULL,
target TEXT NOT NULL, -- Path to application, URL, etc.
iconUrl TEXT, -- Optional URL for a custom icon
position INT, -- Order for display
category VARCHAR(50) -- Optional category for grouping
);
-- User Preferences (for default theme, layout, etc.)
user_preferences (
userId TEXT PRIMARY KEY REFERENCES users(id) ON DELETE CASCADE,
defaultThemeId INT REFERENCES themes(id) ON DELETE SET NULL,
layout JSONB -- Could store general layout settings if needed beyond widgets/shortcuts
);
-- Example Relationships:
-- A user can have multiple themes (one-to-many).
-- A user can have multiple widgets (one-to-many).
-- A user can have multiple shortcuts (one-to-many).
-- A user has one default theme preference.
```
**CORE FEATURES & USER FLOW:**
1. **Authentication (NextAuth.js):**
* **Flow:** User lands on the homepage. Clicks "Sign In" or "Get Started". Presented with options (Email/Password, Google, GitHub). Upon successful authentication, user is redirected to their personalized dashboard.
* **Sign Up:** Email input, Password input, Confirm Password. Zod validation. On success, creates a new user record in the `users` table and a default theme/preference record. User is logged in and redirected to dashboard.
* **Sign In:** Email/Password input. NextAuth.js handles credential verification against the `users` and `accounts` tables.
* **Sign Out:** Button in user menu. Destroys session and redirects to homepage.
* **Edge Case:** Handle OAuth callback errors, invalid credentials, rate limiting for sign-in attempts.
2. **Dashboard - Personalized Workspace:**
* **Flow:** Authenticated user lands on `/dashboard`. The page loads user's data: active theme, configured widgets, and shortcuts from the database.
* **Layout:** A flexible grid system (using CSS Grid/Flexbox) that allows widgets and shortcuts to be placed and resized. Supports drag-and-drop reordering.
* **Components:** Header (Logo, User Menu), Widget Area, Shortcut Bar.
* **Initial State:** If no widgets/shortcuts are configured, display a "Get Started" guide prompting the user to add their first item.
3. **Widget Management:**
* **Adding Widgets:** User clicks an "Add Widget" button on the dashboard. A modal or sidebar appears listing available widget types (Clock, Weather, Notes, System Stats). User selects a widget, configures initial settings (e.g., location for weather), and clicks "Add".
* **Configuration:** Each widget instance can be configured. Clicking a "Settings" icon on the widget opens a configuration modal specific to that widget type (e.g., for Clock: timezone; for Notes: text content).
* **Positioning & Resizing:** Users drag widgets to desired positions (`positionX`, `positionY`) and resize them (`width`, `height`). These values are updated in the `widgets` table via API calls (debounced to avoid excessive updates).
* **Removing Widgets:** A "Remove" or "Delete" button on the widget or in its settings.
* **Edge Cases:** Widget fails to load/render, configuration data is invalid.
4. **Shortcut Management:**
* **Adding Shortcuts:** Similar to widgets, an "Add Shortcut" button. User inputs Name, Target (file path, URL, command), optionally uploads/selects an icon.
* **Launching:** Clicking a shortcut triggers a backend action (potentially using a small native helper app or specific OS commands if feasible within the SaaS constraints, or simply opening URLs/known app protocols). For a pure web app, launching local apps is challenging; focus on web app shortcuts or deep links initially.
* **Organization:** Display shortcuts in a visually appealing bar or grid. Support drag-and-drop reordering (`position`). Optional categorization.
* **Editing/Removing:** Standard edit/delete functionality.
* **Edge Cases:** Invalid shortcut target, permissions issues launching applications (if applicable).
5. **Theme Customization:**
* **Access:** Via "Settings" -> "Appearance" or directly from the User Menu.
* **Options:** Select from pre-defined themes or create a new custom theme.
* **Custom Theme Builder:** UI for selecting background color, text color, primary/secondary accent colors, font family. Live preview is crucial.
* **Saving:** Updates the `themes` table. User can set a theme as default via `user_preferences`.
* **Applying:** The selected theme's CSS variables are applied globally, affecting all components.
* **Edge Cases:** Invalid color codes, font not loading.
**API & DATA FETCHING:**
- **Approach:** Utilize Next.js App Router's Server Components for initial data fetching where possible (e.g., loading dashboard data when the page loads). Use Server Actions or API Routes (under `app/api/`) for mutations (POST, PUT, DELETE) and dynamic data fetching. Employ client-side fetching (using `fetch` in `useEffect` or libraries like SWR/React Query) for interactions requiring immediate updates without a full page reload (e.g., updating widget position).
- **Example API Routes/Server Actions:**
* `POST /api/widgets` or `serverActions.addWidget()`: Add a new widget.
* `PUT /api/widgets/:id` or `serverActions.updateWidget(id, updates)`: Update widget position, size, or config.
* `DELETE /api/widgets/:id` or `serverActions.deleteWidget(id)`: Remove a widget.
* (Similar routes/actions for `shortcuts` and `themes`).
* `GET /api/user/dashboard` or Server Component fetch: Load all user data for the dashboard.
- **Data Fetching Principles:** Fetch only necessary data. Use caching strategies effectively. Implement optimistic UI updates where appropriate.
- **Request/Response:** Standard JSON. Use Zod for request/response validation on API routes.
**COMPONENT BREAKDOWN (Next.js App Router Structure):**
- **`app/`:**
- **`(auth)/`:**
- `signin/page.tsx`: Sign-in form page.
- `signup/page.tsx`: Sign-up form page.
- `reset-password/page.tsx`: Password reset page.
- **`(app)/`:** (Protected routes, requires authentication)
- `dashboard/page.tsx`: The main personalized workspace. Loads user data, renders grid, widgets, shortcuts.
- `settings/page.tsx`:
- `layout.tsx`: Settings navigation (Appearance, Profile, Account).
- `appearance/page.tsx`: Theme customization UI.
- `profile/page.tsx`: User profile editing.
- `account/page.tsx`: Account management (email, password).
- `layout.tsx`: Root layout (includes global providers, possibly header/footer for public pages).
- `page.tsx`: Public landing page.
- `global.css`: Global styles.
- **`components/`:**
- **`ui/`:** (Shared components from shadcn/ui)
- `button.tsx`, `input.tsx`, `card.tsx`, `dialog.tsx`, `dropdown-menu.tsx`, `tooltip.tsx`, etc.
- **`auth/`:**
- `SignInForm.tsx`, `SignUpForm.tsx`, `UserNav.tsx` (dropdown in header).
- **`dashboard/`:**
- `DashboardGrid.tsx`: Main grid container, handles layout logic, potentially uses a drag-and-drop library.
- `WidgetRenderer.tsx`: Component to dynamically render different widget types based on `widget.type`.
- **`widgets/`:** (Individual widget components)
- `ClockWidget.tsx`, `WeatherWidget.tsx`, `NotesWidget.tsx`, `SystemStatsWidget.tsx` (each handles its own state and potential configuration modals).
- **`shortcuts/`:**
- `ShortcutBar.tsx`: Renders the shortcut list/bar.
- `ShortcutItem.tsx`: Individual shortcut component.
- `AddShortcutDialog.tsx`.
- **`theme/`:**
- `ThemeCustomizer.tsx`: UI for color pickers, font selectors.
- `ThemeSelector.tsx`.
- **`common/`:**
- `Header.tsx`, `Footer.tsx`, `LoadingSpinner.tsx`, `ErrorDisplay.tsx`.
- **`lib/`:**
- `db.ts`: Drizzle ORM initialization.
- `auth.ts`: NextAuth.js configuration.
- `utils.ts`: Utility functions.
- `validators.ts`: Zod validation schemas.
- **`hooks/`:**
- `useDebounce.ts`: Custom debounce hook.
- `useAuth.ts`: Custom hook for auth state.
**UI/UX DESIGN & VISUAL IDENTITY:**
- **Style:** "Minimalist Clean with a touch of BeOS aesthetic". Focus on clarity, spacing, and intuitive interaction. Subtle animations and smooth transitions.
- **Color Palette:**
- **Primary:** `#4A90E2` (Modern Blue)
- **Secondary:** `#50E3C2` (Vibrant Teal/Green)
- **Accent/Action:** `#F5A623` (Warm Orange)
- **Background (Light Mode):** `#F8F9FA` (Very Light Gray)
- **Surface (Light Mode):** `#FFFFFF` (White)
- **Text (Light Mode):** `#212529` (Dark Gray)
- **Background (Dark Mode):** `#121212` (Very Dark Gray)
- **Surface (Dark Mode):** `#1E1E1E` (Slightly Lighter Dark Gray)
- **Text (Dark Mode):** `#E0E0E0` (Light Gray)
- **Typography:**
- **Headings:** Inter (SemiBold) or similar sans-serif, slightly modern.
- **Body Text:** Inter (Regular) or Roboto.
- **Code/Monospace:** JetBrains Mono or Fira Code.
- **Layout:** Generous whitespace. Card-based design for widgets and shortcuts. Clear visual hierarchy. Responsive design ensuring usability on various screen sizes (though primarily desktop-focused).
- **Interactions:** Smooth transitions for opening/closing modals, adding/removing items. Subtle hover effects on buttons and shortcuts. Loading states clearly indicated with spinners or skeleton loaders.
**ANIMATIONS:**
- **Page Transitions:** Use `Framer Motion` or similar for smooth fade/slide transitions between pages in the `(app)` route group.
- **Component Mount/Unmount:** Animate widgets and shortcuts appearing/disappearing from the grid.
- **Hover Effects:** Subtle scaling or background color change on interactive elements like shortcuts and buttons.
- **Loading States:** Use `tailwindcss-animate` or custom spinners within buttons and content areas while data is fetching.
- **Drag and Drop:** Visual feedback during drag operations (e.g., item slightly scales up, placeholder shows where it will drop).
**SAMPLE/MOCK DATA:**
1. **User Profile:**
```json
{
"id": "user_123",
"name": "Alex Mercer",
"email": "alex.mercer@example.com"
}
```
2. **Theme (Default Dark):**
```json
{
"id": 1,
"userId": "user_123",
"name": "Midnight",
"backgroundColor": "#121212",
"textColor": "#E0E0E0",
"primaryColor": "#4A90E2",
"secondaryColor": "#50E3C2",
"isDarkMode": true
}
```
3. **Widget (Clock):**
```json
{
"id": 101,
"userId": "user_123",
"type": "clock",
"positionX": 0,
"positionY": 0,
"width": 2,
"height": 1,
"config": {"timezone": "Local"}
}
```
4. **Widget (Notes):**
```json
{
"id": 102,
"userId": "user_123",
"type": "notes",
"positionX": 2,
"positionY": 0,
"width": 3,
"height": 2,
"config": {"content": "Remember to buy milk. Also, check Vitruvian Flow updates."}
}
```
5. **Shortcut (VS Code):**
```json
{
"id": 201,
"userId": "user_123",
"name": "VS Code",
"target": "/usr/bin/code" OR "vscode://open"
"iconUrl": "/icons/vscode.png",
"position": 0
}
```
6. **Shortcut (Hacker News):**
```json
{
"id": 202,
"userId": "user_123",
"name": "Hacker News",
"target": "https://news.ycombinator.com",
"iconUrl": null,
"position": 1
}
```
7. **Widget (Weather - Initial Config):**
```json
{
"id": 103,
"userId": "user_123",
"type": "weather",
"positionX": 5,
"positionY": 0,
"width": 2,
"height": 1,
"config": {"location": "Istanbul, TR"}
}
```
8. **User Preferences:**
```json
{
"userId": "user_123",
"defaultThemeId": 1
}
```
**EDGE CASES:**
- **Empty States:** Display helpful messages and clear calls to action when dashboards, widget lists, or shortcut lists are empty (e.g., "Add your first widget to get started!").
- **Authentication:** Handle expired sessions, incorrect login attempts gracefully. Implement password reset flow securely. Protect all routes within `(app)` group.
- **Error Handling:** Global error handling mechanism (e.g., using Error Boundaries in React). Specific error messages for API failures, widget loading issues, invalid user input.
- **Validation:** Robust validation using Zod for all form inputs (sign up, settings, widget/shortcut config) and API payloads.
- **Offline/Connectivity Issues:** Consider how the app behaves if the user loses internet connection (especially for widgets that rely on external APIs like weather). Potentially cache data or display an offline indicator.
- **Responsiveness:** Ensure the dashboard grid and components adapt reasonably to different screen sizes, although the primary target is desktop.
- **Widget Failures:** If a widget fails to load or fetch data, display a clear error state within its bounds without crashing the entire dashboard.
- **Data Persistence:** Ensure all user changes (widget placement, theme settings, etc.) are saved reliably to the database.