# beStream Technical Documentation

## Table of Contents

1. [Overview](#overview)
2. [Architecture](#architecture)
3. [Project Structure](#project-structure)
4. [Frontend Application](#frontend-application)
5. [Backend Server](#backend-server)
6. [Platform Support](#platform-support)
7. [API Reference](#api-reference)
8. [State Management](#state-management)
9. [Services](#services)
10. [Build System](#build-system)
11. [Configuration](#configuration)
12. [Troubleshooting](#troubleshooting)

---

## Overview

beStream is a cross-platform movie and TV show streaming application with a Netflix-style UI. It supports:

- **Desktop**: Windows, macOS, Linux (via Electron)
- **Mobile**: Android (via Capacitor with embedded Node.js)
- **Web**: Browser-based development mode

The application streams content via WebTorrent, providing real-time torrent-to-stream functionality with optional HLS transcoding for broader device compatibility.

### Key Features

- 🎬 Stream movies and TV shows in real-time
- 📺 Netflix-style responsive UI
- 🔍 Search and browse content from YTS and EZTV
- 📱 Cross-platform support (Desktop & Android)
- ⬇️ Download management with progress tracking
- 📚 Watch history and watchlist
- 🎯 Quality selection (480p, 720p, 1080p, 2160p)
- 🔄 Integration with Radarr/Sonarr/Lidarr

---

## Architecture

### High-Level Architecture

```
┌─────────────────────────────────────────────────────────────────┐
│                        Frontend (React)                          │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────────────┐ │
│  │  Pages   │  │Components│  │  Stores  │  │    Services      │ │
│  │          │  │          │  │ (Zustand)│  │ (API, Streaming) │ │
│  └──────────┘  └──────────┘  └──────────┘  └──────────────────┘ │
└──────────────────────────────┬──────────────────────────────────┘
                               │ HTTP/WebSocket
                               ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Backend Server (Node.js)                      │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────┐   │
│  │   Express    │  │  WebTorrent  │  │   FFmpeg Transcoder  │   │
│  │   Routes     │  │   Manager    │  │   (HLS streaming)    │   │
│  └──────────────┘  └──────────────┘  └──────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘
```

### Platform-Specific Architecture

#### Electron (Desktop)

```
┌─────────────────────────────────────────┐
│              Electron App               │
│  ┌─────────────────────────────────┐    │
│  │       Main Process              │    │
│  │  - Window management            │    │
│  │  - IPC handling                 │    │
│  │  - Server process spawn         │    │
│  └─────────────────────────────────┘    │
│  ┌─────────────────────────────────┐    │
│  │     Renderer Process            │    │
│  │  - React Frontend               │    │
│  │  - Preload scripts              │    │
│  └─────────────────────────────────┘    │
│  ┌─────────────────────────────────┐    │
│  │     Server Process (fork)       │    │
│  │  - Express + WebTorrent         │    │
│  └─────────────────────────────────┘    │
└─────────────────────────────────────────┘
```

#### Capacitor (Android)

```
┌─────────────────────────────────────────┐
│           Android Application           │
│  ┌─────────────────────────────────┐    │
│  │         WebView                 │    │
│  │  - React Frontend               │    │
│  │  - Capacitor Bridge             │    │
│  └─────────────────────────────────┘    │
│  ┌─────────────────────────────────┐    │
│  │   capacitor-nodejs plugin       │    │
│  │  - Embedded Node.js runtime     │    │
│  │  - Express + WebTorrent bundle  │    │
│  └─────────────────────────────────┘    │
└─────────────────────────────────────────┘
```

---

## Project Structure

```
beStream/
├── src/                        # Frontend React application
│   ├── components/             # Reusable UI components
│   │   ├── calendar/           # Calendar-related components
│   │   ├── integration/        # *arr integration components
│   │   ├── layout/             # Layout components (Header, Sidebar)
│   │   ├── movie/              # Movie display components
│   │   ├── music/              # Music-related components
│   │   ├── player/             # Video player components
│   │   ├── tv/                 # TV show components
│   │   └── ui/                 # Generic UI components (Button, Modal, etc.)
│   ├── pages/                  # Page components (routes)
│   ├── hooks/                  # Custom React hooks
│   ├── services/               # API and business logic services
│   │   ├── api/                # External API clients (YTS, EZTV, TMDB)
│   │   ├── integration/        # *arr service integrations
│   │   ├── server/             # Server management
│   │   ├── storage/            # Local storage services
│   │   ├── streaming/          # Streaming service client
│   │   ├── subtitles/          # Subtitle handling
│   │   └── torrent/            # Torrent utilities
│   ├── stores/                 # Zustand state stores
│   ├── types/                  # TypeScript type definitions
│   ├── utils/                  # Utility functions
│   └── constants/              # Application constants
├── server/                     # Backend Node.js server
│   ├── src/
│   │   ├── routes/             # Express route handlers
│   │   ├── services/           # Backend services (torrent, transcoder)
│   │   ├── utils/              # Server utilities
│   │   └── polyfills/          # Platform polyfills
│   ├── bundle.js               # esbuild bundler script
│   └── package.json            # Server dependencies
├── electron/                   # Electron main process
│   ├── main.ts                 # Main process entry
│   ├── preload.ts              # Preload script
│   └── tsconfig.json           # Electron TypeScript config
├── android/                    # Android native project (Capacitor)
├── scripts/                    # Build and utility scripts
├── docs/                       # Documentation
├── public/                     # Static assets
├── dist/                       # Built frontend
├── dist-electron/              # Built Electron files
└── release/                    # Release builds
```

---

## Frontend Application

### Technology Stack

- **React 18** - UI framework
- **TypeScript** - Type safety
- **Vite** - Build tool and dev server
- **Tailwind CSS** - Utility-first styling
- **Zustand** - State management
- **React Router** - Client-side routing
- **Framer Motion** - Animations
- **Axios** - HTTP client
- **HLS.js** - HLS video playback

### Pages

| Page | Route | Description |
|------|-------|-------------|
| Home | `/` | Hero section with trending content |
| Browse | `/browse`, `/browse/:genre` | Browse movies by genre |
| Search | `/search` | Search movies and TV shows |
| Movie Details | `/movie/:id` | Movie information and stream options |
| Player | `/player/:id` | Video player with streaming |
| TV Shows | `/tv` | Browse TV shows |
| TV Show Details | `/tv/:id` | Season/episode browser |
| TV Player | `/tv/:showId/:seasonId/:episodeId` | TV episode player |
| Watchlist | `/watchlist` | Saved items |
| Downloads | `/downloads` | Download manager |
| History | `/history` | Watch history |
| Queue | `/queue` | Download queue |
| Settings | `/settings` | App configuration |

### Component Architecture

#### Layout Components

- **Layout** - Main app layout with header and sidebar
- **Header** - Top navigation with search
- **Sidebar** - Navigation menu

#### Movie Components

- **Hero** - Featured content carousel
- **MovieRow** - Horizontal scrollable movie list
- **MovieCard** - Individual movie thumbnail
- **MovieGrid** - Grid layout for movies

#### Player Components

- **StreamingPlayer** - Main video player wrapper
- **VideoPlayer** - Core video element with controls
- **NextEpisodeOverlay** - Auto-play next episode UI

### Hooks

| Hook | Purpose |
|------|---------|
| `useMovies` | Fetch and cache movie data |
| `useSeries` | Fetch TV show data |
| `useCalendar` | Episode calendar data |
| `useIntegration` | *arr service integration |
| `useAsyncData` | Generic async data fetching |
| `useMusic` | Music service data |

---

## Backend Server

### Technology Stack

- **Express.js** - Web framework
- **WebTorrent** - Torrent client
- **FFmpeg** (optional) - Video transcoding
- **ws** - WebSocket server
- **mime-types** - MIME type detection

### Server Entry Point

The server initializes in `server/src/index.js`:

1. Creates Express app with security headers
2. Sets up CORS for cross-origin requests
3. Registers API routes
4. Creates WebSocket server for real-time updates
5. Binds to `localhost:3001` (or `0.0.0.0:3001` on Android)

### Routes

#### Stream Routes (`/api/stream`)

| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/start` | Start a new streaming session |
| GET | `/:sessionId/status` | Get session status |
| GET | `/:sessionId/video` | Stream video (supports range requests) |
| POST | `/:sessionId/hls` | Start HLS transcoding |
| GET | `/:sessionId/hls/playlist.m3u8` | Get HLS playlist |
| GET | `/:sessionId/hls/:segment` | Get HLS segment |
| DELETE | `/:sessionId` | End streaming session |

#### Proxy Routes (`/api`)

| Endpoint | Target | Purpose |
|----------|--------|---------|
| `/api/eztv/*` | eztvx.to | TV show torrents |
| `/api/yts/*` | yts.mx | Movie torrents |
| `/api/tmdb/*` | themoviedb.org | Movie/TV metadata |

### Services

#### TorrentManager

Manages WebTorrent client and streaming sessions:

```javascript
class TorrentManager {
  // Start a new torrent session
  async startSession(sessionId, torrentHash, movieName, onProgress)
  
  // Create readable stream for video file
  createReadStream(sessionId, options)
  
  // Get session status (progress, speed, peers)
  getSessionStatus(sessionId)
  
  // Clean up session
  destroySession(sessionId)
}
```

Key features:
- Session reuse for duplicate torrents
- Range request support for seeking
- Progress tracking via callbacks
- Platform-aware cache directories

#### Transcoder

Handles FFmpeg-based HLS transcoding (desktop only):

```javascript
class Transcoder {
  // Get video file information
  getVideoInfo(inputPath)
  
  // Start HLS transcoding from file
  startHlsTranscode(sessionId, inputPath, onProgress, quality)
  
  // Start HLS transcoding from stream
  startHlsStreamTranscode(sessionId, inputStream, onProgress, quality)
  
  // Clean up transcoding session
  cleanup(sessionId)
}
```

Note: FFmpeg transcoding is disabled on Android due to binary unavailability.

---

## Platform Support

### Electron (Desktop)

The Electron build provides:
- Native window with frameless design (macOS) or custom frame (Windows/Linux)
- System tray integration
- File system access for downloads
- Embedded server process

#### Main Process (`electron/main.ts`)

- Window creation and management
- Server process lifecycle
- IPC handlers for native features
- Menu and tray setup

#### Preload Script (`electron/preload.ts`)

Exposes safe APIs to renderer:
- `window.electron.openExternal(url)` - Open URLs in browser
- `window.electron.getDownloadsPath()` - Get downloads directory
- `window.electron.showItemInFolder(path)` - Show file in explorer

### Capacitor (Android)

The Android build uses:
- Capacitor WebView for UI
- `capacitor-nodejs` plugin for embedded Node.js
- Bundled server (single `index.js` file)

#### Build Process

1. Build frontend with Vite
2. Bundle server with esbuild
3. Copy bundle to Android assets
4. Sync Capacitor
5. Build APK with Gradle

#### Platform Considerations

- **No FFmpeg**: Transcoding disabled, direct video streaming only
- **No uTP**: WebTorrent uTP disabled (native module incompatible)
- **Cache Directory**: Uses `/data/data/com.bestream.app/files/` instead of `/tmp`
- **Network**: Server binds to `0.0.0.0` for WebView access

---

## API Reference

### External APIs

#### YTS API

Movie data and torrents from YTS.

```typescript
// List movies with filters
ytsApi.listMovies({
  limit: 20,
  page: 1,
  quality: '1080p',
  genre: 'action',
  sort_by: 'rating',
  order_by: 'desc',
  query_term: 'search term'
})

// Get movie details
ytsApi.getMovieDetails({ movie_id: 12345 })

// Get suggestions
ytsApi.getMovieSuggestions(12345)
```

#### EZTV API

TV show torrents from EZTV.

```typescript
// Get torrents for a show (by IMDB ID)
tvDiscoveryApi.getTorrents('tt1234567')

// Search episode torrents
tvDiscoveryApi.searchEpisodeTorrents(showTitle, season, episode, imdbId)
```

#### TMDB API

TV show metadata from The Movie Database.

```typescript
// Get trending shows
tvDiscoveryApi.getTrending()

// Get show details
tvDiscoveryApi.getShowDetails(showId)

// Get season details
tvDiscoveryApi.getSeasonDetails(showId, seasonNumber)
```

### Internal APIs

#### Streaming Service

```typescript
// Start a stream
streamingService.startStream(hash, name, quality)

// Connect to WebSocket updates
streamingService.connect(sessionId)

// Subscribe to progress updates
streamingService.subscribe(sessionId, callback)

// Get video URL
streamingService.getVideoUrl(sessionId)

// Check server health
streamingService.checkHealth()
```

---

## State Management

The app uses Zustand for state management with persistence.

### Stores

#### Settings Store

```typescript
interface SettingsState {
  settings: {
    preferredQuality: '480p' | '720p' | '1080p' | '2160p';
    preferredLanguage: string;
    autoPlay: boolean;
    notifications: boolean;
    downloadPath: string;
    maxConcurrentDownloads: number;
    theme: 'dark' | 'light';
  };
  updateSettings(settings: Partial<AppSettings>): void;
  resetSettings(): void;
}
```

#### History Store

```typescript
interface HistoryState {
  history: HistoryItem[];
  addToHistory(item: HistoryItem): void;
  updateProgress(id: number, progress: number): void;
  getProgress(id: number): HistoryItem | undefined;
  removeFromHistory(id: number): void;
  clearHistory(): void;
}
```

#### Watchlist Store

```typescript
interface WatchlistState {
  watchlist: WatchlistItem[];
  addToWatchlist(item: WatchlistItem): void;
  removeFromWatchlist(id: number): void;
  isInWatchlist(id: number): boolean;
}
```

#### Download Store

```typescript
interface DownloadState {
  downloads: Download[];
  addDownload(download: Download): void;
  updateDownload(id: string, updates: Partial<Download>): void;
  removeDownload(id: string): void;
}
```

#### Integration Store

```typescript
interface IntegrationState {
  radarrUrl: string;
  radarrApiKey: string;
  sonarrUrl: string;
  sonarrApiKey: string;
  lidarrUrl: string;
  lidarrApiKey: string;
  // ... setters
}
```

---

## Services

### API Services (`src/services/api/`)

- **yts.ts** - YTS API client for movies
- **tvDiscovery.ts** - TMDB + EZTV for TV shows
- **radarr.ts** - Radarr integration
- **sonarr.ts** - Sonarr integration
- **lidarr.ts** - Lidarr integration

### Streaming Services (`src/services/streaming/`)

- **streamingService.ts** - Main streaming client
  - HTTP requests to backend
  - WebSocket connection management
  - Session lifecycle

### Server Services (`src/services/server/`)

- **serverManager.ts** - Server lifecycle management
  - Start/stop server (Capacitor)
  - Health checks
  - Automatic restarts

### Storage Services (`src/services/storage/`)

- Local database (Dexie/IndexedDB)
- Download management
- Offline data caching

---

## Build System

### Development

```bash
# Frontend only
npm run dev

# Frontend + Server
npm run dev:all

# Electron development
npm run electron:dev
```

### Production Builds

```bash
# Web build
npm run build

# Electron builds
npm run build:win      # Windows
npm run build:mac      # macOS
npm run build:linux    # Linux

# Android build
npm run build:android:apk      # Debug APK
npm run build:android:release  # Release APK
```

### Build Pipeline (Android)

1. **Frontend Build** (`npm run build`)
   - TypeScript compilation
   - Vite production build
   - Output: `dist/`

2. **Server Install** (`npm run server:install`)
   - Install server dependencies

3. **Server Bundle** (`npm run copy-server-to-android`)
   - Bundle with esbuild
   - Single file output
   - Platform-aware polyfills
   - Output: `dist/nodejs-v3/index.js`

4. **Capacitor Sync** (`npx cap sync android`)
   - Copy web assets
   - Update native project

5. **Gradle Build** (`gradlew assembleDebug`)
   - Compile Android project
   - Output: `android/app/build/outputs/apk/`

---

## Configuration

### Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `VITE_API_URL` | Backend server URL | `http://localhost:3001` |
| `PORT` | Server port | `3001` |
| `NODE_ENV` | Environment mode | `development` |
| `VITE_EZTV_USERNAME` | EZTV authentication | - |
| `VITE_EZTV_PASSWORD` | EZTV authentication | - |

### Capacitor Config (`capacitor.config.ts`)

```typescript
{
  appId: 'com.bestream.app',
  appName: 'beStream',
  webDir: 'dist',
  plugins: {
    CapacitorNodeJS: {
      nodeDir: 'nodejs-v3',
      startMode: 'manual',
    },
  },
  android: {
    allowMixedContent: true,
    cleartext: true,
  },
}
```

### Vite Config (`vite.config.ts`)

- React plugin
- Path aliases (`@/` → `src/`)
- Development proxy for APIs
- Rollup externals for Capacitor

### Tailwind Config (`tailwind.config.js`)

Custom theme with Netflix-inspired colors:
- `netflix-black`: `#141414`
- `netflix-red`: `#E50914`
- Custom spacing and breakpoints

---

## Troubleshooting

### Common Issues

#### Server Not Starting (Android)

**Symptoms**: App shows "Server not running" error

**Solutions**:
1. Check Logcat for Node.js errors
2. Verify `nodejs-v3/index.js` exists in APK
3. Ensure `builtin_modules` placeholder exists
4. Check for native module errors (node-datachannel, uTP)

#### Video Not Playing

**Symptoms**: Black screen or loading forever

**Solutions**:
1. Check server health: `http://localhost:3001/health`
2. Verify torrent has seeders
3. Check browser console for errors
4. Try different quality/torrent

#### CORS Errors

**Symptoms**: Network errors in browser console

**Solutions**:
1. Ensure server CORS is configured
2. Check proxy configuration in Vite
3. Verify API URLs are correct

#### Build Failures (Android)

**Symptoms**: Gradle build errors

**Solutions**:
1. Clean build: `cd android && gradlew clean`
2. Sync Capacitor: `npx cap sync android`
3. Check Java/Gradle versions
4. Verify Android SDK installation

### Debug Tools

#### Logcat (Android)

```bash
# All app logs
adb logcat | grep com.bestream.app

# Node.js logs only
adb logcat | grep -E "(NodeJS|beStream)"
```

#### Server Health Check

```bash
curl http://localhost:3001/health
```

#### WebSocket Testing

```javascript
const ws = new WebSocket('ws://localhost:3001/ws');
ws.onopen = () => ws.send(JSON.stringify({ type: 'subscribe', sessionId: 'test' }));
ws.onmessage = (e) => console.log(JSON.parse(e.data));
```

---

## Contributing

### Code Style

- TypeScript for all new code
- ESLint + Prettier for formatting
- Functional components with hooks
- Named exports preferred

### Testing

- Unit tests for utilities
- Integration tests for services
- E2E tests for critical flows

### Pull Request Process

1. Create feature branch
2. Make changes with tests
3. Update documentation
4. Submit PR with description
5. Pass CI checks
6. Get review approval

---

## License

This project is private and proprietary. See LICENSE file for details.