## Project: PersistentDocs - Cloud Document Storage Platform

### 1. OVERVIEW

**Goal:** Build a Cloudflare Worker-based cloud document storage application that serves as a **Dropbox alternative at half the cost**.

**UI Vision:** Modern, polished, and intuitive — similar to AWS Console's design language with clean typography, subtle shadows, professional color scheme, and smooth animations.

**Technology Stack:**
- Frontend: HTML5, CSS3, JavaScript (vanilla or lightweight framework)
- Backend: Cloudflare Workers (single `worker.js` file)
- Database: AWS DynamoDB
- Storage: Cloudflare R2 or Backblaze B2 (configurable)

---

### 2. CONFIGURATION

**Configuration Variables (top of worker.js):**
```javascript
const CONFIG = {
  // Storage Provider: "CLOUDFLARE_R2" | "BACKBLAZE_B2" (extensible for future providers)
  STORAGE_VENDOR: "CLOUDFLARE_R2",

  // Cloudflare R2 credentials
  R2_ACCOUNT_ID: "",
  R2_ACCESS_KEY_ID: "",
  R2_SECRET_ACCESS_KEY: "",
  R2_BUCKET_NAME: "",

  // Backblaze B2 credentials
  B2_APPLICATION_KEY_ID: "",
  B2_APPLICATION_KEY: "",
  B2_BUCKET_ID: "",
  B2_BUCKET_NAME: "",

  // AWS DynamoDB credentials
  AWS_REGION: "",
  AWS_ACCESS_KEY_ID: "",
  AWS_SECRET_ACCESS_KEY: "",

  // Email service (Resend - for OTP/password reset)
  RESEND_API_KEY: "",
  EMAIL_FROM_ADDRESS: "support@persistentdocs.com",
  EMAIL_FROM_NAME: "PersistentDocs",

  // Security
  JWT_SECRET: "",
  SESSION_EXPIRY_HOURS: 24,
  OTP_EXPIRY_MINUTES: 15,
  PASSWORD_RESET_LINK_EXPIRY_HOURS: 1,

  // Application
  APP_NAME: "PersistentDocs",
  APP_URL: "",
  MAX_FILE_SIZE_MB: 100,
  MAX_STORAGE_PER_USER_GB: 15,

  // Signed URLs
  SIGNED_URL_EXPIRY_SECONDS: 172800,  // 48 hours

  // Feature Settings
  MAX_RECENT_FILES: 50,
  NOTIFICATION_RETENTION_DAYS: 30,
  MAX_COMMENT_LENGTH: 2000,
  FILE_REQUEST_DEFAULT_EXPIRY_DAYS: 30,
  TRASH_RETENTION_DAYS: 30,
};
```

---

### 3. DATABASE DESIGN (AWS DynamoDB - 4 Tables)

This design uses **4 consolidated tables** for optimal performance and cost:

| Table | Purpose | Contains |
|-------|---------|----------|
| `persistentdocs-users` | User-centric data | Profiles, emails, phones, sessions, notifications, favorites, recent files |
| `persistentdocs-documents` | Document-centric data | Files, folders, versions, comments, shares |
| `persistentdocs-lookups` | Reverse lookups | Email→User, Phone→User, Token→Share mappings |
| `persistentdocs-audit` | Audit trail | All activity logs (separate for compliance & TTL) |

---

#### 3.1 Table: `persistentdocs-users`

All user-related data in one table using composite keys.

**Primary Key:** `PK` (Partition Key) + `SK` (Sort Key)

| SK Pattern | Type | Key Attributes |
|------------|------|----------------|
| `PROFILE` | User Profile | first_name, last_name, password_hash, storage_used_bytes, account_status |
| `EMAIL#<email>` | Email Address | is_primary, verified, verification_token |
| `PHONE#<number>` | Phone Number | type ("personal"\|"work"), is_primary, verified |
| `SESSION#<id>` | Session | expires_at, ip_address, user_agent, device_name |
| `NOTIF#<timestamp>#<id>` | Notification | type, title, message, link, is_read |
| `FAV#<doc_id>` | Favorite | added_at |
| `RECENT#<timestamp>` | Recent File | document_id, action |
| `FILEREQ#<id>` | File Request | title, target_folder_id, public_token, expires_at |

---

#### 3.2 Table: `persistentdocs-documents`

All document-related data in one table.

| SK Pattern | Type | Key Attributes |
|------------|------|----------------|
| `META` | Document/Folder Metadata | owner_user_id, file_name, file_extension, mime_type, storage_path |
| `VERSION#<number>` | Version | storage_path, file_size_bytes, checksum, created_by |
| `COMMENT#<timestamp>#<id>` | Comment | user_id, content, parent_comment_id, is_resolved |
| `SHARE#<id>` | Share | shared_with_user_id, share_type, permission, public_token |

