prooof of build

Stop manually recording demos. Proof-of-Build turns your screenshots, terminal output, and logs into professional video demos with AI-generated narration in minutes. Share without the editing hassle.

Comment

Inspiration

Creating demo videos for hackathons and projects is time-consuming. Recording, editing, and syncing narration takes hours. We wanted a way to turn development artifacts(screenshots, terminal output, and logs) into shareable videos automatically.

The idea came from the need to document work without interrupting flow. Instead of stopping to record, developers could upload artifacts and get a polished video demo with AI narration.

What it does

Proof-of-Build automatically transforms development artifacts into shareable video demos with AI-generated narration. Upload screenshots, terminal output, and logs via CLI, and the system:

  1. Classifies artifacts automatically (screenshots vs terminal vs logs)
  2. Generates a narration script using AI based on artifact context
  3. Synthesizes professional audio narration using ElevenLabs
  4. Composes a synchronized video demo with visuals and narration
  5. Provides a shareable URL for playback

No manual recording, editing, or video production required, just upload your artifacts and get a professional demo in minutes.

How we built it

We built Proof-of-Build as an event-driven system on Cloudflare's edge platform using a monorepo architecture.

System Architecture

The system consists of three main applications:

  • CLI Tool (apps/cli/): A TypeScript CLI using Commander.js that uploads artifacts to Cloudflare R2. It automatically classifies files and generates a manifest.json as the completion signal.

  • Worker Orchestrator (apps/worker/): A Cloudflare Worker that consumes queue messages triggered by R2 event notifications. It orchestrates a 5-stage pipeline:

    1. Ingest artifacts from R2
    2. Classify and validate artifacts
    3. Generate narration script using AI
    4. Synthesize audio with ElevenLabs
    5. Mark project as ready for playback

  • Playback UI (apps/pages/): A Hono-based Cloudflare Pages application that provides a read-only interface for viewing generated demos. It dynamically composes media at runtime, synchronizing screenshots with AI-generated narration.

Design Principles

We followed hexagonal architecture (ports & adapters) to keep core domain logic pure and testable. The packages/core/ package contains zero Cloudflare dependencies—just pure TypeScript functions for artifact classification, manifest creation, and state management.

Key Technologies

  • Cloudflare R2: Object storage for artifacts, scripts, audio, and state files
  • Cloudflare Queues: Event-driven processing triggered by R2 notifications
  • Cloudflare Workers: Serverless orchestration with sub-100ms cold starts
  • Cloudflare Pages: Edge-hosted playback UI with Hono
  • Zod: Runtime schema validation for all data contracts
  • TypeScript: Type safety across the monorepo
  • ElevenLabs API: Text-to-speech for narration
  • AI APIs: Script generation from artifact context

Challenges we ran into

  1. R2 Event Notifications Setup: Configuring R2 bucket notifications to trigger queue messages only on manifest.json uploads required careful suffix filtering. We learned that event notifications are the only way to trigger Workers from R2 without polling.

  2. Dynamic Media Composition: Instead of pre-rendering MP4s, we built a playback UI that dynamically loads screenshots and synchronizes them with audio at runtime. This required careful timing logic and handling of edge cases like missing assets or out-of-order uploads.

  3. Pure Core Logic: Keeping packages/core/ free of Cloudflare dependencies while still being useful required careful interface design. We created adapter layers (packages/adapters/) to bridge between pure domain logic and Cloudflare APIs.

  4. Monorepo Dependency Management: Since we used file: protocol instead of npm workspaces, we had to install dependencies in a specific order (schemas → core → apps). This was a tradeoff for simplicity but required clear documentation.

  5. Error Handling & State: Ensuring failures never go silent meant every pipeline stage must write explicit error states. The playback UI needed to handle three states: Processing, Ready, and Error—with clear messaging for each.

  6. Type Safety Across Packages: Maintaining TypeScript types across the monorepo while using local file: dependencies required careful configuration of tsconfig.json paths and ensuring all packages export proper type definitions.

Accomplishments that we're proud of

  1. Event-Driven Architecture: Built a fully event-driven system using R2 event notifications → Queues → Workers. No polling, no manual triggers—just upload artifacts and the system processes them automatically.

  2. Clean Architecture: Successfully implemented hexagonal architecture with pure domain logic that's testable without infrastructure. The core package has zero external dependencies, making it vendor-agnostic and easily extensible.

  3. Complete Pipeline: Built an end-to-end pipeline from artifact upload to video playback, with proper state management, error handling, and idempotent stages that can safely retry on failures.

  4. Dynamic Playback: Created a playback UI that dynamically composes media at runtime instead of requiring pre-rendered videos, making the system more flexible and efficient.

  5. Developer Experience: Built a CLI tool that's intuitive to use—just initialize a project, upload artifacts, and get a shareable demo URL.

  6. Type Safety: Maintained full TypeScript type safety across a monorepo with multiple packages and local dependencies.

What we learned

  1. Event-Driven Architecture: Using R2 event notifications → Queues → Workers created a decoupled, scalable pipeline. This pattern eliminates the need for polling and makes the system more responsive and cost-effective.

  2. Hexagonal Architecture in Practice: Separating core logic from infrastructure made testing easier and the codebase more maintainable. We could test artifact classification, manifest generation, and state machines without mocking Cloudflare APIs.

  3. Cloudflare's Edge Platform: Building on Workers, R2, Queues, and Pages provided a cohesive serverless stack. The global edge network ensures low latency for playback, and the pay-per-use model keeps costs low.

  4. State Management in Distributed Systems: Implementing idempotent, restartable pipeline stages was crucial. Each stage checks state before proceeding, allowing safe retries and recovery from failures.

  5. Monorepo Management: Learned the tradeoffs between npm workspaces and file: protocol dependencies. While file: requires manual dependency ordering, it gives explicit control and is simpler for smaller projects.

  6. Error Handling Best Practices: Ensuring failures never go silent required explicit error state management at every stage. This makes debugging easier and provides better user experience.

What's next for Proof-of-Build

  1. Enhanced AI Script Generation: Improve prompt engineering to generate more contextual and engaging narration based on artifact content and ordering.

  2. Multiple Voice Options: Add support for different voices, languages, and narration styles to match different project types and audiences.

  3. GitHub Actions Integration: Create a GitHub Action that automatically generates demo videos from CI/CD artifacts, making it seamless for developers to document their work.

  4. Video Export: Add the ability to export final videos as MP4 files for offline sharing and archival.

  5. Interactive Timeline: Enhance the playback UI with an interactive timeline showing all artifacts, allowing users to jump to specific sections.

  6. Captions & Subtitles: Add automatic caption generation and subtitle support for better accessibility.

  7. Background Music: Allow users to add background music or sound effects to enhance the demo experience.

  8. Project Templates: Create templates for different project types (web apps, APIs, CLI tools) with optimized narration styles.

  9. Analytics Dashboard: Add analytics to track demo views, engagement, and popular sections.

  10. Batch Processing: Support processing multiple projects simultaneously and provide a dashboard to manage all projects.

Built With

Share this project:

Updates