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 680 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 TanStack Query, Zustand stores, Provider Contexts, 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.
• Music Discover: Swipe-based song discovery feed with audio previews, haptic feedback, and personalized recommendation engine.
• Manga: MangaPlus reader with browse/search, favorites, reading progress persistence, and Smart TV spatial-navigation support.
• Remote Control: Mobile-to-desktop video remote control via Socket.IO.
• Smart TV: Android TV platform — spatial navigation, D-pad player, letter grid search, overscan, QR login, music full player, manga reader.
• Mobile Application: Capacitor setup, 21 native plugins, mobile bridge API, and dev workflow.
• Desktop Application: Electron wrapper, system tray, Discord Rich Presence, media keys, and auto-updates.
• Games: Embedded HTML5 game catalogue, asset pipeline, and in-app player.
  • Games Patching: Patching third-party game bundles for offline/embedded use.
  • Games Deployment: Building and shipping game assets.

Contributing

• Contributing Guide: Branching model, commit conventions, and review expectations.

Technology Stack

• Framework: Next.js 16 (React 19, App Router)
• Desktop Wrapper: Electron (Node.js)
• Mobile Wrapper: Capacitor (iOS, Android)
• Language: TypeScript (Strict Mode)
• Styling: Tailwind CSS v4 (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)
• Server State & Caching: TanStack Query (useQuery, useMutation, stale-while-revalidate)
• Client State: Zustand (auth state, music playback state)
• Real-Time Database: Firestore (explore posts, reactions — real-time onSnapshot listeners)
• 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 (native plugins, providers)
├── components/        # Global, reusable UI primitives (Buttons, Inputs, Dialogs)
├── features/          # Domain-isolated modules (auth, profile, watch-party, livestream, explore, friends)
├── hooks/             # Global generic hooks
├── i18n/              # Internationalization (14 locales, 8 namespaces per locale)
├── lib/               # Shared utilities, formatting scripts, and global singletons
├── platforms/         # Platform-specific layers (desktop, mobile, smart-tv)
├── providers/         # Global React Contexts (Socket, Session, Theme)
├── store/             # Zustand global stores (auth)
└── 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 and linting before committing:

pnpm check        # Biome lint/format validation
pnpm type-check   # TypeScript strict mode
pnpm test         # Vitest unit tests

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, 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 v2.17.0 --title "v2.17.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 Next.js + Electron 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, and swipe-based navigation.

Native Plugins (21)

Splash Screen, Status Bar, Clipboard, Haptics, Keep Awake, Screen Orientation, Network Detection, Share, Badge, Keyboard, App Lifecycle, Preferences, Device Info, Push Notifications, Phone Call Notification, CallKit (Incoming Call Kit), Social Login, Volume Buttons, Volumes, Firebase Analytics, Firebase Crashlytics.

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.