**GSIs:**
- `GSI1`: owner_user_id + created_at (List user's documents)
- `GSI2`: parent_folder_id + file_name (List folder contents)
- `GSI3`: shared_with_user_id + created_at (Shared with me)
- `GSI4`: owner_user_id + trashed_at (Trash listing)

---

#### 3.3 Table: `persistentdocs-lookups`

Reverse lookup table for finding users/documents by email, phone, or token.

| PK Pattern | SK | Purpose |
|------------|-----|---------|
| `EMAIL#<email>` | `USER` | Find user by email |
| `PHONE#<number>` | `USER` | Find user by phone |
| `SHARETOKEN#<token>` | `SHARE` | Find share by public token |
| `UPLOADTOKEN#<token>` | `FILEREQ` | Find file request by token |

---

#### 3.4 Table: `persistentdocs-audit`

Separate table for audit logs with TTL policy (90 days).

---

### 4. API ENDPOINTS

#### Authentication
```
POST /api/auth/register
POST /api/auth/login
POST /api/auth/logout
POST /api/auth/forgot-password
POST /api/auth/reset-password
GET  /api/auth/verify-email
```

#### Documents
```
GET    /api/documents
POST   /api/documents
GET    /api/documents/:id
PUT    /api/documents/:id
DELETE /api/documents/:id
GET    /api/documents/:id/download
GET    /api/documents/:id/versions
```

#### Folders
```
POST   /api/folders
PUT    /api/folders/:id
DELETE /api/folders/:id
```

#### Sharing
```
POST   /api/shares
GET    /api/shares
DELETE /api/shares/:id
GET    /api/shared-with-me
```

#### Favorites & Recent
```
GET    /api/favorites
POST   /api/favorites/:documentId
DELETE /api/favorites/:documentId
GET    /api/recent
```

#### Notifications
```
GET    /api/notifications
PUT    /api/notifications/:id/read
PUT    /api/notifications/read-all
```

---

### 5. USER INTERFACE

#### 5.0 Global Design System (AWS Console-Inspired)

**Brand Colors:**
- Primary: #FF9900 (Orange)
- Secondary: #232F3E (Squid Ink)
- Success: #1D8102 (Green)
- Warning: #8A6116 (Amber)
- Error: #D13212 (Red)
- Info: #0073BB (Blue)

**Key UI Pages:**
1. Landing Page - Hero section, features, pricing comparison
2. Registration Page - Multi-field form with validation
3. Login Page - Email/password with forgot password link
4. File Explorer - Windows Explorer-like interface
5. File Viewer/Editor - Monaco Editor for code, PDF.js for PDFs
6. Sharing Interface - User search, permissions, public links
7. Account Settings - Profile, security, storage analytics

#### File Explorer Layout
- Left sidebar (240px): Quick access, folders, storage usage
- Main content: Grid/list view of files
- Toolbar: Upload, New, View toggle, Sort, Filter
- Breadcrumb navigation
- Context menus for files/folders

#### Monaco Editor Integration
- Syntax highlighting for 50+ languages
- Auto-save with debouncing
- Split view for Markdown preview
- Diff editor for file comparison

---

### 6. STORAGE & CACHING

**Virtual Folders:** Folders exist only in DynamoDB metadata, NOT in storage.
- Move/rename operations only update DynamoDB
- Storage paths remain unchanged
- Efficient and cost-effective

**Signed URLs:** For downloads and video streaming
- 48-hour expiry
- Direct B2/R2 to user streaming
- No Worker memory issues

---

### 7. SECURITY

- Password hashing: scrypt or PBKDF2 (Web Crypto API)
- Sessions: JWT or secure random tokens
- Rate limiting: DynamoDB atomic counters
- Account lockout: 5 failed attempts = 15-minute lock
- CSRF protection tokens
- Input validation & sanitization

---

### 8. EMAIL SERVICE (Resend)

**Setup:**
1. Add domain in Resend dashboard
2. Add DNS records in Cloudflare (SPF, DKIM, DMARC)
3. Get API key
4. Use simple fetch() calls from Worker

**Email Types:**
- Email verification
- OTP codes
- Password reset links
- Share notifications
- Security alerts

---

### 9. FEATURES CHECKLIST

**Security:** HTTPS, CSRF, rate limiting, account lockout
**UX:** Drag-drop upload, bulk operations, keyboard shortcuts
**File Management:** Trash, versioning, favorites, recent files
**Sharing:** Password protection, expiring links, view-only mode
**Notifications:** In-app bell icon, email notifications
**Analytics:** Storage breakdown, largest files list

---

### 10. PROJECT STRUCTURE

```
persistentdocs-worker/
├── wrangler.toml
├── package.json
├── src/
│   ├── index.js              # Entry point
│   ├── config/constants.js
│   ├── middleware/
│   ├── routes/
│   ├── services/
│   ├── utils/
│   └── templates/
└── tests/
```

---

### Key Implementation Notes

**DynamoDB Single-Table Design Benefits:**
- Single query returns document + versions + comments + shares
- Efficient GSI queries for all common access patterns
- Consistent single-digit millisecond latency at any scale

**Cost Comparison:**
| Design | Tables | GSIs | Cost |
|--------|--------|------|------|
| Old (13 tables) | 13 | 17+ | $$$ |
| New (4 tables) | 4 | 6 | $ |

---

*Full specification includes detailed UI wireframes, code examples, and implementation patterns.*