loopwind 0.24.0 → 0.24.2

package/plans/PLATFORM.md

@@ -0,0 +1,1001 @@
+# Loopwind API Service Design
+
+## Overview
+
+This document outlines the architecture for a cloud-based Loopwind API service that enables:
+- **Publishing templates** via `loopwind publish template-name`
+- **User accounts** at loopwind.dev with authentication
+- **Secure API endpoints** for generating images/videos from published templates
+- **Template marketplace** for sharing and discovering templates
+
+---
+
+## Architecture
+
+### High-Level Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                              loopwind CLI                                │
+│         loopwind publish / loopwind render --remote                      │
+└─────────────────────────────────────────────────────────────────────────┘
+                                    │
+                                    ▼
+┌─────────────────────────────────────────────────────────────────────────┐
+│                           API Gateway (Kong/AWS)                         │
+│              Rate Limiting • Auth Validation • Request Routing           │
+└─────────────────────────────────────────────────────────────────────────┘
+                                    │
+            ┌───────────────────────┼───────────────────────┐
+            ▼                       ▼                       ▼
+┌───────────────────┐   ┌───────────────────┐   ┌───────────────────┐
+│   Auth Service    │   │  Template Service  │   │   Render Service  │
+│                   │   │                    │   │                   │
+│ • User accounts   │   │ • Template CRUD    │   │ • Image rendering │
+│ • API keys        │   │ • Version control  │   │ • Video rendering │
+│ • OAuth           │   │ • Validation       │   │ • Job queue       │
+│ • Sessions        │   │ • Search/browse    │   │ • Webhooks        │
+└───────────────────┘   └───────────────────┘   └───────────────────┘
+            │                       │                       │
+            └───────────────────────┼───────────────────────┘
+                                    ▼
+┌─────────────────────────────────────────────────────────────────────────┐
+│                              Data Layer                                  │
+│    PostgreSQL (users, templates)  •  Redis (cache, sessions, queue)     │
+│    S3/R2 (template files, renders)  •  CDN (output delivery)            │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+### Design Principles
+
+1. **Microservices** - Independent, deployable services for auth, templates, and rendering
+2. **WASM-first rendering** - Serverless-compatible using existing h264-mp4-encoder/Resvg
+3. **Multi-tenancy** - Isolated user data with shared infrastructure
+4. **Queue-based video rendering** - Long-running jobs handled asynchronously
+5. **Edge caching** - Fast delivery of rendered assets via CDN
+
+---
+
+## Authentication System
+
+### User Authentication
+
+```
+POST /api/auth/register
+{
+  "email": "user@example.com",
+  "password": "securepassword",
+  "name": "John Doe"
+}
+→ 201 { "user": {...}, "token": "jwt..." }
+
+POST /api/auth/login
+{
+  "email": "user@example.com",
+  "password": "securepassword"
+}
+→ 200 { "user": {...}, "token": "jwt...", "refreshToken": "..." }
+
+POST /api/auth/refresh
+{
+  "refreshToken": "..."
+}
+→ 200 { "token": "jwt...", "refreshToken": "..." }
+
+POST /api/auth/logout
+→ 204 No Content
+```
+
+### API Keys for Programmatic Access
+
+```
+POST /api/keys
+{
+  "name": "Production App",
+  "scopes": ["render:read", "render:write", "templates:read"]
+}
+→ 201 {
+  "id": "key_abc123",
+  "key": "lw_live_xxxxxxxxxxxxxxxxxxxx",  // Only shown once
+  "name": "Production App",
+  "scopes": [...],
+  "createdAt": "2025-01-05T..."
+}
+
+GET /api/keys
+→ 200 [{ "id": "key_abc123", "name": "...", "lastUsed": "...", ... }]
+
+DELETE /api/keys/:id
+→ 204 No Content
+```
+
+### CLI Authentication Flow
+
+```bash
+# Login via browser (OAuth-style device flow)
+$ loopwind login
+Opening browser for authentication...
+Waiting for confirmation...
+✓ Logged in as user@example.com
+
+# Token stored in ~/.loopwind/credentials
+{
+  "token": "jwt...",
+  "refreshToken": "...",
+  "email": "user@example.com",
+  "expiresAt": "2025-01-06T..."
+}
+
+# Or use API key directly
+$ export LOOPWIND_API_KEY=lw_live_xxxxxxxxxxxxxxxxxxxx
+$ loopwind publish my-template
+```
+
+---
+
+## Template Publishing
+
+### Publish Command
+
+```bash
+loopwind publish [template-name] [options]
+
+Options:
+  --version <version>      Semantic version (default: auto-increment)
+  --description <text>     Template description
+  --private               Make template private (default: public)
+  --tags <tags>           Comma-separated tags
+  --dry-run              Validate without publishing
+```
+
+### Publishing Flow
+
+```
+┌─────────────┐    ┌──────────────┐    ┌────────────────┐    ┌─────────────┐
+│   Validate  │ → │   Package    │ → │   Upload       │ → │   Publish   │
+│   Template  │    │   Files      │    │   to Storage   │    │   Metadata  │
+└─────────────┘    └──────────────┘    └────────────────┘    └─────────────┘
+     │                   │                    │                     │
+     ▼                   ▼                    ▼                     ▼
+ Check meta.ts      Bundle template     POST files to S3     Update registry
+ Validate props     Include assets      Get file URLs        Set version
+ Check deps         Compress            Store checksums      Index for search
+```
+
+### Publish API Endpoints
+
+```
+POST /api/templates/publish
+Authorization: Bearer <token>
+Content-Type: multipart/form-data
+
+{
+  "name": "og-card",                    // Required
+  "version": "1.0.0",                   // Semver
+  "description": "Dynamic OG images",   // Optional
+  "private": false,                     // Default: false
+  "tags": ["og", "social", "image"],   // Optional
+  "files": [                            // Multipart files
+    { "path": "template.tsx", "content": "..." },
+    { "path": "assets/logo.png", "content": "..." }
+  ],
+  "meta": {                             // Extracted from template
+    "type": "image",
+    "size": { "width": 1200, "height": 630 },
+    "props": { "title": "string", "subtitle": "string?" }
+  }
+}
+
+→ 201 {
+  "id": "tpl_abc123",
+  "name": "og-card",
+  "version": "1.0.0",
+  "author": "username",
+  "url": "https://loopwind.dev/username/og-card",
+  "publishedAt": "2025-01-05T..."
+}
+```
+
+### Template Metadata Schema
+
+```typescript
+interface PublishedTemplate {
+  id: string;                    // tpl_abc123
+  name: string;                  // og-card
+  slug: string;                  // username/og-card
+  version: string;               // 1.0.0
+  description: string;
+
+  author: {
+    id: string;
+    username: string;
+    avatar?: string;
+  };
+
+  meta: {
+    type: "image" | "video";
+    size: { width: number; height: number };
+    video?: { fps: number; duration: number };
+    props: Record<string, string>;
+  };
+
+  files: {
+    path: string;
+    url: string;                 // CDN URL
+    checksum: string;
+  }[];
+
+  stats: {
+    downloads: number;
+    renders: number;
+    stars: number;
+  };
+
+  private: boolean;
+  tags: string[];
+
+  createdAt: string;
+  updatedAt: string;
+  publishedAt: string;
+}
+```
+
+---
+
+## Rendering API
+
+### Synchronous Rendering (Images)
+
+For quick image renders (<5 seconds):
+
+```
+POST /api/render
+Authorization: Bearer <token>
+Content-Type: application/json
+
+{
+  "template": "username/og-card",       // Template slug or ID
+  "version": "latest",                  // Optional, default: latest
+  "props": {
+    "title": "Hello World",
+    "subtitle": "My awesome post"
+  },
+  "format": "png",                      // png, jpg, webp, svg
+  "scale": 2                            // Optional, for retina (default: 1)
+}
+
+→ 200 (binary image data)
+Content-Type: image/png
+X-Render-Duration: 234ms
+X-Render-Id: rnd_xyz789
+```
+
+### Asynchronous Rendering (Videos)
+
+For longer video renders:
+
+```
+POST /api/render/async
+Authorization: Bearer <token>
+Content-Type: application/json
+
+{
+  "template": "username/promo-video",
+  "props": {
+    "title": "Product Launch",
+    "logoUrl": "https://example.com/logo.png"
+  },
+  "format": "mp4",                      // mp4, gif
+  "webhook": "https://myapp.com/hooks/render-complete"  // Optional
+}
+
+→ 202 {
+  "jobId": "job_abc123",
+  "status": "queued",
+  "estimatedDuration": 15000,           // ms
+  "statusUrl": "/api/render/job_abc123",
+  "createdAt": "2025-01-05T..."
+}
+```
+
+### Job Status Polling
+
+```
+GET /api/render/:jobId
+Authorization: Bearer <token>
+
+→ 200 {
+  "jobId": "job_abc123",
+  "status": "processing",               // queued, processing, completed, failed
+  "progress": 0.45,                     // 0-1 for video
+  "currentFrame": 45,
+  "totalFrames": 100,
+  "createdAt": "2025-01-05T...",
+  "startedAt": "2025-01-05T..."
+}
+
+// When completed:
+→ 200 {
+  "jobId": "job_abc123",
+  "status": "completed",
+  "progress": 1,
+  "outputUrl": "https://cdn.loopwind.dev/renders/job_abc123.mp4",
+  "expiresAt": "2025-01-06T...",        // URL expires in 24h
+  "duration": 12500,                    // Render time in ms
+  "completedAt": "2025-01-05T..."
+}
+```
+
+### Webhook Payload
+
+```
+POST https://myapp.com/hooks/render-complete
+Content-Type: application/json
+X-Loopwind-Signature: sha256=...
+
+{
+  "event": "render.completed",
+  "jobId": "job_abc123",
+  "status": "completed",
+  "outputUrl": "https://cdn.loopwind.dev/renders/job_abc123.mp4",
+  "template": "username/promo-video",
+  "format": "mp4",
+  "duration": 12500,
+  "timestamp": "2025-01-05T..."
+}
+```
+
+### CLI Remote Rendering
+
+```bash
+# Render using cloud API (fast, no local compute)
+$ loopwind render my-template --remote --props '{"title": "Hello"}'
+✓ Rendered in 234ms
+  Output: https://cdn.loopwind.dev/renders/rnd_xyz789.png
+
+# For videos (async)
+$ loopwind render promo-video --remote --format mp4 --props '{"title": "Launch"}'
+⠋ Rendering video... 45% (45/100 frames)
+✓ Rendered in 12.5s
+  Output: https://cdn.loopwind.dev/renders/job_abc123.mp4
+```
+
+---
+
+## Template Marketplace
+
+### Discovery Endpoints
+
+```
+GET /api/templates
+  ?q=<search>           Search query
+  &type=image|video     Filter by type
+  &tags=og,social       Filter by tags
+  &author=username      Filter by author
+  &sort=popular|recent|downloads
+  &page=1&limit=20
+
+→ 200 {
+  "templates": [...],
+  "total": 156,
+  "page": 1,
+  "pages": 8
+}
+
+GET /api/templates/:slug
+→ 200 { ...PublishedTemplate }
+
+GET /api/templates/:slug/versions
+→ 200 [
+  { "version": "1.0.0", "publishedAt": "...", "downloads": 50 },
+  { "version": "0.9.0", "publishedAt": "...", "downloads": 120 }
+]
+```
+
+### User Profile & Templates
+
+```
+GET /api/users/:username
+→ 200 {
+  "username": "johndoe",
+  "name": "John Doe",
+  "avatar": "https://...",
+  "bio": "Designer & developer",
+  "templates": [...],
+  "stats": { "templates": 12, "totalDownloads": 5000 }
+}
+
+GET /api/me/templates
+Authorization: Bearer <token>
+→ 200 [...] // All user's templates including private
+```
+
+---
+
+## Pricing & Rate Limits
+
+### Free Tier
+- 100 image renders/month
+- 10 video renders/month
+- 5 published templates
+- Public templates only
+- Rate limit: 10 req/min
+
+### Pro Tier ($19/month)
+- 5,000 image renders/month
+- 500 video renders/month
+- Unlimited published templates
+- Private templates
+- Priority rendering
+- Rate limit: 100 req/min
+- Webhook support
+
+### Business Tier ($99/month)
+- 50,000 image renders/month
+- 5,000 video renders/month
+- Team accounts
+- Custom domains
+- SLA guarantee
+- Rate limit: 500 req/min
+- API analytics
+
+### Rate Limit Headers
+
+```
+X-RateLimit-Limit: 100
+X-RateLimit-Remaining: 95
+X-RateLimit-Reset: 1704499200
+```
+
+---
+
+## Infrastructure
+
+### Recommended Stack (100% Cloudflare)
+
+| Component | Technology | Why |
+|-----------|------------|-----|
+| API Gateway | Cloudflare Workers | Rate limiting, auth, routing - all at edge |
+| Auth | Workers + D1 | JWT validation, session management |
+| Database | D1 (SQLite) / Turso | Users, templates, jobs - edge-native |
+| Cache | Workers KV | Sessions, rate limits, template cache |
+| Queue | Durable Objects | Video job orchestration |
+| Storage | R2 | Templates, rendered outputs |
+| CDN | Cloudflare CDN | Automatic, integrated with R2 |
+| Image Rendering | Workers (WASM) | Satori + Resvg, up to 5min CPU |
+| Video Rendering | Containers | FFmpeg, unlimited duration, GPU support |
+| Monitoring | Workers Analytics + Sentry | Built-in metrics + error tracking |
+
+### Deployment Architecture
+
+```
+                         ┌─────────────────────────┐
+                         │    Cloudflare CDN       │
+                         │   (R2 public buckets)   │
+                         └───────────┬─────────────┘
+                                     │
+┌────────────────────────────────────┼────────────────────────────────────┐
+│                                    │                                    │
+│  ┌─────────────────────────────────────────────────────────────────┐   │
+│  │                     Cloudflare Workers                           │   │
+│  │                                                                  │   │
+│  │  ┌──────────────┐  ┌──────────────┐  ┌───────────────────────┐  │   │
+│  │  │  API Worker  │  │   Template   │  │   Image Render Worker │  │   │
+│  │  │              │  │    Worker    │  │                       │  │   │
+│  │  │ • Auth/JWT   │  │ • Publish    │  │ • Satori (JSX→SVG)    │  │   │
+│  │  │ • Rate limit │  │ • Validate   │  │ • Resvg (SVG→PNG)     │  │   │
+│  │  │ • Routing    │  │ • List/Get   │  │ • Up to 5min CPU      │  │   │
+│  │  └──────────────┘  └──────────────┘  └───────────────────────┘  │   │
+│  │                                                                  │   │
+│  └─────────────────────────────────────────────────────────────────┘   │
+│                                    │                                    │
+│                                    │ getContainer(env.RENDERER, jobId)  │
+│                                    ▼                                    │
+│  ┌─────────────────────────────────────────────────────────────────┐   │
+│  │                   Cloudflare Containers                          │   │
+│  │                                                                  │   │
+│  │   ┌─────────────┐   ┌─────────────┐   ┌─────────────┐           │   │
+│  │   │  job_abc    │   │  job_def    │   │  job_ghi    │   ...     │   │
+│  │   │  Container  │   │  Container  │   │  Container  │           │   │
+│  │   │             │   │             │   │             │           │   │
+│  │   │ • FFmpeg    │   │ • FFmpeg    │   │ • FFmpeg    │           │   │
+│  │   │ • Node.js   │   │ • Node.js   │   │ • Node.js   │           │   │
+│  │   │ • Loopwind  │   │ • Loopwind  │   │ • Loopwind  │           │   │
+│  │   └──────┬──────┘   └──────┬──────┘   └──────┬──────┘           │   │
+│  │          │                 │                 │                   │   │
+│  │          └─────────────────┼─────────────────┘                   │   │
+│  │                            ▼                                     │   │
+│  │              Durable Object (Job Orchestrator)                   │   │
+│  │              • Track progress per job                            │   │
+│  │              • Manage container lifecycle                        │   │
+│  │              • Handle webhooks                                   │   │
+│  │                                                                  │   │
+│  └─────────────────────────────────────────────────────────────────┘   │
+│                                    │                                    │
+│  ┌─────────────────────────────────────────────────────────────────┐   │
+│  │                        Data Layer                                │   │
+│  │                                                                  │   │
+│  │   D1 (SQLite)          KV                    R2                  │   │
+│  │   • Users              • Sessions            • Templates         │   │
+│  │   • Templates          • Rate limits         • Rendered videos   │   │
+│  │   • Jobs               • Template cache      • Assets            │   │
+│  │   • Usage              • Font cache                              │   │
+│  │                                                                  │   │
+│  └─────────────────────────────────────────────────────────────────┘   │
+│                                                                        │
+└────────────────────────────────────────────────────────────────────────┘
+```
+
+### Cloudflare Containers for Video Rendering
+
+[Cloudflare Containers](https://blog.cloudflare.com/cloudflare-containers-coming-2025/) (launched June 2025) enable **full video rendering on Cloudflare**:
+
+#### Key Features
+- **Docker containers** - Run FFmpeg, Node.js, any runtime
+- **No time limits** - Long-running video encodes supported
+- **On-demand scaling** - Containers boot per job, sleep when idle
+- **GPU support** - Hardware-accelerated encoding available
+- **Global deployment** - Containers run near users automatically
+- **Pay per use** - Only charged for active container time
+
+#### Container Architecture
+
+Each video job gets its own container instance:
+
+```typescript
+// Worker routes video jobs to containers
+import { getContainer } from "cloudflare:container";
+
+export default {
+  async fetch(request: Request, env: Env) {
+    const { jobId, template, props, format } = await request.json();
+
+    // Each unique jobId = separate container instance
+    // Containers auto-scale horizontally
+    const container = await getContainer(env.VIDEO_RENDERER, jobId);
+
+    return container.fetch("/render", {
+      method: "POST",
+      body: JSON.stringify({ template, props, format })
+    });
+  }
+}
+```
+
+#### Container Dockerfile
+
+```dockerfile
+FROM node:20-slim
+
+# Install FFmpeg for video encoding
+RUN apt-get update && apt-get install -y ffmpeg && rm -rf /var/lib/apt/lists/*
+
+# Install loopwind
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci --production
+COPY . .
+
+# Render server listens for jobs
+EXPOSE 8080
+CMD ["node", "render-server.js"]
+```
+
+#### Scaling Patterns
+
+**Pattern 1: Job-per-Container (Recommended)**
+```
+POST /render/video { jobId: "job_abc" }
+  → Container "job_abc" boots
+  → Renders video
+  → Uploads to R2
+  → Container sleeps after 60s idle
+```
+
+**Pattern 2: Pooled Workers**
+```typescript
+// Distribute across N warm containers using consistent hashing
+const POOL_SIZE = 10;
+const workerId = `renderer-${hash(jobId) % POOL_SIZE}`;
+const container = await getContainer(env.VIDEO_RENDERER, workerId);
+```
+
+#### Durable Object Orchestration
+
+```typescript
+// Durable Object manages container lifecycle and job state
+export class VideoJobOrchestrator extends DurableObject {
+  async startJob(jobId: string, params: RenderParams) {
+    // Store job state
+    await this.ctx.storage.put(`job:${jobId}`, {
+      status: "processing",
+      progress: 0,
+      startedAt: Date.now()
+    });
+
+    // Get or create container for this job
+    const container = await getContainer(this.env.VIDEO_RENDERER, jobId);
+
+    // Start render (non-blocking)
+    container.fetch("/render", {
+      method: "POST",
+      body: JSON.stringify(params)
+    });
+
+    return { jobId, status: "processing" };
+  }
+
+  async updateProgress(jobId: string, progress: number) {
+    const job = await this.ctx.storage.get(`job:${jobId}`);
+    job.progress = progress;
+    await this.ctx.storage.put(`job:${jobId}`, job);
+
+    // Notify via WebSocket if client connected
+    this.broadcast({ type: "progress", jobId, progress });
+  }
+
+  async completeJob(jobId: string, outputUrl: string) {
+    await this.ctx.storage.put(`job:${jobId}`, {
+      status: "completed",
+      progress: 1,
+      outputUrl,
+      completedAt: Date.now()
+    });
+
+    // Fire webhook if configured
+    await this.fireWebhook(jobId, outputUrl);
+  }
+}
+```
+
+### Workers for Image Rendering
+
+Cloudflare Workers handle all image rendering with [up to 5 minutes CPU time](https://developers.cloudflare.com/changelog/2025-03-25-higher-cpu-limits/):
+
+```toml
+# wrangler.toml
+name = "loopwind-api"
+main = "src/worker.ts"
+compatibility_date = "2025-01-01"
+
+[limits]
+cpu_ms = 300000  # 5 minutes - enough for complex images
+
+[[d1_databases]]
+binding = "DB"
+database_name = "loopwind"
+
+[[r2_buckets]]
+binding = "STORAGE"
+bucket_name = "loopwind-assets"
+
+[[kv_namespaces]]
+binding = "CACHE"
+id = "xxx"
+```
+
+### Rendering Decision Flow
+
+```
+                    ┌─────────────────┐
+                    │ Render Request  │
+                    └────────┬────────┘
+                             │
+                             ▼
+                    ┌─────────────────┐
+                    │  Image or Video?│
+                    └────────┬────────┘
+                             │
+              ┌──────────────┴──────────────┐
+              │                             │
+              ▼                             ▼
+     ┌────────────────┐           ┌────────────────┐
+     │     IMAGE      │           │     VIDEO      │
+     └────────┬───────┘           └────────┬───────┘
+              │                             │
+              ▼                             ▼
+     ┌────────────────┐           ┌────────────────┐
+     │    Worker      │           │   Container    │
+     │                │           │                │
+     │ • Satori→SVG   │           │ • FFmpeg       │
+     │ • Resvg→PNG    │           │ • Full Node.js │
+     │ • <5min CPU    │           │ • No time limit│
+     │ • 128MB RAM    │           │ • Multi-core   │
+     └────────┬───────┘           └────────┬───────┘
+              │                             │
+              ▼                             ▼
+     ┌────────────────┐           ┌────────────────┐
+     │ Sync Response  │           │ Async Job ID   │
+     │ (binary data)  │           │ (poll/webhook) │
+     └────────────────┘           └────────────────┘
+```
+
+### Cost Optimization
+
+| Workload | Platform | Estimated Cost |
+|----------|----------|----------------|
+| Image render | Worker | ~$0.0001 per render |
+| Short video (<30s) | Worker (WASM) | ~$0.001 per render |
+| Long video (1-5min) | Container | ~$0.01-0.05 per render |
+| GPU video | Container + GPU | ~$0.10-0.50 per render |
+
+**Tips:**
+- Use Workers for images (cheapest, fastest)
+- Use WASM encoding in Workers for short videos when possible
+- Containers auto-sleep after idle timeout (default 60s)
+- Cache fonts/assets in KV to reduce cold start time
+
+---
+
+## CLI Implementation
+
+### New Commands
+
+```bash
+# Authentication
+loopwind login              # Browser-based OAuth flow
+loopwind logout             # Clear credentials
+loopwind whoami             # Show current user
+
+# Publishing
+loopwind publish [template] # Publish template to registry
+  --version <ver>           # Semantic version
+  --private                 # Private template
+  --dry-run                 # Validate only
+
+# Remote rendering
+loopwind render <template>  # Render (local by default)
+  --remote                  # Use cloud API
+  --props <json>            # Template props
+  --format <fmt>            # Output format
+  --out <path>              # Save locally
+
+# Account management
+loopwind keys list          # List API keys
+loopwind keys create        # Create new API key
+loopwind keys revoke <id>   # Revoke API key
+```
+
+### Credential Storage
+
+```
+~/.loopwind/
+├── credentials.json        # Auth tokens
+├── config.json            # User preferences
+└── keys/                  # Cached API keys
+```
+
+```json
+// ~/.loopwind/credentials.json
+{
+  "token": "eyJhbG...",
+  "refreshToken": "eyJhbG...",
+  "expiresAt": "2025-01-06T12:00:00Z",
+  "user": {
+    "id": "usr_abc123",
+    "email": "user@example.com",
+    "username": "johndoe"
+  }
+}
+```
+
+---
+
+## Security Considerations
+
+### API Security
+
+1. **Authentication**
+   - JWT tokens with short expiry (15min)
+   - Refresh tokens stored securely (HttpOnly cookies on web)
+   - API keys hashed with bcrypt before storage
+
+2. **Authorization**
+   - Scoped API keys (render:read, templates:write, etc.)
+   - Private template access control
+   - Rate limiting per API key/user
+
+3. **Input Validation**
+   - Template code sandboxed (no network access, no fs access)
+   - Props validated against schema
+   - File size limits (10MB per template)
+
+4. **Output Security**
+   - Signed URLs with expiration
+   - CORS configuration
+   - Content-Security-Policy headers
+
+### Template Sandboxing
+
+Templates run in isolated environment:
+
+```typescript
+// Allowed in templates
+- React JSX rendering
+- Math operations
+- String manipulation
+- Built-in helpers (tw, qr, image, path)
+
+// NOT allowed
+- fetch() / network requests
+- fs / file system access
+- eval() / dynamic code
+- process / environment access
+- require() / import() of external modules
+```
+
+---
+
+## Database Schema
+
+```sql
+-- Users
+CREATE TABLE users (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  email VARCHAR(255) UNIQUE NOT NULL,
+  username VARCHAR(50) UNIQUE NOT NULL,
+  password_hash VARCHAR(255),
+  name VARCHAR(255),
+  avatar_url VARCHAR(500),
+  plan VARCHAR(20) DEFAULT 'free',
+  created_at TIMESTAMP DEFAULT NOW(),
+  updated_at TIMESTAMP DEFAULT NOW()
+);
+
+-- API Keys
+CREATE TABLE api_keys (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  user_id UUID REFERENCES users(id) ON DELETE CASCADE,
+  name VARCHAR(100) NOT NULL,
+  key_hash VARCHAR(255) NOT NULL,
+  key_prefix VARCHAR(12) NOT NULL,  -- lw_live_xxxx for display
+  scopes TEXT[] DEFAULT '{}',
+  last_used_at TIMESTAMP,
+  created_at TIMESTAMP DEFAULT NOW()
+);
+
+-- Templates
+CREATE TABLE templates (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  user_id UUID REFERENCES users(id) ON DELETE CASCADE,
+  name VARCHAR(100) NOT NULL,
+  slug VARCHAR(150) NOT NULL,  -- username/template-name
+  description TEXT,
+  type VARCHAR(20) NOT NULL,  -- image, video
+  meta JSONB NOT NULL,
+  private BOOLEAN DEFAULT FALSE,
+  tags TEXT[] DEFAULT '{}',
+  downloads INTEGER DEFAULT 0,
+  renders INTEGER DEFAULT 0,
+  created_at TIMESTAMP DEFAULT NOW(),
+  updated_at TIMESTAMP DEFAULT NOW(),
+  UNIQUE(user_id, name)
+);
+
+-- Template Versions
+CREATE TABLE template_versions (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  template_id UUID REFERENCES templates(id) ON DELETE CASCADE,
+  version VARCHAR(20) NOT NULL,
+  files JSONB NOT NULL,  -- [{path, url, checksum}]
+  published_at TIMESTAMP DEFAULT NOW(),
+  UNIQUE(template_id, version)
+);
+
+-- Render Jobs
+CREATE TABLE render_jobs (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  user_id UUID REFERENCES users(id),
+  template_id UUID REFERENCES templates(id),
+  status VARCHAR(20) DEFAULT 'queued',
+  props JSONB,
+  format VARCHAR(10),
+  output_url VARCHAR(500),
+  error TEXT,
+  progress FLOAT DEFAULT 0,
+  started_at TIMESTAMP,
+  completed_at TIMESTAMP,
+  created_at TIMESTAMP DEFAULT NOW()
+);
+
+-- Usage tracking
+CREATE TABLE usage (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  user_id UUID REFERENCES users(id),
+  type VARCHAR(20) NOT NULL,  -- image_render, video_render, publish
+  count INTEGER DEFAULT 1,
+  month DATE NOT NULL,  -- First of month
+  UNIQUE(user_id, type, month)
+);
+```
+
+---
+
+## Implementation Phases
+
+### Phase 1: Authentication & Publishing
+- User registration/login
+- API key management
+- `loopwind login/logout/whoami` commands
+- `loopwind publish` command
+- Template storage in R2
+- Basic registry API
+
+### Phase 2: Image Rendering API
+- Synchronous image rendering endpoint
+- `loopwind render --remote` for images
+- Rate limiting
+- Usage tracking
+
+### Phase 3: Video Rendering & Queue
+- Async video rendering with job queue
+- Webhook notifications
+- Progress tracking
+- `loopwind render --remote` for videos
+
+### Phase 4: Marketplace & Discovery
+- Template search and browse
+- User profiles
+- Download/star tracking
+- loopwind.dev website updates
+
+### Phase 5: Billing & Pro Features
+- Stripe integration
+- Usage-based billing
+- Private templates
+- Team accounts
+
+---
+
+## API Client SDK
+
+For easy integration, provide official SDKs:
+
+```typescript
+// JavaScript/TypeScript
+import { Loopwind } from '@loopwind/sdk';
+
+const lw = new Loopwind({ apiKey: 'lw_live_xxx' });
+
+// Render image
+const image = await lw.render('username/og-card', {
+  props: { title: 'Hello World' },
+  format: 'png'
+});
+
+// Render video (async)
+const job = await lw.renderVideo('username/promo', {
+  props: { title: 'Launch' },
+  format: 'mp4'
+});
+
+// Poll for completion
+const result = await job.wait();
+console.log(result.outputUrl);
+
+// Or use webhook
+await lw.renderVideo('username/promo', {
+  props: { title: 'Launch' },
+  webhook: 'https://myapp.com/hooks/render'
+});
+```
+
+---
+
+## References
+
+### Cloudflare Platform
+- [Cloudflare Containers Announcement](https://blog.cloudflare.com/cloudflare-containers-coming-2025/) - Containers coming June 2025
+- [Cloudflare Containers Architecture](https://developers.cloudflare.com/containers/architecture/) - How containers work with Workers/DOs
+- [Container Platform with GPUs](https://blog.cloudflare.com/container-platform-preview/) - GPU support preview
+- [Workers 5-Minute CPU Limit](https://developers.cloudflare.com/changelog/2025-03-25-higher-cpu-limits/) - Extended CPU time for Workers
+- [Workers Limits](https://developers.cloudflare.com/workers/platform/limits/) - Full limits documentation
+- [Durable Objects](https://developers.cloudflare.com/durable-objects/) - Stateful coordination
+
+### Architecture & Design
+- [Eden AI - Video Generation APIs](https://www.edenai.co/post/best-ai-video-generation-apis-in-2025)
+- [SaaS Architecture Patterns](https://www.mindinventory.com/blog/software-architecture-patterns/)
+- [API Architecture Best Practices](https://www.catchpoint.com/api-monitoring-tools/api-architecture)
+- [Vercel Marketplace API](https://vercel.com/docs/integrations/create-integration/marketplace-api)
+- [Sharetribe Marketplace API](https://www.sharetribe.com/docs/concepts/api-sdk/marketplace-api-integration-api/)
+- [SaaS Architecture Guide 2025](https://www.decipherzone.com/blog-detail/saas-architecture-cto-guide)