# kern/filepizza architecture

> Architecture diagram of the GitHub repository kern/filepizza, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kern/filepizza
- Repository: https://github.com/kern/filepizza

## Overview

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: [`src/app/api/create/route.ts`](https://github.com/kern/filepizza/blob/main/src/app/api/create/route.ts) (Channel APIs), [`src/components/Uploader.tsx`](https://github.com/kern/filepizza/blob/main/src/components/Uploader.tsx) (Uploader), [`src/components/Downloader.tsx`](https://github.com/kern/filepizza/blob/main/src/components/Downloader.tsx) (Downloader), [`src/components/WebRTCProvider.tsx`](https://github.com/kern/filepizza/blob/main/src/components/WebRTCProvider.tsx) (WebRTC Layer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g1["Client UI"]
  node_n1["Landing<br/>route<br/>[page.tsx]"]
  node_n2["Download Page<br/>route<br/>[page.tsx]"]
  node_n3["Reported Page<br/>route<br/>[page.tsx]"]
  node_n4["Uploader<br/>ui flow<br/>[Uploader.tsx]"]
  node_n5["Downloader<br/>ui flow<br/>[Downloader.tsx]"]
  node_n6["Shared UI<br/>components<br/>[ProgressBar.tsx]"]
end

subgraph group_g2["Server API"]
  node_n7["Channel APIs<br/>api routes<br/>[route.ts]"]
  node_n8[("Channel Store<br/>state store<br/>[channel.ts]")]
end

subgraph group_g3["Transfer Core"]
  node_n9{{"PeerJS Bridge<br/>signaling<br/>[peerjs.js]"}}
  node_n10{{"WebRTC Layer<br/>transport<br/>[WebRTCProvider.tsx]"}}
  node_n11{{"NAT Traversal<br/>stun/turn<br/>[coturn.ts]"}}
  node_n12["Transfer Hooks<br/>state hooks<br/>[useDownloader.ts]"]
  node_n13["Zip Stream<br/>streaming<br/>[zip-stream.ts]"]
  node_n14["Download Utils<br/>download helpers<br/>[download.ts]"]
end

subgraph group_g4["Shared Core"]
  node_n15["Config & Types<br/>shared core<br/>[config.ts]"]
  node_n16["Slug & Routes<br/>routing helpers<br/>[slugs.ts]"]
  node_n17["Logging & FS<br/>platform helpers<br/>[log.ts]"]
end

subgraph group_g5["Ops & Assets"]
  node_n18["Runtime Assets<br/>[sw.js]"]
  node_n19["Packaging<br/>ops"]
end

node_n1 -->|"starts upload"| node_n4
node_n2 -->|"receives file"| node_n5
node_n4 -->|"uses"| node_n12
node_n5 -->|"uses"| node_n12
node_n4 -->|"renders"| node_n6
node_n5 -->|"renders"| node_n6
node_n4 -->|"creates channel"| node_n7
node_n5 -->|"joins channel"| node_n7
node_n7 -->|"stores metadata"| node_n8
node_n7 -->|"signals peers"| node_n9
node_n9 -->|"connects"| node_n10
node_n10 -->|"uses"| node_n11
node_n10 -->|"streams multi-file"| node_n13
node_n10 -->|"downloads"| node_n14
node_n10 -->|"orchestrated by"| node_n12
node_n4 -->|"shares protocol"| node_n15
node_n5 -->|"shares protocol"| node_n15
node_n7 -->|"validates"| node_n15
node_n4 -->|"uses links"| node_n16
node_n7 -->|"routes"| node_n16
node_n17 -->|"supports"| node_n7
node_n18 -->|"supports streaming"| node_n14
node_n18 -->|"enhances"| node_n5
node_n19 -->|"deploys"| node_n1
node_n19 -->|"deploys"| node_n7

click node_n1 "https://github.com/kern/filepizza/blob/main/src/app/page.tsx"
click node_n2 "https://github.com/kern/filepizza/blob/main/src/app/download/[...slug]/page.tsx"
click node_n3 "https://github.com/kern/filepizza/blob/main/src/app/reported/page.tsx"
click node_n4 "https://github.com/kern/filepizza/blob/main/src/components/Uploader.tsx"
click node_n5 "https://github.com/kern/filepizza/blob/main/src/components/Downloader.tsx"
click node_n6 "https://github.com/kern/filepizza/blob/main/src/components/ProgressBar.tsx"
click node_n7 "https://github.com/kern/filepizza/blob/main/src/app/api/create/route.ts"
click node_n8 "https://github.com/kern/filepizza/blob/main/src/channel.ts"
click node_n9 "https://github.com/kern/filepizza/blob/main/bin/peerjs.js"
click node_n10 "https://github.com/kern/filepizza/blob/main/src/components/WebRTCProvider.tsx"
click node_n11 "https://github.com/kern/filepizza/blob/main/src/coturn.ts"
click node_n12 "https://github.com/kern/filepizza/blob/main/src/hooks/useDownloader.ts"
click node_n13 "https://github.com/kern/filepizza/blob/main/src/zip-stream.ts"
click node_n14 "https://github.com/kern/filepizza/blob/main/src/utils/download.ts"
click node_n15 "https://github.com/kern/filepizza/blob/main/src/config.ts"
click node_n16 "https://github.com/kern/filepizza/blob/main/src/slugs.ts"
click node_n17 "https://github.com/kern/filepizza/blob/main/src/log.ts"
click node_n18 "https://github.com/kern/filepizza/blob/main/public/sw.js"
click node_n19 "https://github.com/kern/filepizza/tree/main/Dockerfile"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_n1,node_n2,node_n3,node_n4,node_n5,node_n6 toneBlue
class node_n7,node_n8 toneAmber
class node_n9,node_n10,node_n11,node_n12,node_n13,node_n14 toneMint
class node_n15,node_n16,node_n17 toneRose
class node_n18,node_n19 toneIndigo
```

## Components

### Client UI

Browser-facing upload and download journeys

- [Landing](https://github.com/kern/filepizza/blob/main/src/app/page.tsx): route · Upload start page at / · `src/app/page.tsx`
- [Download Page](https://github.com/kern/filepizza/blob/main/src/app/download/[...slug]/page.tsx): route · Downloader entry at /download/[...slug] · `src/app/download/[...slug]/page.tsx`
- [Reported Page](https://github.com/kern/filepizza/blob/main/src/app/reported/page.tsx): route · Abuse and terms reporting destination · `src/app/reported/page.tsx`
- [Uploader](https://github.com/kern/filepizza/blob/main/src/components/Uploader.tsx): ui flow · File selection, transfer start/stop, and progress · `src/components/Uploader.tsx`
- [Downloader](https://github.com/kern/filepizza/blob/main/src/components/Downloader.tsx): ui flow · Receive, unlock, and save incoming files · `src/components/Downloader.tsx`
- [Shared UI](https://github.com/kern/filepizza/blob/main/src/components/ProgressBar.tsx): components · Reusable controls like buttons, progress, password, copy, and status · `src/components/ProgressBar.tsx`

### Server API

Next.js routes that coordinate transfers

- [Channel APIs](https://github.com/kern/filepizza/blob/main/src/app/api/create/route.ts): api routes · Create, renew, destroy, and ICE signaling endpoints · `src/app/api/create/route.ts`
- [Channel Store](https://github.com/kern/filepizza/blob/main/src/channel.ts): state store · Ephemeral channel metadata with Redis or memory fallback · `src/channel.ts`

### Transfer Core

Peer-to-peer transport and connection establishment

- [PeerJS Bridge](https://github.com/kern/filepizza/blob/main/bin/peerjs.js): signaling · Peer discovery and WebRTC signaling via PeerJS · `bin/peerjs.js`
- [WebRTC Layer](https://github.com/kern/filepizza/blob/main/src/components/WebRTCProvider.tsx): transport · Browser-to-browser file transfer over WebRTC · `src/components/WebRTCProvider.tsx`
- [NAT Traversal](https://github.com/kern/filepizza/blob/main/src/coturn.ts): stun/turn · STUN fallback and optional TURN credential support · `src/coturn.ts`
- [Transfer Hooks](https://github.com/kern/filepizza/blob/main/src/hooks/useDownloader.ts): state hooks · Uploader and downloader side effects and connection state · `src/hooks/useDownloader.ts`
- [Zip Stream](https://github.com/kern/filepizza/blob/main/src/zip-stream.ts): streaming · Streaming archive generation for multi-file downloads · `src/zip-stream.ts`
- [Download Utils](https://github.com/kern/filepizza/blob/main/src/utils/download.ts): download helpers · Browser download support and stream helpers · `src/utils/download.ts`

### Shared Core

Code used across UI and API layers

- [Config & Types](https://github.com/kern/filepizza/blob/main/src/config.ts): shared core · Protocol constants, typed state, and shared messages · `src/config.ts`
- [Slug & Routes](https://github.com/kern/filepizza/blob/main/src/slugs.ts): routing helpers · Slug generation and route mapping for share links · `src/slugs.ts`
- [Logging & FS](https://github.com/kern/filepizza/blob/main/src/log.ts): platform helpers · Logging and filesystem-adjacent helpers used by client and server code · `src/log.ts`

### Ops & Assets

Deployment, runtime helpers, and browser assets

- [Runtime Assets](https://github.com/kern/filepizza/blob/main/public/sw.js): assets · Service worker, stream page, and static public files · `public/sw.js`
- [Packaging](https://github.com/kern/filepizza/tree/main/Dockerfile): ops · Docker, compose, CI, and browser test setup · `Dockerfile`

## Connections

- 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
