Skip to content
feedpipe

How It Works

feedpipe is built on a layered architecture that separates tunneling infrastructure from collaboration features.

Architecture Overview

┌─────────────────────────────────────────────────────────────────────────────┐
│                           FEEDPIPE (Application Layer)                       │
│  • Annotation overlay          • AI agent integration                        │
│  • Real-time collaboration     • Dashboard                                   │
│  • Event routing               • Developer notifications                     │
├─────────────────────────────────────────────────────────────────────────────┤
│                           PORTHOLE (Infrastructure Layer)                    │
│  • HTTP/WS tunneling           • URL lifecycle                              │
│  • Slug management             • CLI ↔ Relay WebSocket                      │
│  • Request proxying            • Response streaming                         │
└─────────────────────────────────────────────────────────────────────────────┘

Components

CLI (feedpipe)

The command-line interface that runs on your machine:

  • Creates a WebSocket connection to the relay
  • Proxies HTTP requests to your local server
  • Displays real-time feedback in the terminal
  • Optionally pipes events to AI agents

Relay (Cloudflare Workers)

The edge infrastructure that handles all traffic:

  • TunnelDurableObject: Manages CLI connections and request proxying
  • AnnotationRoom: Handles real-time annotation state and broadcasting
  • HTML Injection: Injects the toolbar script into HTML responses

Toolbar (@feedpipe/toolbar)

A Preact app injected into proxied pages:

  • Renders in a Shadow DOM to isolate styles
  • Connects to AnnotationRoom via WebSocket
  • Enables element selection and rectangle drawing
  • Displays existing annotations

Data Flow

HTTP Request

1. Reviewer requests: GET https://my-app.feedpipe.dev/dashboard
2. Feedpipe Relay Worker receives request
3. Worker routes to TunnelDurableObject
4. DO sends request to CLI via WebSocket
5. CLI proxies to localhost:3000/dashboard
6. CLI sends response back via WebSocket
7. Relay intercepts HTML, injects toolbar script
8. Response returned to reviewer

Annotation Created

1. Reviewer clicks element, types comment, submits
2. Toolbar sends annotation via WebSocket to AnnotationRoom
3. AnnotationRoom validates, stores, broadcasts to all clients
4. AnnotationRoom forwards event to TunnelDurableObject
5. TunnelDurableObject sends to CLI via WebSocket
6. CLI prints event to terminal
7. CLI optionally pipes to AI agent stdin

Technology Stack

  • Runtime: Cloudflare Workers + Durable Objects
  • CLI: Node.js with Commander, Chalk
  • Toolbar: Preact with Shadow DOM
  • Protocol: WebSocket with JSON messages
  • Storage: Durable Object storage (24h TTL)

Security

  • Session Tokens: Each tunnel has a unique session token
  • Password Protection: Optional password for tunnel access
  • 24h TTL: Tunnels automatically expire
  • No Persistence: Annotations are ephemeral