# 🗂️ Project Structure

NovaStream is built on a hybrid architecture, combining a highly interactive React frontend with a robust Node.js streaming proxy backend.

Below is an overview of the core file structure and components:

```text
NovaStream/
├── server.cjs                 # Core Node.js Express server
│                              # Handles /api/metadata, /api/stream, FFmpeg transmuxing, and file probing
├── package.json               # Project dependencies and npm scripts
├── vite.config.js             # Vite configuration for building the React frontend
├── eslint.config.js           # Linter configuration
├── index.html                 # Entry point for the frontend application
├── Dockerfile                 # Configuration for containerizing the application
├── LICENSE                    # GPL-3.0 Open Source License
├── README.md                  # Project overview, features, and setup guide
│
├── public/                    # Static assets
│
└── src/                       # React Frontend Source Code
    ├── App.jsx                # Main Application component (UI, Player Logic, State Management)
    ├── App.css                # Glassmorphism & Cinematic styling, animations
    └── main.jsx               # React DOM rendering entry point
```

## ⚙️ Backend Architecture (`server.cjs`)

The backend is responsible for bypassing cross-origin restrictions (CORS) and handling unsupported browser video formats (like MKV) through real-time processing.

### Key Endpoints:
- `GET /api/metadata`: Probes the provided video URL using HTTP HEAD requests or `ffprobe`. Detects file size, duration, container type, and extracts internal audio track metadata.
- `GET /api/stream`: The core streaming engine. 
  - If the file is a standard MP4/WebM, it acts as a direct byte-range proxy.
  - If the file is an MKV or requires transcoding, it spawns an `ffmpeg` child process. It pipes fragmented MP4 directly to the Express response, supporting real-time seeking, audio track switching, and optional HEVC-to-H.264 transcoding.

## 🎨 Frontend Architecture (`src/App.jsx`)

The frontend is a monolithic yet organized React component that manages the entire lifecycle of the media player.

### Key Capabilities:
- **State Management**: Handles player states (Play/Pause, Volume, Fullscreen), stream metadata, bookmarks, history, and buffering telemetry.
- **Subtitle Processing**: The `srtToVtt` utility function converts uploaded SRT subtitle files into WebVTT format entirely on the client side.
- **Speedometer & Telemetry**: Uses video buffering API (`video.buffered`) to calculate download speeds and buffer health in real-time.
- **Sandbox Player**: Utilizes `URL.createObjectURL` to allow users to play large local files securely without uploading them to the server.