PROJECT OVERVIEW:
This project aims to build 'Kendi Bulutun' (Your Own Cloud), a single-page application (SPA) that empowers users to manage their cloud storage services (like AWS S3, Cloudflare R2, Vercel Blob, or local storage) as if it were a local file system. The core value proposition is to provide a unified, secure, and cost-effective alternative to traditional cloud storage providers like Dropbox or Google Drive, allowing users to 'Bring Your Own Bucket' (BYOB). It solves the problem of high recurring costs, data privacy concerns, and vendor lock-in associated with commercial cloud storage by leveraging user-owned storage resources and offering a streamlined virtual file system experience with powerful search capabilities.
TECH STACK:
- Frontend Framework: React.js (using Vite for fast development server and build optimization).
- Styling: Tailwind CSS for rapid and utility-first styling.
- State Management: Zustand for efficient global and local state management.
- Routing: React Router DOM for client-side navigation.
- API Interaction: Axios for making HTTP requests to the backend or directly to cloud storage APIs.
- UI Components: Radix UI primitives for accessible and unstyled UI components, which will be styled with Tailwind CSS.
- Icons: Lucide React for a comprehensive set of SVG icons.
- Form Handling: React Hook Form for efficient form validation and management.
- Utility Libraries: Lodash for utility functions, date-fns for date formatting.
- Build Tool: Vite.
- Deployment Target: Static site hosting (e.g., Vercel, Netlify) with a lightweight backend or serverless functions for specific operations if needed (though the goal is to minimize server-side logic for a true BYOB experience).
CORE FEATURES:
1. **Cloud Provider Connection Management:**
* **User Flow:** Users navigate to a 'Connections' or 'Settings' page. They select a provider (S3, R2, Vercel Blob, Local). Upon selection, they are prompted to enter their specific credentials (e.g., Access Key ID, Secret Access Key, Endpoint URL for S3/R2; API Token for Vercel Blob; or a local path if applicable). The system validates these credentials. Successful connections are listed, allowing users to edit or remove them.
* **Details:** This involves secure input fields for sensitive credentials. Each connection should be clearly labeled with the provider type and a user-defined alias. Error handling for invalid credentials is crucial.
2. **Virtual File System (VFS) Interface:**
* **User Flow:** The main interface displays the contents of the selected bucket/container. Users see a familiar hierarchical view of folders and files. They can click on folders to navigate into them, click on files to preview or download, and use breadcrumbs to go back up. A 'New Folder' button allows creation. Options to rename, move, and delete files/folders are available via context menus or action buttons.
* **Details:** This is the primary user interaction area. It requires efficient rendering of potentially large numbers of files. Features include displaying file names, sizes, modification dates, and icons. Actions like renaming, moving, and deleting should trigger appropriate API calls to the respective cloud provider.
3. **File Upload & Download:**
* **User Flow:** Users can drag and drop files/folders into the VFS interface or use a dedicated 'Upload' button to select files from their local system. Progress indicators show upload status. Clicking a file initiates a download prompt. Large file handling with multipart uploads should be considered for providers like S3.
* **Details:** Drag-and-drop functionality needs robust handling of both files and directories. Download requires generating appropriate links or streaming content.
4. **Search Functionality (QMD Plugin Integration):**
* **User Flow:** A prominent search bar is available across the application. Users type keywords, and the system searches file names, potentially metadata, and even file content (if feasible and supported by the backend/provider capabilities). Search results are displayed in a dedicated view, showing file paths and relevant snippets.
* **Details:** This is an advanced feature. For file content search, it might require a backend indexing service or leveraging provider-specific search capabilities (like S3 Select or specialized search services). Initially, it can focus on file/folder name and metadata search.
5. **Provider Agnostic Abstraction Layer:**
* **User Flow:** This is a backend/architectural feature that is transparent to the end-user but enables the VFS and other features to work seamlessly across different storage providers.
* **Details:** A service layer within the application (or a separate microservice) will abstract the differences between cloud storage APIs. It will handle authentication, bucket operations (list, create, delete), file operations (upload, download, delete, copy, move), and potentially metadata fetching for each supported provider.
UI/UX DESIGN:
- **Layout:** A clean, minimalist, and intuitive interface. A primary navigation sidebar (collapsible) for connections and possibly bookmarks/recent files. The main content area will display the VFS or search results. A header bar will contain the search input and user profile/settings access.
- **Color Palette:** A modern and professional palette. Primary colors could be shades of deep blue or grey for backgrounds and containers, with vibrant accent colors (e.g., teal, green, or orange) for interactive elements, buttons, and highlights. Dark mode support is essential.
- **Typography:** Use a readable sans-serif font family (e.g., Inter, Roboto, or system defaults). Clear hierarchy using font weights and sizes for headings, file names, metadata, etc.
- **Responsive Design:** Mobile-first approach. The layout must adapt seamlessly to various screen sizes. On mobile, the sidebar might become a bottom navigation or a slide-out menu. File lists should be optimized for touch interaction.
- **Interactions:** Subtle hover effects on files and buttons. Smooth transitions for navigation, modal opening/closing, and loading states. Clear visual feedback for actions (e.g., upload progress bars, success/error messages).
COMPONENT BREAKDOWN:
- **`App.jsx`**: Main application component, sets up routing and global layout.
- **`Layout.jsx`**: Wrapper component for overall page structure, including header, sidebar, and main content area.
- **`Sidebar.jsx`**: Collapsible navigation panel showing connections, maybe favorites.
- Props: `connections` (array), `onSelectConnection` (function).
- **`Header.jsx`**: Contains the search bar, user profile access.
- Props: `onSearchChange` (function).
- **`VFSView.jsx`**: Renders the virtual file system interface (file list, breadcrumbs, actions).
- Props: `currentPath` (string), `files` (array), `isLoading` (boolean), `onNavigate` (function), `onFileAction` (function).
- **`FileItem.jsx`**: Renders a single file or folder in the list.
- Props: `item` (object: {name, type, size, modifiedDate}), `onClick` (function), `onContextMenu` (function).
- **`Breadcrumbs.jsx`**: Displays the current path and allows navigation.
- Props: `path` (string), `onNavigate` (function).
- **`ConnectionManager.jsx`**: Component for adding, editing, and removing cloud connections.
- Props: `connections` (array), `onSaveConnection` (function), `onDeleteConnection` (function).
- **`ConnectionForm.jsx`**: Form for inputting cloud provider credentials.
- Props: `providerOptions` (array), `onSubmit` (function).
- **`SearchBar.jsx`**: Input component for search queries.
- Props: `value` (string), `onChange` (function).
- **`UploadArea.jsx`**: Component for handling file drag-and-drop uploads.
- Props: `onUpload` (function).
- **`Modal.jsx`**: Generic modal component for dialogs (e.g., rename, delete confirmation).
- **`Notification.jsx`**: Component for displaying user feedback messages (toast notifications).
DATA MODEL:
- **`AuthState`**: `{ isAuthenticated: boolean, user: object | null, error: string | null }` (Managed by Zustand)
- **`ConnectionsState`**: `{ connections: Array<object>, activeConnection: object | null, isLoading: boolean, error: string | null }`
- Each connection object: `{ id: string, alias: string, provider: 's3' | 'r2' | 'vercel' | 'local', credentials: object }`
- **`VFSState`**: `{ currentPath: string, files: Array<object>, isLoading: boolean, error: string | null }`
- Each file/folder object: `{ name: string, type: 'file' | 'folder', size: number, modifiedDate: string, path: string }`
- **`SearchState`**: `{ query: string, results: Array<object>, isLoading: boolean }`
- **Mock Data Example (`files` array):**
```json
[
{ "name": "Documents", "type": "folder", "size": 0, "modifiedDate": "2023-10-27T10:00:00Z", "path": "/Documents" },
{ "name": "report.pdf", "type": "file", "size": 1024500, "modifiedDate": "2023-10-26T15:30:00Z", "path": "/Documents/report.pdf" },
{ "name": "Images", "type": "folder", "size": 0, "modifiedDate": "2023-10-25T09:00:00Z", "path": "/Images" },
{ "name": "photo1.jpg", "type": "file", "size": 2048000, "modifiedDate": "2023-10-25T11:20:00Z", "path": "/Images/photo1.jpg" },
{ "name": "vacation.mp4", "type": "file", "size": 512000000, "modifiedDate": "2023-10-20T18:00:00Z", "path": "/vacation.mp4" }
]
```
- **Mock Data Example (`connections` array):**
```json
[
{ "id": "conn-123", "alias": "My S3 Bucket", "provider": "s3", "credentials": { "region": "us-east-1", "bucketName": "my-awesome-bucket" } },
{ "id": "conn-456", "alias": "R2 - My Files", "provider": "r2", "credentials": { "account_id": "...", "access_key_id": "...", "secret_access_key": "...", "endpoint": "https://..." } }
]
```
ANIMATIONS & INTERACTIONS:
- **Hover Effects:** Subtle background color changes or slight scaling on buttons, file items, and navigation links.
- **Transitions:** Smooth transitions for page changes (using React Router's `<CSSTransition>` or Framer Motion), modal popups, sidebar collapse/expand.
- **Loading States:** Implement skeleton loaders or spinners for file lists, connection attempts, and search operations. Disable buttons and inputs while operations are in progress.
- **Micro-interactions:** Visual feedback on successful file uploads (e.g., file briefly highlights), delete confirmations, drag-and-drop visual cues (e.g., dashed border on drop target).
- **Menu Animations:** Smooth opening/closing animations for context menus on file items.
EDGE CASES:
- **Empty State:** Display friendly messages and clear calls-to-action when there are no connections, no files in a directory, or no search results.
- **Error Handling:** Gracefully handle API errors (network issues, invalid credentials, permission denied). Display user-friendly error messages using the `Notification` component. Implement retry mechanisms for transient errors.
- **Validation:** Client-side and server-side validation for connection credentials (e.g., checking for required fields, format of keys/endpoints). Input validation for file renaming and folder creation.
- **Large File Handling:** Implement chunking/multipart uploads for large files to prevent timeouts and improve reliability. Provide clear progress feedback.
- **Security:** Never store sensitive credentials directly in the frontend state or local storage without proper encryption or secure handling. Consider using environment variables for API endpoints and potentially a secure backend service for credential management if direct browser-to-cloud is too insecure for certain providers.
- **Accessibility (a11y):** Use semantic HTML, ensure proper ARIA attributes, keyboard navigation support for all interactive elements, and sufficient color contrast. Use accessible UI primitives like Radix UI.
- **Rate Limiting:** Be mindful of API rate limits imposed by cloud providers and implement appropriate delays or backoff strategies if necessary.
SAMPLE DATA:
Refer to the Data Model section for mock data examples for `files` and `connections`. Additional examples:
- **Mock Error Object:** `{ code: 'AccessDenied', message: 'The provided credentials are not valid or lack permissions.' }`
- **Mock Upload Progress:** `{ fileName: 'large_video.mp4', progress: 75, uploadedBytes: 384000000, totalBytes: 512000000 }`
- **Mock Search Result:** `{ name: 'final_report_v2.docx', type: 'file', size: 512000, modifiedDate: '2023-10-27T11:00:00Z', path: '/Projects/Q4Report/final_report_v2.docx' }`
- **Provider Options for Form:** `[{ label: 'Amazon S3', value: 's3' }, { label: 'Cloudflare R2', value: 'r2' }, { label: 'Vercel Blob', value: 'vercel' }]`
DEPLOYMENT NOTES:
- **Build Settings:** Configure Vite for production build (`vite build`). Ensure appropriate base path configuration if deploying to a subdirectory.
- **Environment Variables:** Use `.env` files for managing API keys (if any backend service is used), endpoint URLs, and other configuration settings. Ensure sensitive keys are not committed to version control.
- **Performance Optimizations:** Code splitting via React.lazy and Suspense for route-based splitting. Image optimization (if applicable). Memoization using `React.memo` and `useMemo`/`useCallback` where necessary. Efficient state management to prevent unnecessary re-renders. Tree shaking via Vite.
- **Static Hosting:** Deploy the built static assets to a platform like Vercel, Netlify, or AWS S3/CloudFront. Configure appropriate caching headers.
- **CORS:** Ensure correct CORS configuration on the cloud storage provider side if direct browser uploads are implemented, allowing requests from your application's domain.
- **HTTPS:** Always use HTTPS for secure data transfer.