# NextAV Documentation

> A modern, YouTube-like media library management system built with Next.js

## 📋 **Quick Navigation**

### **🟢 Current Features** (Production Ready)
- **[Feature Status](FEATURE_STATUS.md)** - Implementation overview
- **[Documentation Organization](DOCUMENTATION_ORGANIZATION.md)** - Doc structure guide

#### **Library Cluster System** 
Comprehensive media organization with clusters
- 📁 [`active/library-clusters/`](active/library-clusters/) - Complete documentation
- ✅ **Status**: Production ready
- 🎯 **Features**: Cluster management, library mapping, statistics, folder navigation

#### **Media Streaming & Format Support**
Zero-transcoding media streaming with local player fallback
- 📁 [`active/media-streaming/`](active/media-streaming/) - Core streaming documentation
- 📁 [`active/media-streaming-root/`](active/media-streaming-root/) - Additional streaming features
- ✅ **Status**: Production ready  
- 🎯 **Features**: Direct streaming, format detection, local player integration, auto-launch, transcoding fixes

#### **Surprise Me Recommendations**
Intelligent content discovery system
- 📁 [`active/recommendations/`](active/recommendations/) - Design & implementation
- ⚠️ **Status**: MVP ready (3/7 algorithms)
- 🎯 **Features**: Multiple algorithms, media access tracking

#### **Recent Fixes & Enhancements**
Latest improvements and bug fixes
- 📁 [`active/fixes-enhancements/`](active/fixes-enhancements/) - Fix documentation
- ✅ **Status**: Implemented and tested
- 🎯 **Features**: Auto-close fixes, migration guides, implementation tracking, library IntelliSense

#### **Performance Optimization**
Systematic performance improvements for large datasets
- 📁 [`active/performance/`](active/performance/) - Performance documentation
- ✅ **Status**: Implementation planning complete
- 🎯 **Features**: API pagination, virtual scrolling, database optimization, caching strategy

#### **Library Scan Enhancement**
Enhanced scanning with file cleanup, thumbnail recovery, and progress tracking
- 📁 [`active/library-clusters/`](active/library-clusters/) - Enhanced scan documentation (4 docs)
- 📁 **Requirements**: [`LIBRARY_SCAN_ENHANCEMENT_REQUIREMENTS.md`](active/library-clusters/LIBRARY_SCAN_ENHANCEMENT_REQUIREMENTS.md)
- 📁 **Architecture**: [`LIBRARY_SCAN_ENHANCEMENT_ARCHITECTURE.md`](active/library-clusters/LIBRARY_SCAN_ENHANCEMENT_ARCHITECTURE.md)
- 📁 **Implementation**: [`LIBRARY_SCAN_ENHANCEMENT_IMPLEMENTATION.md`](active/library-clusters/LIBRARY_SCAN_ENHANCEMENT_IMPLEMENTATION.md)
- 📁 **Summary**: [`LIBRARY_SCAN_ENHANCEMENT_SUMMARY.md`](active/library-clusters/LIBRARY_SCAN_ENHANCEMENT_SUMMARY.md)
- 📋 **Status**: Planning complete, ready for development
- 🎯 **Features**: File cleanup, thumbnail recovery, progress tracking, error handling
- ⚡ **Priority**: 🔴 Critical - Core functionality gaps

### **🧪 Testing Suite**
Comprehensive testing framework for all components
- 📁 [`tests/`](../tests/) - Test scripts and utilities
- ✅ **Status**: Active testing framework
- 🎯 **Coverage**: Player, streaming, performance, diagnostics (8 test scripts)

### **🟡 Planned Features**
- 📁 [`planning/`](planning/) - Future enhancements
- 🎯 **ArtPlayer Enhancement**: Direct playback optimization (1 document)

### **📚 Archive**
- 📁 [`archive/transcoding-legacy/`](archive/transcoding-legacy/) - Removed transcoding features
- 📁 [`archive/deployment-legacy/`](archive/deployment-legacy/) - Historical deployment info

---

## 🚀 **Getting Started**

### **Development Setup**
```bash
# Install dependencies
pnpm install

# Run development server
pnpm dev

# Build for production
pnpm build
```

### **Docker Deployment**
```bash
# Build and run with Docker Compose
docker-compose up -d

# Access application
open http://localhost:3000
```

---

## 📊 **Feature Implementation Status**

| Feature | Status | Progress |
|---------|--------|----------|
| Library Clusters | ✅ Complete | 100% |
| Transcoding Removal | ✅ Complete | 100% |
| Video Player | ✅ Complete | 100% |
| Folder Bookmarks | ✅ Complete | 100% |
| Performance Optimization | ✅ Planning Complete | 100% |
| Testing Framework | ✅ Complete | 100% |
| Library Scan Enhancement | 📋 Planning Complete | 100% |
| Surprise Me (MVP) | ⚠️ Partial | 43% |
| Recommendation ML | 📋 Planned | 0% |

---

## 🛠️ **Technical Stack**

- **Frontend**: Next.js 15.5.0, React 19.1.0, TypeScript
- **Styling**: TailwindCSS v3.4.17
- **Database**: SQLite with better-sqlite3
- **Video Player**: ArtPlayer with HLS.js support
- **Media Processing**: FFmpeg for thumbnails
- **Deployment**: Docker with multi-stage builds

---

## 📖 **Core Requirements** ✅

All original requirements from project specification are implemented:

- ✅ YouTube-like UI with collapsible sidebar
- ✅ Media library management with scanning
- ✅ Support for 10,000+ media files
- ✅ Photo and video support
- ✅ Library add/remove functionality  
- ✅ SQLite database with proper schema
- ✅ Thumbnail generation with hashed storage
- ✅ Bookmark system for videos
- ✅ 1-5 star rating system
- ✅ Text file viewer
- ✅ Docker deployment

---

## 🔗 **Useful Links**

- **[CLAUDE.md](../CLAUDE.md)** - Project requirements and specifications
- **[package.json](../package.json)** - Dependencies and scripts
- **[docker-compose.yml](../docker-compose.yml)** - Deployment configuration

---

*Last Updated: October 13, 2025*  
*Next Review: October 20, 2025*