ODrive-01 — Storage Abstraction Layer MVP

Core Objective

Build a lightweight SaaS Storage Abstraction Layer that unifies multiple cloud storage providers through an adapter-based architecture, exposing a single consistent API and UI. This is not a Google Drive clone but a vendor-agnostic storage management platform.

Focus: Clean architecture, modularity, and immediate functionality over feature completeness.

---

Technical Foundations

Architecture Principles

• Adapter Pattern: All provider integrations must implement a standardized interface
• Repository Pattern: Business logic interacts only with abstract repositories
• Dependency Injection: Core services must be replaceable without code changes
• Modular Monolith: Single deployable unit with clear separation of concerns
• Vendor Agnostic: No tight coupling to any storage provider or database

Tech Stack

• Frontend: React + TypeScript (Vite + Tailwind CSS + shadcn/ui)
• Runtime: Cloudflare Workers/Pages compatible
• Database: Repository pattern implementation (no direct SQL exposure)

Security Requirements

• OAuth tokens encrypted before storage (Secret Manager interface required)
• No vendor API calls from business logic
• Token rotation policy to be defined

---

Project Structure

/apps
  /web          # Frontend application

/packages
  /core         # Business logic and interfaces
  /database     # Repository implementations
  /storage      # Storage abstraction layer
  /auth         # Authentication services
  /shared       # Cross-cutting utilities

/adapters
  /google-drive # Provider implementations
  /onedrive
  /telegram
  /r2          # Cloudflare R2
  /s3          # Amazon S3

---

MVP Scope

1. Authentication

• Magic link (no social login)
• Replaceable implementation (future OAuth providers)
• Session management with token encryption

2. Dashboard

Immediate post-login experience with:

• Top Navbar: ODrive branding, search, user menu
• Sidebar: Dashboard, Connections, Explorer, Transfers, Settings
• Main Content: Dynamic based on selected view

3. Core Pages

Homepage (Minimal)

• Hero Section: "Omni Drive. Every Storage" with provider grid
• Supported Providers: Google Drive, OneDrive, Telegram, Cloudflare R2, Amazon S3
• Footer: Logo, Documentation, Privacy, Terms, GitHub

Connections (Critical Path)

• Add unlimited accounts per provider
• Connection fields: Provider, Name, Status, Created Date, Actions
• Status management: Connect/Disconnect/Delete/Edit

Explorer

• Mock file browsing (replaceable later)
• Features: Search, Grid/List view, folder navigation, Recent/Favorites/Trash

Transfers

• Upload/Download queues with status management
• Actions: Retry, Cancel
• Completed/Failed state tracking

Settings

• Modular tabs: General, Workspace, Security, API, Experimental

---

Database Schema (Repository Pattern)

Rule: No direct SQL in UI layer - always use repositories.

---

Provider Integration

Requirements

1. Each provider must implement:

   interface StorageProvider {
     connect(): Promise<Connection>;
     disconnect(): Promise<void>;
     upload(file: File): Promise<FileMetadata>;
     download(fileId: string): Promise<Blob>;
     list(path?: string): Promise<FileMetadata[]>;
     delete(fileId: string): Promise<void>;
     rename(fileId: string, newName: string): Promise<void>;
     search(query: string): Promise<FileMetadata[]>;
   }
   

2. Mock implementations required until providers are live

3. Adapter registration must be dynamic (no code changes needed)

Initial Providers

• Google Drive
• OneDrive
• Telegram
• Cloudflare R2
• Amazon S3

---

Admin Panel (Hidden Route: /admin)

Authentication

• Separate admin credentials
• Features: Dashboard, Users, Connections, Providers, Feature Flags, Logs, Settings

Initial Scope

• No advanced analytics
• Basic user management
• Provider configuration
• Feature flag controls

---

UI/UX Guidelines

• Style: Minimal, clean, professional (light mode first)
• Components: Reusable library (Provider Card, Connection Card, etc.)
• Performance: Fast loading, no fake delays in mocks
• States: Empty, loading, error handling required

---

Future-Proofing

Adding New Providers

1. Create new adapter implementing StorageProvider interface
2. Register adapter in provider registry
3. No changes to core business logic required

Example: Adding Dropbox

• Create /adapters/dropbox package
• Implement all required methods
• Register in provider configuration
• Done

---

Success Criteria

✓ User authentication (magic link) ✓ Dashboard loads immediately post-login ✓ Connections page with mock provider support ✓ Explorer UI with basic navigation ✓ Transfer queue implementation ✓ Admin panel with basic controls ✓ Repository pattern implemented ✓ Adapter architecture prepared ✓ Zero vendor lock-in

---

Non-Functional Requirements

• Security: Token encryption, no direct vendor API exposure
• Performance: Optimistic UI updates, caching strategy
• Scalability: Modular design for horizontal scaling
• Maintainability: Clear separation of concerns, dependency injection
• Testability: Mockable interfaces, replaceable components