# Streamhut

Decentralized video streaming on AT Protocol, powered by serverless bundles.

## Architecture

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                              STREAMHUT                                       │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│  ┌──────────────┐     ┌──────────────┐     ┌──────────────┐                │
│  │   AppView    │────▶│    Turso     │     │   Frontend   │                │
│  │   Bundle     │     │   (SQLite)   │     │   (React)    │                │
│  └──────────────┘     └──────────────┘     └──────────────┘                │
│         │                                          │                        │
│         │ indexes videos                           │ plays videos           │
│         ▼                                          ▼                        │
│  ┌──────────────┐     ┌──────────────┐     ┌──────────────┐                │
│  │  File Cache  │◀───▶│  VOD Bundle  │◀────│   at-run     │                │
│  │ /tmp/vod-cache     │  (playback)  │     │   Runner     │                │
│  └──────────────┘     └──────────────┘     └──────────────┘                │
│                              │                                              │
│                              ▼                                              │
│                       ┌──────────────┐                                      │
│                       │ stream.place │                                      │
│                       │    (HLS)     │                                      │
│                       └──────────────┘                                      │
│                                                                              │
└─────────────────────────────────────────────────────────────────────────────┘
```

## Project Structure

```
├── apps/
│   ├── backend/
│   │   ├── api/          # VOD bundle - HLS proxying, thumbnails, sprites, sharing
│   │   └── appview/      # Video indexer - crawls creators, stores in Turso (WIP)
│   └── frontend/         # Nuxt 4 web app - video player UI
│
├── packages/at-run/
│   ├── runtime/          # Bundle authoring SDK
│   ├── cli/              # Deploy bundles to PDS
│   ├── runner/           # Execute bundles in Deno sandbox
│   └── lexicons/         # AT Protocol record schemas
│
└── DESIGN.md             # Architecture decisions
```

## Quick Start

```bash
# Install dependencies
bun install

# Login to your AT Protocol PDS
npm run login

# Start the runner (dev mode with hot reload)
npm run runner

# In another terminal, start the frontend
npm run web
```

## Common Tasks

### Deploy Bundles

```bash
# Deploy both bundles
npm run deploy:all

# Deploy individually
npm run deploy:vod
npm run deploy:appview
```

### Development

```bash
# Start runner + frontend together
npm run dev

# Or separately:
npm run runner    # Start at-run runner
npm run web       # Start frontend dev server

# Build bundles
npm run bundle

# Type check
npm run typecheck
```

## Environment Variables

Copy `.env.example` to `.env` and configure:

```bash
# Required for AppView
TURSO_URL=libsql://your-db.turso.io
TURSO_AUTH_TOKEN=your-token

# Optional: Connect VOD to AppView
APPVIEW_URL=https://at-run.example.com/bundle/.../streamhut-appview/latest

# Frontend
VITE_RUNNER_URL=https://at-run.example.com
```

## Bundles

### VOD (`atmosphereconf-vod`)

Serves video playback with thumbnails, preview sprites, and social sharing.

| Endpoint | Description |
|----------|-------------|
| `GET /listVideos` | List videos (from AppView or fallback) |
| `GET /getPlaylist` | HLS master playlist |
| `GET /getThumbnail` | Video thumbnail |
| `GET /getSprite` | Preview sprite sheet |
| `GET /getVtt` | Sprite coordinates |
| `GET /shareVideo` | Share page with OG meta tags |
| `GET /shareCreator` | Creator share page with OG meta tags |

**Job:** `syncAndProcessVideos` - runs every 10 minutes

### AppView (`streamhut-appview`) *(Work in Progress)*

Indexes `place.stream.video` records from registered AT Protocol creators.

| Endpoint | Description |
|----------|-------------|
| `POST /init` | Initialize database schema |
| `POST /registerCreator` | Add creator DID to index |
| `POST /unregisterCreator` | Remove creator |
| `GET /listVideos` | Query indexed videos |
| `GET /getStats` | Get index statistics |
| `POST /triggerSync` | Manual sync trigger |

**Job:** `syncAllCreators` - runs every 15 minutes

## Documentation

### Applications
- [VOD Bundle](./apps/backend/api/README.md) - Video playback API with HLS, thumbnails, and sharing
- [Frontend](./apps/frontend/README.md) - Nuxt 4 web application
- [AppView](./apps/backend/appview/README.md) - Video indexer *(work in progress)*

### at-run Framework
- [Overview](./packages/at-run/README.md) - Serverless execution on AT Protocol
- [Runner](./packages/at-run/runner/README.md) - HTTP server for bundle execution
- [Runtime](./packages/at-run/runtime/README.md) - Bundle authoring SDK *(docs coming soon)*
- [CLI](./packages/at-run/cli/README.md) - Deployment tool *(docs coming soon)*

### Other
- [Design Decisions](./DESIGN.md) - Architecture decisions and rationale
- [Hosting Guide](./packages/at-run/runner/HOSTING.md) - Deploy your own runner

## Requirements

- [Bun](https://bun.sh) v1.0+ - Runtime and bundler
- [Deno](https://deno.land) v1.40+ - Sandbox execution
- [Turso](https://turso.tech) account - Database (free tier works)

## License

MIT