docs: Update README.md and add STRUCTURE.md

README.md

@@ -1,30 +1,99 @@
+<div align="center">
+
+  <h1>NovaStream</h1>
+
+  <p align="center">
+    <strong>A powerful, offline-capable browser media player with cinematic glassmorphism design.</strong>
+  </p>
+
+  <p align="center">
+    Stream direct URLs, play large local MKV files with advanced HEVC hardware decoding, and convert subtitles on the fly with a sleek, theater-grade interface.
+  </p>
+
+  <div align="center">
+    <img src="https://img.shields.io/badge/Node.js-Express-68a063?style=for-the-badge&logo=node.js&logoColor=white" alt="Node.js" />
+    <img src="https://img.shields.io/badge/React-Vite-61dafb?style=for-the-badge&logo=react&logoColor=black" alt="React" />
+    <img src="https://img.shields.io/badge/License-GPL%203.0-blue?style=for-the-badge&logo=open-source-initiative&logoColor=white" alt="GPL 3.0" />
+    <img src="https://img.shields.io/badge/FFmpeg-Transmuxing-ff4f00?style=for-the-badge&logo=ffmpeg&logoColor=white" alt="FFmpeg" />
+  </div>
+</div>
+
+<hr />
+
+## ✨ Features
+
+- **Direct MKV Proxy Streaming**: Seamlessly stream remote MKV files right within the browser without having to download them completely.
+- **Zero-Latency HEVC/H.264 Handling**: Native support for high-efficiency video coding. Hardware decoding for crisp, lag-free playback.
+- **Offline Capability**: Directly stream large local files from your server or through the browser sandbox.
+- **On-the-fly Transmuxing**: Real-time conversion of MKV containers using FFmpeg backend integration. Supports real-time HEVC to H.264 transcoding fallback.
+- **Subtitle Parsing & Track Switching**: Automatically converts standard SRT subtitle files to WebVTT on the fly. Switch between multiple embedded audio tracks effortlessly.
+- **Cinematic Theater Mode**: An immersive, auto-hiding UI wrapped in a premium Glassmorphism design language.
+- **Real-Time Telemetry**: Monitor bandwidth speed and buffer health instantly with the built-in speedometer.
+
+---
+
+## 🛠️ Tech Stack & Architecture
+
+- **Frontend**: React 19, Vite, Lucide Icons. Pure custom CSS for dynamic cinematic and glassmorphic aesthetics.
+- **Backend**: Node.js, Express.js. Handles URL probing, CORS bypassing, direct stream proxying, and spawns FFmpeg processes for real-time transmuxing.
+- **Transmuxer Engine**: FFmpeg is utilized to map video and audio streams seamlessly to browser-compatible fragmented MP4.
+
+Check out our [STRUCTURE.md](STRUCTURE.md) for a detailed breakdown of the codebase and file structure.
+
 ---
-title: NovaStream
-emoji: 🚀
-colorFrom: purple
-colorTo: indigo
-sdk: docker
-app_port: 7860
-pinned: false
+
+## 🚀 Deployment & Installation
+
+NovaStream can be deployed natively using Node.js or easily containerized with Docker.
+
+### Prerequisites
+- Node.js (v18+)
+- FFmpeg installed and available in the system PATH.
+
+### Standard Node.js Setup
+
+1. **Clone the repository:**
+   ```bash
+   git clone https://github.com/urstark/NovaStream.git
+   cd NovaStream
+   ```
+
+2. **Install dependencies:**
+   ```bash
+   npm install
+   ```
+   *(Note: For development, use `npm run dev` to start concurrently)*
+
+3. **Build the Frontend:**
+   ```bash
+   npm run build
+   ```
+
+4. **Start the Server:**
+   ```bash
+   npm start
+   ```
+
+The application will be running on port `7860` (or `process.env.PORT`).
+
+### Docker Setup
+
+```bash
+docker build -t novastream .
+docker run -p 7860:7860 novastream
+```
+
 ---
 
-# NovaStream
+## 👨‍💻 Developer Credits
 
-NovaStream is a powerful, offline-capable browser media player. Stream direct URLs, play large local MKV files with advanced HEVC hardware decoding, and convert subtitles on the fly with a sleek, theater-grade interface.
+- **Developer:** [urstarkz](https://github.com/urstark)
+- **Website:** [urstark.is-a.dev](https://urstark.is-a.dev)
+- **Telegram:** [t.me/urstarkz](https://t.me/urstarkz)
+- **Instagram:** [@urstarkz](https://instagram.com/urstarkz)
 
-## Developer Credits
-* **Developer:** urstarkz
-* **Website:** [urstark.is-a.dev](https://urstark.is-a.dev)
-* **Telegram:** [t.me/urstarkz](https://t.me/urstarkz)
-* **Instagram:** [@urstarkz](https://instagram.com/urstarkz)
+---
 
-## Features
-* Direct MKV proxy streaming
-* Zero-latency HEVC/H.264 handling
-* Offline capability for local files
-* Theater mode with auto-hiding UI
-* Subtitle parsing & track switching
-* Glassmorphism cinematic design
+## ⚖️ License
 
-## Deployment
-Can be deployed via Docker or a standard Node.js server.
+NovaStream is open-source software licensed under the **GPL-3.0 License**. See the [LICENSE](LICENSE) file for more details.

STRUCTURE.md

@@ -0,0 +1,45 @@
+# 🗂️ 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.