Nightwatch

Your personal streaming companion — synchronized playback, watch parties, live streaming, and voice calls.

---

Welcome to the Nightwatch frontend repository. This is a Next.js (App Router) application designed for real-time, synchronized media playback and interactive collaboration.

With over 400+ modules spanning complex real-time domains, this project implements a highly optimized, edge-ready architecture mixing Server-Side Rendering (SSR) with heavy client-side Peer-to-Peer data sharing via WebRTC and Real-Time Messaging.

Documentation Index

Due to the scale of the application, our detailed technical documentation is split into domain-specific guides inside the /docs folder.

Core Architecture

• Setup & Local Development: Instructions for environment variables, dependencies, and local start.
• High-Level Architecture: The Next.js framework, real-time topologies, React state strategies, platform layers, and player compound components.
• API Layer & Communication: Integration with Node.js backend, Agora RTM/RTC, and WebRTC protocols.
• State Management Strategy: Multi-tiered state management using Provider Contexts, Server Actions, and React hooks.
• Testing Methodology: Unit, integration, and E2E testing strategies using Vitest and Playwright.
• UI & Styling Guidelines: Neo-brutalist design rules, Tailwind utility constraints, and CVA component usage.
• Internationalization: 14 languages, 8 namespaces, cookie-based locale, RTL support, and next-intl integration.

Feature Details

• Authentication: Dual-factor HTTP-only cookie sessions and Anti-Bot protection.
• Google OAuth: Google Sign-In integration (web redirect + native iOS/Android).
• Livestream Framework: RTMP ingestion, HLS transmission, and Agora RTM Live Chat loops.
• Livestream Clipping: Record live moments, FFmpeg processing, MinIO storage, public sharing, and Library page.
• User Profile: Zod validation, S3 avatar uploads, and Security mutations.
• Ask AI: Voice-to-voice AI assistant with Nova 2 Sonic, tool calling, and content search.
• Search Engine: Debounced URL-parameter driven queries and infinite scroll facets.
• Watch Content: VOD operations, HLS bitrates, and Redis heartbeat synchronization.
• Watchlist: Optimistic UI, Radix primitives, and TanStack query caching.
• Watch Party: Decentralized peer-to-peer event pipelines over Agora Real-Time Messaging.
• Friends & Voice Calls: Friend system, voice calls, media ducking, and online presence.
• Music: JioSaavn streaming, AudioEngine, synced lyrics, playlists, Redis queue, gapless playback, crossfade, equalizer, sleep timer, and Spotify Connect-like device transfer.
• Remote Control: Mobile-to-desktop video remote control via Socket.IO.
• Offline Downloads: Cross-platform HLS/MP4 downloads, offline library, and quality selection.
• Mobile Application: Capacitor setup, 16 native plugins, mobile bridge API, and dev workflow.

Technology Stack

• Framework: Next.js (React 18+, App Router)
• Desktop Wrapper: Electron (Node.js)
• Mobile Wrapper: Capacitor (iOS, Android)
• Language: TypeScript (Strict Mode)
• Styling: Tailwind CSS (Custom Neo-Brutalist Theme)
• Internationalization: next-intl (14 languages, cookie-based)
• Real-Time Data: Agora RTM, Socket.IO (friends, presence, voice calls)
• Real-Time Media: Agora RTC (WebRTC — watch party, voice calls)
• Quality Assurance: Biome (Linting/Formatting), Vitest (Unit Testing), Playwright (E2E Testing)
• Package Manager: pnpm

Project Structure Overview

The src directory governs all application code, rigidly separated by domain logic:

src/
├── app/               # Next.js App Router (Pages, Layouts, Server forms)
├── capacitor/         # Capacitor mobile-specific modules (downloads, providers)
├── components/        # Global, reusable UI primitives (Buttons, Inputs, Dialogs)
├── features/          # Domain-isolated modules (auth, profile, watch-party, livestream, friends)
├── hooks/             # Global generic hooks
├── lib/               # Shared utilities, formatting scripts, and global singletons
├── providers/         # Global React Contexts (Socket, Session, Theme)
└── types/             # Global TypeScript types (Zod inferred and explicit interfaces)

Quick Start

Ensure you have your environment variables configured (see Setup Guide).

# Install all dependencies
pnpm install

# Launch development environment with Turbopack
pnpm dev

For thorough type-checking, formatting, and tests before committing:

pnpm validate

Desktop Application (macOS, Windows, Linux)

This repository also contains a native OS desktop wrapper using Electron (Node.js). It adds system tray icons, Discord Rich Presence, media key controls, offline downloads, and macOS Dock unread badging.

To develop the desktop app locally:

pnpm desktop:start

Automated Cloud Builds (Releases)

The application uses GitHub Actions to automatically build and publish .dmg (Mac), .msi/.exe (Windows), and .AppImage/.deb (Linux) binaries whenever a new "v*" version tag is created.

You can easily trigger a new desktop build using the official GitHub CLI (gh):

# 1. Update the version in package.json
# 2. Commit the change
# 3. Create and push a new release tag using the gh cli
gh release create v1.32.0 --title "v1.32.0 - Major Update" --notes "Release notes here..."

As soon as the tag is pushed to GitHub, the Build Electron Desktop App action will spin up cloud runners, compile the Rust + Next.js binaries, and attach the installer links automatically to the GitHub Releases page.

Mobile Application (iOS, Android)

The application includes a native mobile wrapper using Capacitor. It wraps the deployed Next.js app in a native WebView with access to device APIs: haptic feedback, status bar theming, CallKit voice calls, background music playback, lock screen media controls, native share sheet, offline downloads, and swipe-based navigation.

Native Plugins (15)

Splash Screen, Status Bar, Clipboard, Haptics, Keep Awake, Screen Orientation, Network Detection, Share, Badge, Keyboard, App Lifecycle, Preferences, Filesystem, Phone Call Notification, CallKit.

Local Development

# Start Next.js dev server
pnpm dev

# Sync Capacitor and open in Xcode (iOS)
pnpm mobile:ios

# Sync Capacitor and open in Android Studio
pnpm mobile:android

For physical device testing, the WebView points to your Mac's LAN IP:

CAPACITOR_DEV=true CAPACITOR_SERVER_URL=http://192.168.x.x:3000 npx cap sync ios

Production Build

# Sync with production URL (https://nightwatch.in)
npx cap sync ios

# Build from Xcode: Product → Scheme → Release → ⌘R

Automated Cloud Builds (Android APK)

The build-android.yml GitHub Action builds a debug APK and attaches it to GitHub Releases alongside the desktop binaries.

# Trigger manually
gh workflow run build-android.yml

Android TV

The app also ships an Android TV build that runs the same WebView-based app with D-pad spatial navigation support. The TV remote's arrow keys move focus between interactive elements, Enter selects, and Back navigates history.

# Build TV APK locally
cd android && ./gradlew assembleRelease -PtvBuild

# Trigger CI build
gh workflow run build-android-tv.yml

The TV build uses a separate application ID (com.nightwatch.in.tv) so it can coexist with the mobile app on the Play Store.

---

For issues regarding the backend services or database administration, see the respective nightwatch-backend or admin-nightwatch repositories.