From 0ca65f264d310c0dbfe244d774ea308fe7d5beb1 Mon Sep 17 00:00:00 2001
From: Jeff Emmett <jeffemmett@gmail.com>
Date: Tue, 17 Feb 2026 12:30:14 -0700
Subject: [PATCH] docs: add MODULE_SPEC.md with permission model and
 capabilities

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 MODULE_SPEC.md | 87 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 87 insertions(+)
 create mode 100644 MODULE_SPEC.md

diff --git a/MODULE_SPEC.md b/MODULE_SPEC.md
new file mode 100644
index 0000000..7d41dc8
--- /dev/null
+++ b/MODULE_SPEC.md
@@ -0,0 +1,87 @@
+# rTube — Video Hosting & Streaming
+
+**Module ID:** `rtube`
+**Domain:** `rtube.online`
+**Version:** 0.1.0
+**Framework:** Next.js 14 / React 18 / HLS.js / AWS S3 / nginx-rtmp
+**Status:** Active
+
+## Purpose
+
+Community video hosting and live streaming platform. Videos stored in Cloudflare R2 (S3-compatible), served with HTTP range requests for seeking. Live streaming via RTMP ingest (nginx-rtmp Docker sidecar). Currently a simple video library — no channels, no auth.
+
+## Data Model
+
+### Storage (S3/R2 — no database)
+
+| Resource | Storage | Format |
+|----------|---------|--------|
+| **Videos** | R2 bucket | .mp4, .mkv, .webm, .mov, .avi, .wmv, .flv, .m4v |
+| **Streams** | RTMP ingest → HLS | Live streams via nginx-rtmp |
+
+- No database — video metadata read from S3 ListObjectsV2
+- No user model, no channels, no comments
+- Future: Prisma/PostgreSQL for metadata, channels, and permissions
+
+## Permission Model
+
+### Space Integration
+
+- **SpaceVisibility:** PUBLIC by default (anyone can watch)
+- **Default role for open spaces:** PARTICIPANT (can upload videos)
+
+### Capabilities
+
+| Capability | Required SpaceRole | AuthLevel | Description |
+|-----------|-------------------|-----------|-------------|
+| `view_videos` | VIEWER | BASIC | Watch videos and streams |
+| `upload_video` | PARTICIPANT | STANDARD | Upload video files to library |
+| `start_stream` | PARTICIPANT | STANDARD | Start RTMP live stream |
+| `moderate_videos` | MODERATOR | STANDARD | Delete/hide others' videos |
+| `configure_channel` | ADMIN | ELEVATED | Manage channel settings, storage |
+
+### Current Auth Implementation
+
+- **None** — all content publicly readable, no upload endpoint yet
+
+## API Endpoints
+
+| Method | Path | Auth Required | Capability | Description |
+|--------|------|---------------|------------|-------------|
+| GET | /api/videos | No | view_videos | List all videos in bucket |
+| GET | /api/v/[...path] | No | view_videos | Stream video with range support |
+
+### RTMP Ingest (Docker sidecar)
+
+- Port 1936 (RTMP) → nginx-rtmp → HLS
+- Archive to R2 on stream end
+- Not exposed via Next.js API
+
+## Canvas Integration
+
+Future shape types for rSpace canvas:
+- **Video player widget**: Embedded HLS player
+- **Stream indicator**: Live stream status with viewer count
+
+## Cross-Module Dependencies
+
+| Module | Integration |
+|--------|------------|
+| **rSpace** | Video player shapes on canvas |
+| **rNotes** | Video notes/annotations |
+| **EncryptID** | Identity for upload permissions (not yet implemented) |
+
+## Local-First / Offline Support
+
+- Video playback works offline if cached by browser/service worker
+- Upload requires connectivity (R2/S3)
+- No CRDT — videos are immutable blobs
+
+## Migration Plan
+
+1. Add EncryptID auth middleware
+2. Add upload endpoint with `hasCapability('upload_video')` check
+3. Add Prisma schema for video metadata (title, description, uploader DID, channel)
+4. Add channel concept scoped to spaces
+5. Import `RTUBE_PERMISSIONS` from SDK
+6. Add `resolveSpaceRole()` for space-scoped video libraries