Architecture
BucketDrive is a monorepo built on Next.js 15, React 19, and TypeScript. Here's how the pieces fit together.
System Overview
┌─────────────────────────────────────────────────────────────┐
│ BucketDrive Dashboard │
│ (Next.js 15 + React 19) │
├─────────────────────────────────────────────────────────────┤
│ UI Layer │
│ ├── File Browser (Tree, Column, List views) │
│ ├── Built-in Editor (syntax highlighting) │
│ ├── Bucket Sites (iframe preview + deploy) │
│ ├── AI Chat (Claude + CoT reasoning) │
│ └── Provider Management │
├─────────────────────────────────────────────────────────────┤
│ State Layer │
│ ├── Zustand (client state) │
│ ├── React Query (server state) │
│ └── BroadcastChannel (multi-tab coordination) │
├─────────────────────────────────────────────────────────────┤
│ Sync Layer (Bucket Sync) │
│ ├── OPFS (Origin Private File System) │
│ ├── IndexedDB (metadata + manifest) │
│ ├── Service Worker (offline fetch) │
│ └── Web Crypto API (AES-256-GCM encryption) │
├─────────────────────────────────────────────────────────────┤
│ SDK Layer │
│ ├── S3Worm (file operations + schema management) │
│ ├── BucketDrive API Client │
│ └── Smol Agent (AI tool framework) │
├─────────────────────────────────────────────────────────────┤
│ Storage │
│ └── Any S3-Compatible Provider │
│ (Storj, AWS, Backblaze, MinIO, DigitalOcean) │
└─────────────────────────────────────────────────────────────┘
Monorepo Structure
Apps
| App | Technology | Purpose |
|---|
dashboard | Next.js 15.3.6, React 19 | Main BucketDrive application |
landing | Next.js 15.3.6, React 19 | Landing site + documentation |
playground | Next.js 15.3.6 | Interactive SDK demo |
Packages
| Package | Version | Purpose |
|---|
s3worm | 0.3.3 | S3 file system SDK |
bucket-sync | 0.1.0 | OPFS + IndexedDB sync engine |
smol-agent | 0.1.0 | AI agent framework |
bucketdrive-types | 0.1.0 | Shared TypeScript types |
bucketdrive-ui-kit | 0.1.0 | React component library |
bucketdrive-api-client | 0.1.0 | TypeScript API client |
milfy | - | CLI for schema DSL + rules |
Technology Stack
Frontend
- Next.js 15 with App Router and Turbopack
- React 19 with Server Components
- TypeScript in strict mode
- Tailwind CSS 4 with custom cyberpunk theme
- Radix UI for accessible component primitives
- Zustand for client state management
- Three.js for 3D visualizations
Storage
- OPFS — Browser-native file system for local cache
- IndexedDB — Metadata and manifest storage via Dexie.js
- AWS S3 SDK — Universal S3 operations
- Web Crypto API — AES-256-GCM encryption, SHA-256 hashing
AI
- Anthropic Claude — Language model for AI chat
- Smol Agent — Tool-use framework for file operations
- Chain of Thought — Multi-step reasoning with iteration
Infrastructure
- pnpm workspaces for monorepo management
- Vercel for deployment
- GitHub Actions for CI/CD
- Changesets for versioning
Data Flow
File Upload
User drops file → Dashboard UI → Presign API → S3 Direct Upload
↓
IndexedDB manifest update
↓
OPFS local cache write
Bucket Sync
Local write → OPFS + IndexedDB → Sync Queue → S3 Push
Remote change → S3 Poll → Compare ETags → OPFS Pull
Conflict → Detect → Strategy (keep-local/remote/both)
AI Chat
User message → API Route → Claude API → Tool calls → S3Worm → Response
↓
CoT iterations (up to 8)
↓
Streaming response to UI
Design Principles
- Local-First — Browser storage is the source of truth. S3 is the backup.
- Offline-Ready — Everything works without internet. Sync is eventual.
- Provider-Agnostic — Any S3 endpoint works. No vendor lock-in.
- Type-Safe — TypeScript strict mode everywhere. Zod for runtime validation.
- Composable — Each package works independently. Use what you need.