PROJECT OVERVIEW:
The application, named 'Storage Sentinel', is a comprehensive cloud storage management SaaS designed to empower users by providing a unified dashboard for monitoring, analyzing, and optimizing their storage across multiple cloud providers like Microsoft OneDrive, Google Drive, and Dropbox. It aims to solve the problem of users unexpectedly running out of storage, facing unexpected charges, and being subjected to 'dark patterns' by service providers trying to upsell them. The core value proposition is to give users clear visibility, actionable insights, and control over their digital assets, saving them time and money.
TECH STACK:
- Frontend: Next.js (App Router), React, Tailwind CSS, shadcn/ui (for pre-built components), Zustand (for state management).
- Backend: Next.js API Routes (or a separate Node.js/Express.js server).
- Database: PostgreSQL with Drizzle ORM.
- Authentication: NextAuth.js (with providers for Google, Microsoft, etc., and email/password).
- Cloud Storage Integration: Official SDKs/APIs for Google Drive, Microsoft OneDrive, Dropbox.
- Deployment: Vercel or similar platform.
- Other: Axios (for API requests), React Hook Form (for forms), Zod (for validation).
DATABASE SCHEMA:
1. `users` table:
- `id` (uuid, primary key)
- `name` (text)
- `email` (text, unique)
- `emailVerified` (timestamp)
- `image` (text, optional)
- `password` (text, for email/password auth)
- `createdAt` (timestamp)
- `updatedAt` (timestamp)
2. `accounts` table (for NextAuth.js multi-provider support):
- `id` (bigint, primary key, auto-increment)
- `userId` (uuid, foreign key to `users.id`)
- `type` (text, e.g., 'oauth', 'email')
- `provider` (text, e.g., 'google', 'microsoft', 'dropbox')
- `providerAccountId` (text)
- `refresh_token` (text, encrypted)
- `access_token` (text, encrypted)
- `expires_at` (bigint, optional)
- `token_type` (text, optional)
- `scope` (text, optional)
- `createdAt` (timestamp)
- `updatedAt` (timestamp)
3. `storageProviders` table:
- `id` (uuid, primary key)
- `userId` (uuid, foreign key to `users.id`)
- `providerName` (text, e.g., 'google', 'microsoft', 'dropbox')
- `accountId` (bigint, foreign key to `accounts.id`)
- `totalSpaceBytes` (bigint)
- `usedSpaceBytes` (bigint)
- `lastSyncAt` (timestamp)
- `isPrimary` (boolean, default: false)
- `createdAt` (timestamp)
- `updatedAt` (timestamp)
4. `files` table (optional for MVP, focus on aggregated data first):
- `id` (uuid, primary key)
- `userId` (uuid, foreign key to `users.id`)
- `storageProviderId` (uuid, foreign key to `storageProviders.id`)
- `fileName` (text)
- `filePath` (text)
- `fileSize` (bigint)
- `lastModified` (timestamp)
- `fileType` (text)
- `createdAt` (timestamp)
- `updatedAt` (timestamp)
5. `alerts` table:
- `id` (uuid, primary key)
- `userId` (uuid, foreign key to `users.id`)
- `alertType` (text, e.g., 'quota_low', 'large_file_detected', 'inactive_file_detected')
- `thresholdPercent` (integer, optional, for quota_low)
- `status` (text, e.g., 'sent', 'dismissed', 'resolved')
- `message` (text)
- `createdAt` (timestamp)
CORE FEATURES & USER FLOW:
1. **Authentication & Onboarding:**
* User signs up/logs in via NextAuth.js (Google, Microsoft, Email/Password).
* Upon first login, user is prompted to connect their cloud storage accounts.
* User clicks 'Connect [Provider Name]' button (e.g., 'Connect Google Drive').
* Redirected to the provider's OAuth consent screen.
* User grants permissions.
* Redirected back to Storage Sentinel. Account is saved in `accounts` and `storageProviders` tables with initial data fetch.
* User can connect multiple accounts.
2. **Dashboard & Storage Visualization:**
* **User Flow:** Logs in -> Sees Dashboard.
* **Functionality:** Displays a summary card for each connected `storageProvider` showing `providerName`, `usedSpaceBytes`, `totalSpaceBytes`.
* **Visual:** A prominent donut or bar chart visually representing the total aggregated used space vs. total available space across all providers.
* **Data Display:** Shows total used space, total available space, and percentage used. Displays recent alerts.
* **Edge Case:** If no providers are connected, displays an onboarding prompt and instructions to connect accounts.
3. **Storage Analysis & Insights:**
* **User Flow:** Navigates to 'Analysis' tab/page -> Sees list of potential space-saving actions.
* **Functionality:** Backend job or on-demand analysis fetches file metadata (if `files` table is used, otherwise relies on provider API aggregation). Identifies:
* Largest files (by size).
* Files not modified recently (e.g., > 1 year).
* Duplicate files (more complex, maybe future MVP).
* Counts/sizes per file type (images, videos, documents).
* **Output:** Presents these findings in categorized lists or charts. Each item should have a 'Take Action' button (e.g., 'Delete', 'Move to Archive', 'View on Provider').
* **Edge Case:** If no files are analyzed or storage is low, display relevant message.
4. **Alerting System:**
* **User Flow:** User receives a notification (in-app or email/push if implemented) when a threshold is met.
* **Functionality:** A scheduled job or trigger checks `storageProviders` usage against configured thresholds (e.g., 80%, 90%). If a threshold is breached, an entry is created in the `alerts` table and a notification is triggered.
* **Display:** Alerts are listed on the Dashboard and an 'Alerts' page.
* **User Action:** Users can dismiss or mark alerts as resolved.
* **Edge Case:** Ensure alerts are not sent repeatedly for the same event; implement status tracking.
5. **Dark Pattern Detection (Basic MVP):**
* **User Flow:** User navigates to a 'Provider Insights' or 'Security' section. Sees warnings about specific UI tactics used by providers.
* **Functionality:** This feature will initially rely on pre-defined rules and information. For example, if a user is on the OneDrive storage upgrade page and the UI detects a common 'dark pattern' (e.g., a confusingly worded button, a hidden smaller text explaining limitations), a flag can be raised.
* **Display:** A dedicated section or pop-up explaining the detected pattern and its implications. E.g., "Warning: Microsoft's upgrade prompt uses a common tactic to make the cheaper plan seem less appealing. Consider the actual storage amount." This section will be curated based on known industry practices.
* **Edge Case:** Acknowledge that full automation is complex; MVP focuses on awareness and known patterns.
API & DATA FETCHING:
- **Auth Endpoints:** Handled by NextAuth.js (`/api/auth/...`).
- **`/api/storage/connect` (POST):** Initiates OAuth flow with a provider.
- **`/api/storage/callback` (GET):** Handles OAuth callback, exchanges code for tokens, saves account info.
- **`/api/storage/providers` (GET):** Fetches list of connected storage providers and their current usage stats for the logged-in user. Uses `storageProviders` table and potentially background sync jobs.
- **`/api/storage/sync/:providerId` (POST):** Manually triggers a data sync for a specific provider. Returns sync status.
- **`/api/analysis/overview` (GET):** Fetches aggregated data for file analysis (largest files, inactive files etc.).
- **`/api/alerts` (GET):** Fetches user's alerts from the `alerts` table.
- **`/api/alerts/:id` (PUT):** Updates alert status (e.g., dismiss).
- **Data Fetching:** Use server-side fetching (e.g., `fetch` in Route Handlers or `getServerSideProps` in older pages) for initial loads and authenticated API calls from client components using `fetch` or Axios with JWT tokens.
- **Real-time Updates:** Consider Server-Sent Events (SSE) or polling for near real-time sync status updates if needed.
UI/UX DESIGN & VISUAL IDENTITY:
- **Style:** Minimalist Clean with a touch of Modern Professional.
- **Color Palette:** Primary: `#4F46E5` (Indigo-500), Secondary: `#6366F1` (Indigo-400). Accent: `#10B981` (Emerald-500) for success/positive. Warning: `#F59E0B` (Amber-500). Neutral: `#F3F4F6` (Gray-100) for backgrounds, `#1F2937` (Gray-800) for text. Dark Mode support is essential.
- **Typography:** Sans-serif font like Inter or Poppins. Clear hierarchy with distinct heading sizes (H1, H2, H3) and body text.
- **Layout:** Consistent layout with a sidebar navigation for authenticated users (Dashboard, Connections, Analysis, Alerts, Settings). Main content area uses cards, tables, and charts.
- **Responsiveness:** Mobile-first approach. Sidebar collapses into a hamburger menu on smaller screens. Charts and tables adapt gracefully.
- **Animations:** Subtle fade-ins for components, smooth transitions for chart updates, loading spinners/skeletons for data fetching. Button hover effects.
COMPONENT BREAKDOWN (Next.js App Router):
- `/app/layout.tsx`: Root layout, includes providers (state management, theme), Tailwind CSS setup, global styles.
- `/app/(auth)/layout.tsx`: Layout for auth pages.
- `/app/(auth)/login/page.tsx`: Login page.
- `/app/(auth)/signup/page.tsx`: Signup page.
- `/app/(auth)/reset-password/page.tsx`: Password reset page.
- `/app/(app)/layout.tsx`: Main application layout (sidebar, header).
- `/app/(app)/dashboard/page.tsx`: Displays overview, summary cards, main chart, recent alerts.
- `components/dashboard/StorageSummaryCard.tsx`: Displays usage for a single provider.
- `components/dashboard/AggregatedStorageChart.tsx`: Donut/bar chart for total usage.
- `components/dashboard/AlertsList.tsx`: Shows recent alerts.
- `/app/(app)/connections/page.tsx`: Manages connected cloud storage accounts.
- `components/connections/ProviderConnectButton.tsx`: Button to initiate OAuth flow for a provider.
- `components/connections/ProviderCard.tsx`: Displays connected provider info and sync status, option to disconnect.
- `/app/(app)/analysis/page.tsx`: Displays file analysis results.
- `components/analysis/FileList.tsx`: Table/list for large files, inactive files, etc.
- `components/analysis/FileTypeChart.tsx`: Pie chart of file types.
- `/app/(app)/alerts/page.tsx`: Displays all past and present alerts.
- `components/alerts/AlertItem.tsx`: Individual alert display.
- `/app/(app)/settings/page.tsx`: User profile and application settings.
- `/app/(app)/settings/profile/page.tsx`: Profile editing.
- `/app/(app)/settings/notifications/page.tsx`: Notification preferences.
- `/app/(app)/settings/billing/page.tsx`: (If premium features exist) Subscription management.
- `components/ui/Button.tsx`: Reusable button component (from shadcn/ui).
- `components/ui/Card.tsx`: Reusable card component.
- `components/ui/Chart.tsx`: Wrapper for a charting library (e.g., Recharts, Chart.js).
- `components/ui/Input.tsx`, `components/ui/Label.tsx`, etc.: General UI components from shadcn/ui.
- `components/layout/Sidebar.tsx`: Navigation sidebar.
- `components/layout/Header.tsx`: Top header bar.
- `components/layout/LoadingSpinner.tsx`: Global loading indicator.
- `components/layout/EmptyState.tsx`: Placeholder for empty data states.
ANIMATIONS:
- **Page Transitions:** Subtle fade or slide effect between pages using Next.js's built-in capabilities or libraries like `Framer Motion`.
- **Component Mount:** Elements (cards, list items) fade in or slide up as they appear on the screen.
- **Data Loading:** Use skeleton loaders that mimic the final component structure before data arrives. Replace with actual content with a smooth transition.
- **Hover Effects:** Slight scale or background color change on interactive elements like buttons and links.
- **Chart Animations:** Animate chart data loading and updates for a dynamic feel.
EDGE CASES:
- **No Providers Connected:** Dashboard shows an empty state message guiding users to connect their accounts.
- **Authentication Failures:** Clear error messages during login/signup. Handle token expiration gracefully, prompting re-authentication.
- **API Errors:** Implement global error handling for API requests. Show user-friendly messages (e.g., 'Could not fetch data, please try again later') instead of raw error codes.
- **Provider API Limits:** Handle rate limiting from cloud storage providers. Implement retry logic with exponential backoff. Inform the user if API limits are being hit.
- **Empty States:** All lists and data views (Dashboard, Analysis, Alerts) should have well-designed empty state components.
- **Data Validation:** Use Zod for validating all incoming API data and form inputs.
- **Permissions:** Ensure users can only access their own data. Implement authorization checks on API routes.
- **Sync Failures:** Clearly indicate if a data sync for a specific provider has failed and provide options to retry.
SAMPLE DATA:
1. **User:**
```json
{
"id": "uuid-user-123",
"name": "Alice Smith",
"email": "alice.smith@example.com"
}
```
2. **Account (Google):**
```json
{
"id": 1,
"userId": "uuid-user-123",
"provider": "google",
"providerAccountId": "google-id-abc",
"access_token": "encrypted-google-token",
"refresh_token": "encrypted-google-refresh-token",
"expires_at": 1700000000
}
```
3. **Storage Provider (OneDrive):**
```json
{
"id": "uuid-provider-456",
"userId": "uuid-user-123",
"providerName": "microsoft",
"accountId": 2,
"totalSpaceBytes": 10737418240, // 10 GB
"usedSpaceBytes": 8800000000, // 8.8 GB
"lastSyncAt": "2024-01-15T10:00:00Z"
}
```
4. **Storage Provider (Dropbox - Low Space):
```json
{
"id": "uuid-provider-789",
"userId": "uuid-user-123",
"providerName": "dropbox",
"accountId": 3,
"totalSpaceBytes": 5368709120, // 5 GB
"usedSpaceBytes": 4900000000, // 4.9 GB
"lastSyncAt": "2024-01-15T10:05:00Z"
}
```
5. **Alert (Quota Low):
```json
{
"id": "uuid-alert-101",
"userId": "uuid-user-123",
"alertType": "quota_low",
"thresholdPercent": 90,
"status": "sent",
"message": "Your Dropbox storage is at 92% capacity.",
"createdAt": "2024-01-15T11:30:00Z"
}
```
6. **File Example (Large File Analysis):
```json
{
"id": "uuid-file-112",
"userId": "uuid-user-123",
"storageProviderId": "uuid-provider-456",
"fileName": "MyVacationVideo.mp4",
"filePath": "/Videos/Summer2023",
"fileSize": 2147483648, // 2 GB
"lastModified": "2023-07-20T14:00:00Z",
"fileType": "video"
}
```
7. **File Example (Inactive File):
```json
{
"id": "uuid-file-113",
"userId": "uuid-user-123",
"storageProviderId": "uuid-provider-789",
"fileName": "OldProjectBackup.zip",
"filePath": "/Backups",
"fileSize": 536870912, // 0.5 GB
"lastModified": "2022-01-10T09:00:00Z", // Modified over a year ago
"fileType": "archive"
}
```
8. **Dark Pattern Insight Example:**
```json
{
"id": "dp-insight-001",
"provider": "microsoft",
"title": "Confusing Upgrade Button",
"description": "Microsoft often uses buttons that visually emphasize a higher-tier plan while making the desired lower-tier plan less prominent or requiring extra clicks.",
"advice": "Always carefully read the storage amount and price before clicking 'Upgrade'. Look for explicitly stated GB/TB values."
}
```
This prompt provides a detailed blueprint for building a functional MVP of Storage Sentinel, covering technical implementation, user experience, and potential challenges.