How It Works
Deep dive into Pushduck's architecture, upload flow, and component design with visual diagrams
Architecture Overview
Pushduck is built on a direct-to-S3 upload pattern using presigned URLs, eliminating the need for your server to handle file data.
Core Principle: Files go directly from the client to S3 storage, bypassing your server entirely. This enables infinite scalability and edge-compatible deployments.
Upload Flow
Complete Upload Process
Key Benefits:
- ✅ Server never touches file data (saves bandwidth)
- ✅ Scales infinitely (S3 handles the load)
- ✅ Edge-compatible (no file streaming needed)
- ✅ Real-time progress tracking on client
Component Architecture
Configuration Flow
Type Safety System
Middleware Chain
Storage Provider System
Key Insight: All providers use the same S3-compatible API, so switching is just a configuration change.
Client State Management
Integration Points
Comparison: Pushduck vs AWS SDK
What You Need to Build with AWS SDK
Key Takeaways
Direct-to-S3 Pattern
Files upload directly to S3 storage, bypassing your server. This enables infinite scalability and edge deployment.
Lightweight Core
~7KB total bundle using aws4fetch instead of AWS SDK (~500KB). 71x smaller, edge-compatible.
Type-Safe APIs
End-to-end TypeScript inference from server schema to client hook. Catch errors at compile-time.
Extensible via Hooks
Middleware and lifecycle hooks provide integration points without bloating the library with built-in features.
Framework Agnostic
Universal Web Standard handlers work with 16+ frameworks via thin adapters.
Multi-Provider
Unified API works with 6 S3-compatible providers. Switch providers with just a config change.
Next Steps
Ready to build? Check out the Quick Start guide to get Pushduck running in 5 minutes.
Learn More:
- Philosophy & Scope - What Pushduck does (and doesn't do)
- API Reference - Complete API documentation
- Examples - Live demos and code samples