How kern/filepizza works
1. Overall shape
FilePizza is a browser-to-browser file transfer system built on Next.js. The app is split into a client-facing UI and a small server-side coordination layer. The server never handles file payloads; it only coordinates peers and stores transient channel metadata.
2. Primary data path
The transfer path is uploader browser → WebRTC → downloader browser. WebRTC carries the file data directly, so the backend is not in the file data path. This is the core architectural boundary of the repo.
3. Frontend application routes
The Next.js App Router defines the main user journeys:
- / landing / upload start
- /download/[...slug] downloader entry point
- /reported abuse/terms reporting destination
- API endpoints under /api/*
There is also a custom not-found page.
4. Upload and download UI subsystems
The UI is organized into role-specific components:
- Uploader and related controls for selecting files, starting/stopping transfers, and showing progress
- Downloader for receiving, unlocking, and saving files
- shared reusable UI pieces like buttons, progress, password, copy, spinner, and status components
Hooks such as useUploaderChannel, useUploaderConnections, and useDownloader encapsulate transfer state and side effects.
5. Signaling and channel lifecycle
The server API provides the lifecycle for a transfer “channel”:
- create to open/register a channel
- renew to extend its lifetime
- destroy to tear it down
- ice to exchange connectivity info
This layer coordinates peer discovery and expiry, but not file transport.
6. Peer connectivity layer
WebRTC signaling is mediated through PeerJS, with support for either an external PeerJS service or a self-hosted one. The repository includes bin/peerjs.js and configuration for PEERJS_HOST / PEERJS_PATH. This signaling layer is separate from the actual file transfer stream.
7. NAT traversal
The connection stack supports STUN/TURN configuration. If COTURN_ENABLED is set, the app can generate TURN credentials and use a TURN server; otherwise it falls back to a STUN server. This is important for peers behind restrictive NATs and is part of connection establishment, not storage.
8. State storage boundary
Channel metadata is stored in Redis when configured, with an in-memory fallback if REDIS_URL is absent. The architecture therefore treats server state as ephemeral and replaceable. Modules like redisClient, channel, slugs, and routes suggest centralized management of channel IDs, URLs, and expiry state.
9. Multi-file and streaming download support
Multiple uploaded files are bundled for the downloader, with streaming support to avoid buffering everything in memory. The repo includes:
- zip-stream.ts for streaming zip generation
- utils/download.ts
- public/sw.js and public/stream.html for Service Worker–assisted streaming downloads
This means the download experience is partly browser-managed and optimized for large transfers.
10. Security and safety features
Transfers are encrypted by WebRTC/DTLS, and the app adds optional password protection, terms acceptance, and a reporting flow. These features sit around the transfer workflow as safeguards rather than as core transport logic.
11. Shared client/server utilities
Shared modules like config.ts, types.ts, messages.ts, log.ts, fs.ts, coturn.ts, and utils/* support both UI and API code. They centralize protocol constants, typed state, logging, slug generation, and helper logic.
12. Operational packaging
The repo is productionized with Docker, docker-compose, GitHub Actions, and both unit and end-to-end tests. The stack is Next.js + React + TypeScript + Tailwind, with Vitest for unit tests and Playwright for browser transfer tests. This matters because the app’s correctness depends heavily on multi-browser interaction and signaling behavior.
Main entry points: route.ts Channel APIs · Uploader.tsx Uploader · Downloader.tsx Downloader · WebRTCProvider.tsx WebRTC Layer
Components 19
Client UI
Browser-facing upload and download journeys
- Landing · Upload start page at /
src/app/page.tsx - Download Page · Downloader entry at /download/[...slug]
src/app/download/[...slug]/page.tsx - Reported Page · Abuse and terms reporting destination
src/app/reported/page.tsx - Uploader · File selection, transfer start/stop, and progress
src/components/Uploader.tsx - Downloader · Receive, unlock, and save incoming files
src/components/Downloader.tsx - Shared UI · Reusable controls like buttons, progress, password, copy, and status
src/components/ProgressBar.tsx
Server API
Next.js routes that coordinate transfers
- Channel APIs · Create, renew, destroy, and ICE signaling endpoints
src/app/api/create/route.ts - Channel Store · Ephemeral channel metadata with Redis or memory fallback
src/channel.ts
Transfer Core
Peer-to-peer transport and connection establishment
- PeerJS Bridge · Peer discovery and WebRTC signaling via PeerJS
bin/peerjs.js - WebRTC Layer · Browser-to-browser file transfer over WebRTC
src/components/WebRTCProvider.tsx - NAT Traversal · STUN fallback and optional TURN credential support
src/coturn.ts - Transfer Hooks · Uploader and downloader side effects and connection state
src/hooks/useDownloader.ts - Zip Stream · Streaming archive generation for multi-file downloads
src/zip-stream.ts - Download Utils · Browser download support and stream helpers
src/utils/download.ts
Shared Core
Code used across UI and API layers
- Config & Types · Protocol constants, typed state, and shared messages
src/config.ts - Slug & Routes · Slug generation and route mapping for share links
src/slugs.ts - Logging & FS · Logging and filesystem-adjacent helpers used by client and server code
src/log.ts
Ops & Assets
Deployment, runtime helpers, and browser assets
- Runtime Assets · Service worker, stream page, and static public files
public/sw.js - Packaging · Docker, compose, CI, and browser test setup
Dockerfile
Connections 25
- Landing → Uploader: starts upload · Landing page hands off to the uploader flow
- Download Page → Downloader: receives file · Downloader page mounts the download experience
- Uploader → Transfer Hooks: uses · Uploader state and side effects are encapsulated in hooks
- Downloader → Transfer Hooks: uses · Downloader state and side effects are encapsulated in hooks
- Uploader → Shared UI: renders · Uploader composes shared controls and indicators
- Downloader → Shared UI: renders · Downloader composes shared controls and indicators
- Uploader → Channel APIs: creates channel · Uploader opens and maintains the transfer channel
- Downloader → Channel APIs: joins channel · Downloader looks up and participates in the transfer channel
- Channel APIs → Channel Store: stores metadata · API routes read and mutate ephemeral channel state
- Channel APIs → PeerJS Bridge: signals peers · ICE and channel lifecycle are mediated through PeerJS
- PeerJS Bridge → WebRTC Layer: connects · PeerJS signaling establishes the browser-to-browser WebRTC session
- WebRTC Layer → NAT Traversal: uses · WebRTC connection setup may use STUN or TURN
- WebRTC Layer → Zip Stream: streams multi-file · Multi-file transfers can be packaged as a streaming archive
- WebRTC Layer → Download Utils: downloads · Downloader-side helpers support browser saving and stream handling
- WebRTC Layer → Transfer Hooks: orchestrated by · Hooks coordinate peer lifecycle and transfer progress
- Uploader → Config & Types: shares protocol · Uploader relies on shared config and message types
- Downloader → Config & Types: shares protocol · Downloader relies on shared config and message types
- Channel APIs → Config & Types: validates · API behavior is driven by shared constants and types
- Uploader → Slug & Routes: uses links · Shareable download URLs are built from slug helpers
- Channel APIs → Slug & Routes: routes · Channel identifiers map into shareable route structures
- Logging & FS → Channel APIs: supports · Operational helpers support API behavior and diagnostics
- Runtime Assets → Download Utils: supports streaming · Service worker and stream page enable browser-managed downloads
- Runtime Assets → Downloader: enhances · Runtime assets improve downloader behavior in the browser
- Packaging → Landing: deploys · Packaging covers the application and browser workflows
- Packaging → Channel APIs: deploys · Packaging includes server coordination routes