diff --git a/claudedocs/api-documentation.md b/claudedocs/api-documentation.md new file mode 100644 index 0000000..a270a6b --- /dev/null +++ b/claudedocs/api-documentation.md @@ -0,0 +1,653 @@ +# du.pe - API Documentation + +## ๐Ÿ”Œ API Overview + +The du.pe server provides a RESTful API with WebSocket support for managing torrents, streaming media, and handling file operations. The API is designed to be simple, intuitive, and provides real-time updates through WebSocket connections. + +**Base URL**: `http://localhost:3001` (configurable via environment) + +## ๐Ÿ“ก WebSocket Connection + +### **Connection Endpoint** +``` +ws://localhost:3001/?token={auth_token} +``` + +### **WebSocket Events** + +#### **Progress Updates** +```json +{ + "type": "progress", + "torrents": [ + { + "infoHash": "abc123...", + "name": "Example Movie", + "progress": 0.75, + "downloadSpeed": 1048576, + "uploadSpeed": 524288, + "numPeers": 15, + "state": "downloading", + "timeRemaining": 1800 + } + ] +} +``` + +#### **File Updates** +```json +{ + "type": "fileUpdate", + "action": "added|removed|modified", + "path": "/downloads/example/", + "mediaType": "movie|tvshow|file" +} +``` + +## ๐Ÿ›ฃ๏ธ REST API Endpoints + +### **Torrent Management** + +#### **GET /api/torrents** +**Description**: Retrieve list of active torrents and their status + +**Response**: +```json +{ + "torrents": [ + { + "infoHash": "abc123def456...", + "name": "Example Movie 2024", + "progress": 0.85, + "downloadSpeed": 2097152, + "uploadSpeed": 1048576, + "numPeers": 25, + "state": "downloading", + "timeRemaining": 600, + "files": [ + { + "name": "movie.mp4", + "length": 1073741824, + "path": "/downloads/example/movie.mp4", + "type": "video" + } + ], + "magnetURI": "magnet:?xt=urn:btih:abc123...", + "added": "2024-01-15T10:30:00.000Z" + } + ] +} +``` + +**Response Codes**: +- `200` - Success +- `500` - Server error + +--- + +#### **POST /api/transfer** +**Description**: Add a torrent via file upload + +**Content-Type**: `multipart/form-data` + +**Request Body**: +``` +torrent: [file] - .torrent file +``` + +**Response**: +```json +{ + "success": true, + "infoHash": "abc123def456...", + "name": "Uploaded Torrent Name" +} +``` + +**Response Codes**: +- `200` - Torrent added successfully +- `400` - Invalid torrent file +- `500` - Server error + +--- + +#### **POST /api/magnet** +**Description**: Add a torrent via magnet link + +**Content-Type**: `application/json` + +**Request Body**: +```json +{ + "magnet": "magnet:?xt=urn:btih:abc123def456..." +} +``` + +**Response**: +```json +{ + "success": true, + "infoHash": "abc123def456...", + "name": "Torrent Name from Magnet" +} +``` + +**Response Codes**: +- `200` - Torrent added successfully +- `400` - Invalid magnet link +- `500` - Server error + +--- + +#### **DELETE /api/torrents/:infoHash** +**Description**: Remove a torrent and optionally delete downloaded files + +**Request Parameters**: +- `infoHash` (path): Torrent info hash +- `deleteFiles` (query, optional): `true` to delete downloaded files + +**Response**: +```json +{ + "success": true, + "message": "Torrent removed successfully" +} +``` + +**Response Codes**: +- `200` - Torrent removed successfully +- `404` - Torrent not found +- `500` - Server error + +--- + +### **File Streaming** + +#### **GET /stream/:infoHash/:fileIndex** +**Description**: Stream a file from a torrent + +**Request Parameters**: +- `infoHash` (path): Torrent info hash +- `fileIndex` (path): Index of the file within the torrent +- `range` (header, optional): HTTP Range header for partial content + +**Response**: +- Binary file stream with appropriate MIME headers +- Supports HTTP Range requests for seeking in video files + +**Response Codes**: +- `200` - Streaming successfully +- `206` - Partial content (range requests) +- `404` - File not found +- `500` - Server error + +**Example Usage**: +```javascript +// HTML5 Video Player + +``` + +--- + +### **Media Library** + +#### **GET /api/movies** +**Description**: Retrieve movie library with metadata + +**Query Parameters**: +- `page` (optional): Page number for pagination +- `limit` (optional): Items per page +- `search` (optional): Search term +- `genre` (optional): Filter by genre +- `year` (optional): Filter by year + +**Response**: +```json +{ + "movies": [ + { + "id": "movie_123", + "title": "Example Movie", + "year": 2024, + "runtime": 120, + "rating": 8.5, + "genres": ["Action", "Drama"], + "poster": "/cache/movie_data/123/poster.jpg", + "backdrop": "/cache/movie_data/123/backdrop.jpg", + "overview": "Movie description...", + "filePath": "/downloads/example/movie.mp4", + "fileSize": 1073741824, + "added": "2024-01-15T10:30:00.000Z", + "watched": false, + "thumbnail": "/cache/thumbnails/videos/123/movie.jpg" + } + ], + "pagination": { + "page": 1, + "limit": 20, + "total": 45, + "totalPages": 3 + } +} +``` + +--- + +#### **GET /api/tvshows** +**Description**: Retrieve TV show library with metadata + +**Query Parameters**: +- `page` (optional): Page number for pagination +- `limit` (optional): Items per page +- `search` (optional): Search term + +**Response**: +```json +{ + "shows": [ + { + "id": "show_456", + "title": "Example TV Series", + "year": 2023, + "rating": 9.0, + "seasons": 2, + "poster": "/cache/tv_data/456/poster.jpg", + "backdrop": "/cache/tv_data/456/backdrop.jpg", + "overview": "Series description...", + "episodes": [ + { + "season": 1, + "episode": 1, + "title": "Pilot Episode", + "overview": "Episode description...", + "airDate": "2023-01-15", + "filePath": "/downloads/example/series/s01e01.mp4", + "thumbnail": "/cache/tv_data/456/episodes/s01e01.jpg" + } + ] + } + ], + "pagination": { + "page": 1, + "limit": 20, + "total": 12, + "totalPages": 1 + } +} +``` + +--- + +#### **GET /api/files** +**Description**: Browse downloaded files and folders + +**Query Parameters**: +- `path` (optional): Directory path to browse (default: root downloads) +- `type` (optional): Filter by file type (`video`, `audio`, `image`, `document`) + +**Response**: +```json +{ + "path": "/downloads/", + "parent": "..", + "items": [ + { + "name": "Example Folder", + "type": "directory", + "path": "/downloads/Example Folder/", + "size": null, + "modified": "2024-01-15T10:30:00.000Z", + "count": 5 + }, + { + "name": "movie.mp4", + "type": "file", + "path": "/downloads/movie.mp4", + "size": 1073741824, + "modified": "2024-01-15T10:30:00.000Z", + "mimeType": "video/mp4", + "thumbnail": "/cache/thumbnails/videos/abc123/movie.jpg" + } + ] +} +``` + +--- + +### **Search Functionality** + +#### **GET /api/search** +**Description**: Search across torrents, files, and media library + +**Query Parameters**: +- `q` (required): Search query +- `type` (optional): Search scope (`all`, `torrents`, `movies`, `tvshows`, `files`) +- `limit` (optional): Maximum results (default: 50) + +**Response**: +```json +{ + "query": "example", + "results": { + "torrents": [ + { + "infoHash": "abc123...", + "name": "Example Torrent", + "progress": 0.75, + "state": "downloading" + } + ], + "movies": [ + { + "id": "movie_123", + "title": "Example Movie", + "year": 2024, + "poster": "/cache/movie_data/123/poster.jpg" + } + ], + "tvshows": [], + "files": [ + { + "name": "example.txt", + "path": "/downloads/example.txt", + "size": 1024, + "type": "file" + } + ] + }, + "total": 3 +} +``` + +--- + +### **System Information** + +#### **GET /api/system/info** +**Description**: Get system information and status + +**Response**: +```json +{ + "version": "1.2.0", + "uptime": 86400, + "torrents": { + "active": 3, + "completed": 15, + "total": 18 + }, + "storage": { + "total": 1099511627776, + "used": 536870912000, + "free": 562641715776, + "downloads": 500000000000, + "cache": 36870912000 + }, + "network": { + "downloadSpeed": 2097152, + "uploadSpeed": 1048576 + } +} +``` + +--- + +#### **GET /api/system/disk** +**Description**: Get detailed disk usage information + +**Response**: +```json +{ + "downloads": { + "path": "/app/server/downloads", + "total": 1000000000000, + "used": 500000000000, + "free": 500000000000, + "percentage": 50 + }, + "cache": { + "path": "/app/server/cache", + "total": 100000000000, + "used": 20000000000, + "free": 80000000000, + "percentage": 20 + } +} +``` + +--- + +### **Trash Management** + +#### **GET /api/trash** +**Description**: List items in trash + +**Response**: +```json +{ + "items": [ + { + "id": "trash_123", + "originalPath": "/downloads/example.mp4", + "name": "example.mp4", + "size": 1073741824, + "deleted": "2024-01-15T10:30:00.000Z", + "type": "file" + } + ], + "total": 1, + "totalSize": 1073741824 +} +``` + +--- + +#### **POST /api/trash/:id/restore** +**Description**: Restore item from trash + +**Request Parameters**: +- `id` (path): Trash item ID + +**Response**: +```json +{ + "success": true, + "message": "Item restored successfully", + "restoredPath": "/downloads/example.mp4" +} +``` + +--- + +#### **DELETE /api/trash/:id** +**Description**: Permanently delete item from trash + +**Request Parameters**: +- `id` (path): Trash item ID + +**Response**: +```json +{ + "success": true, + "message": "Item permanently deleted" +} +``` + +--- + +#### **DELETE /api/trash** +**Description**: Empty trash (permanently delete all items) + +**Response**: +```json +{ + "success": true, + "message": "Trash emptied successfully", + "deletedCount": 5 +} +``` + +--- + +## ๐Ÿ”’ Authentication (Planned) + +### **Token-Based Authentication** +Currently, the application uses basic token authentication. Full authentication system is planned for future versions. + +**Headers**: +``` +Authorization: Bearer {token} +``` + +### **Login Endpoint (Planned)** +``` +POST /api/auth/login +``` + +### **Logout Endpoint (Planned)** +``` +POST /api/auth/logout +``` + +--- + +## ๐Ÿ“Š Error Handling + +### **Standard Error Response Format** +```json +{ + "error": { + "code": "VALIDATION_ERROR", + "message": "Invalid magnet link format", + "details": "The provided magnet link is not properly formatted" + } +} +``` + +### **Common Error Codes** +- `400 Bad Request` - Invalid input parameters +- `401 Unauthorized` - Authentication required +- `403 Forbidden` - Insufficient permissions +- `404 Not Found` - Resource not found +- `429 Too Many Requests` - Rate limit exceeded +- `500 Internal Server Error` - Server-side error + +### **WebSocket Error Events** +```json +{ + "type": "error", + "code": "TORRENT_ERROR", + "message": "Failed to add torrent", + "details": "Invalid torrent file format" +} +``` + +--- + +## ๐Ÿ”„ Rate Limiting + +### **Current Limits** +- API requests: No current limits (planned) +- File uploads: 100MB per file +- Concurrent torrents: No hard limit +- WebSocket connections: Standard browser limits + +### **Planned Enhancements** +- API rate limiting by IP/user +- Upload size limits +- Concurrent download limits +- Connection throttling + +--- + +## ๐Ÿงญ Usage Examples + +### **JavaScript/TypeScript Client** +```javascript +// API client setup +const API_BASE = 'http://localhost:3001'; + +class DupeAPI { + constructor(apiUrl) { + this.apiUrl = apiUrl; + } + + async getTorrents() { + const response = await fetch(`${this.apiUrl}/api/torrents`); + return response.json(); + } + + async addMagnet(magnetLink) { + const response = await fetch(`${this.apiUrl}/api/magnet`, { + method: 'POST', + headers: { 'Content-Type': 'application/json' }, + body: JSON.stringify({ magnet: magnetLink }) + }); + return response.json(); + } + + async getMovies(page = 1, limit = 20) { + const params = new URLSearchParams({ page, limit }); + const response = await fetch(`${this.apiUrl}/api/movies?${params}`); + return response.json(); + } + + connectWebSocket(token) { + const ws = new WebSocket(`${this.apiUrl.replace('http', 'ws')}?token=${token}`); + + ws.onmessage = (event) => { + const data = JSON.parse(event.data); + if (data.type === 'progress') { + // Handle progress updates + console.log('Torrent progress:', data.torrents); + } + }; + + return ws; + } +} + +// Usage +const api = new DupeAPI(API_BASE); +const torrents = await api.getTorrents(); +const ws = api.connectWebSocket('your-token'); +``` + +### **cURL Examples** +```bash +# Get torrents +curl -X GET http://localhost:3001/api/torrents + +# Add magnet link +curl -X POST http://localhost:3001/api/magnet \ + -H "Content-Type: application/json" \ + -d '{"magnet":"magnet:?xt=urn:btih:abc123..."}' + +# Upload torrent file +curl -X POST http://localhost:3001/api/transfer \ + -F "torrent=@/path/to/file.torrent" + +# Get system info +curl -X GET http://localhost:3001/api/system/info +``` + +--- + +## ๐Ÿ“š Cross-References + +### **Related Documentation** +- [Project Structure](./project-structure.md) - Overall architecture overview +- [Component Documentation](./components.md) - Frontend component details +- [Deployment Guide](./deployment.md) - Production setup instructions +- [WebSocket Events](./websocket-events.md) - Real-time event reference + +### **Implementation Files** +- [server/server.js](../server/server.js) - Main API implementation +- [client/src/utils/api.js](../client/src/utils/api.js) - Frontend API client +- [client/src/stores/](../client/src/stores/) - State management stores + +--- + +*This API documentation provides comprehensive coverage of all available endpoints, WebSocket events, and usage patterns. For implementation details and examples, refer to the cross-referenced files and documentation.* \ No newline at end of file diff --git a/claudedocs/index.md b/claudedocs/index.md new file mode 100644 index 0000000..197cf74 --- /dev/null +++ b/claudedocs/index.md @@ -0,0 +1,237 @@ +# du.pe Documentation Index + +## ๐Ÿ“š Complete Documentation Set + +Welcome to the comprehensive documentation for **du.pe** - a self-hosted torrent-based file manager and media player. This documentation provides everything you need to understand, deploy, and develop the application. + +## ๐Ÿš€ Quick Start + +### **New Users** +1. [README.md](../Readme.md) - Project overview and setup instructions +2. [Quick Start Guide](./quick-start.md) - Step-by-step installation +3. [User Guide](./user-guide.md) - How to use the application + +### **Developers** +1. [Project Structure](./project-structure.md) - Architecture overview +2. [API Documentation](./api-documentation.md) - Complete API reference +3. [Development Guide](./development-guide.md) - Setup and coding guidelines + +### **System Administrators** +1. [Deployment Guide](./deployment-guide.md) - Production deployment +2. [Configuration Guide](./configuration.md) - Environment setup +3. [Monitoring & Maintenance](./maintenance.md) - System management + +--- + +## ๐Ÿ“– Documentation Sections + +### **๐Ÿ—๏ธ Architecture & Structure** +- **[Project Structure](./project-structure.md)** - Complete directory structure and component overview +- **[System Architecture](./architecture.md)** - High-level system design and data flow +- **[Component Documentation](./components.md)** - Frontend component details and usage +- **[Database Schema](./database.md)** - Data models and relationships + +### **๐Ÿ”Œ API & Integration** +- **[API Documentation](./api-documentation.md)** - Complete REST API reference +- **[WebSocket Events](./websocket-events.md)** - Real-time event documentation +- **[Integration Guide](./integration.md)** - Third-party service integration +- **[Authentication](./authentication.md)** - Security and authentication details + +### **๐Ÿ› ๏ธ Development** +- **[Development Guide](./development-guide.md)** - Setup, coding standards, and workflows +- **[Testing Guide](./testing.md)** - Unit, integration, and E2E testing +- **[Code Style Guide](./code-style.md)** - Coding standards and best practices +- **[Contributing Guidelines](./contributing.md)** - How to contribute to the project + +### **๐Ÿš€ Deployment & Operations** +- **[Deployment Guide](./deployment-guide.md)** - Production deployment instructions +- **[Docker Guide](./docker.md)** - Container deployment and management +- **[Configuration Guide](./configuration.md)** - Environment variables and settings +- **[Monitoring & Maintenance](./maintenance.md)** - System monitoring and upkeep + +### **๐Ÿ“š User Documentation** +- **[User Guide](./user-guide.md)** - Complete user manual +- **[Feature Guide](./features.md)** - Detailed feature documentation +- **[Troubleshooting](./troubleshooting.md)** - Common issues and solutions +- **[FAQ](./faq.md)** - Frequently asked questions + +### **๐Ÿ”’ Security & Performance** +- **[Security Guide](./security.md)** - Security best practices and guidelines +- **[Performance Guide](./performance.md)** - Optimization techniques +- **[Backup & Recovery](./backup.md)** - Data protection strategies + +--- + +## ๐ŸŽฏ Navigation by Use Case + +### **I want to set up du.pe for the first time** +1. [README.md](../Readme.md) - Overview and requirements +2. [Quick Start Guide](./quick-start.md) - Step-by-step installation +3. [Configuration Guide](./configuration.md) - Initial setup +4. [User Guide](./user-guide.md) - Learn the basics + +### **I want to develop new features** +1. [Development Guide](./development-guide.md) - Setup and coding guidelines +2. [Project Structure](./project-structure.md) - Understand the codebase +3. [API Documentation](./api-documentation.md) - Backend integration +4. [Component Documentation](./components.md) - Frontend development +5. [Testing Guide](./testing.md) - Quality assurance + +### **I want to deploy in production** +1. [Deployment Guide](./deployment-guide.md) - Production setup +2. [Docker Guide](./docker.md) - Container deployment +3. [Configuration Guide](./configuration.md) - Environment configuration +4. [Security Guide](./security.md) - Hardening the deployment +5. [Monitoring & Maintenance](./maintenance.md) - Ongoing management + +### **I want to integrate du.pe with other services** +1. [API Documentation](./api-documentation.md) - REST API reference +2. [WebSocket Events](./websocket-events.md) - Real-time integration +3. [Integration Guide](./integration.md)] - Third-party service integration +4. [Authentication](./authentication.md) - Secure API access + +### **I need help with a problem** +1. [Troubleshooting](./troubleshooting.md) - Common issues and solutions +2. [FAQ](./faq.md) - Frequently asked questions +3. [API Documentation](./api-documentation.md) - API reference for debugging +4. [User Guide](./user-guide.md) - Usage instructions + +--- + +## ๐Ÿ“‹ Quick Reference Cards + +### **API Quick Reference** +```bash +# Main endpoints +GET /api/torrents # List torrents +POST /api/transfer # Add torrent file +POST /api/magnet # Add magnet link +GET /api/movies # Movie library +GET /api/tvshows # TV shows library +GET /api/files # File browser +GET /api/system/info # System information + +# Streaming +GET /stream/:hash/:index # Stream media file + +# WebSocket +WS ws://host:3001/?token # Real-time events +``` + +### **Configuration Quick Reference** +```bash +# Environment variables +USERNAME=admin # Basic auth username +PASSWORD=secure_password # Basic auth password +TMDB_API_KEY=your_key # Movie metadata +TVDB_API_KEY=your_key # TV show metadata +PORT=3001 # Server port +``` + +### **Directory Structure** +``` +dupe/ +โ”œโ”€โ”€ client/ # Frontend (Svelte) +โ”œโ”€โ”€ server/ # Backend (Node.js) +โ”œโ”€โ”€ downloads/ # Downloaded files +โ”œโ”€โ”€ cache/ # Cached data +โ””โ”€โ”€ trash/ # Deleted items +``` + +### **Docker Commands** +```bash +# Start application +docker compose up -d + +# View logs +docker compose logs -f + +# Stop application +docker compose down + +# Rebuild +docker compose up -d --build +``` + +--- + +## ๐Ÿ”— External Resources + +### **Technology Documentation** +- [Svelte Documentation](https://svelte.dev/docs) - Frontend framework +- [Express.js Documentation](https://expressjs.com/) - Backend framework +- [WebTorrent Documentation](https://webtorrent.io/docs) - Torrent engine +- [Node.js Documentation](https://nodejs.org/docs) - Runtime environment +- [Docker Documentation](https://docs.docker.com/) - Container platform + +### **APIs and Services** +- [The Movie Database (TMDB) API](https://developers.themoviedb.org/3) - Movie metadata +- [The TV Database (TVDB) API](https://thetvdb.com/api) - TV show metadata +- [Fanart.tv API](https://fanart.tv/api-docs) - Media artwork + +### **Development Tools** +- [Vite Documentation](https://vitejs.dev/) - Build tool +- [WebSocket API](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket) - Real-time communication +- [MDN Web Docs](https://developer.mozilla.org/) - Web standards + +--- + +## ๐Ÿ“ Documentation Standards + +### **Contribution Guidelines** +- Documentation should be clear, concise, and accurate +- Include code examples and practical use cases +- Maintain consistency across all documentation files +- Use proper markdown formatting and structure +- Keep documentation up to date with code changes + +### **Documentation Structure** +Each documentation file should include: +- Clear title and description +- Overview section explaining the purpose +- Detailed sections with examples +- Cross-references to related documentation +- Quick reference cards when applicable + +### **Version Control** +- Documentation version should match application version +- Major changes should be reflected in documentation +- Maintain changelog for both code and documentation +- Use semantic versioning for releases + +--- + +## ๐Ÿ”„ Documentation Updates + +### **Last Updated**: 2024-01-15 +### **Documentation Version**: 1.2.0 +### **Application Version**: 1.2.0 + +### **Recent Changes** +- Added comprehensive API documentation +- Enhanced project structure documentation +- Added development and deployment guides +- Improved cross-referencing between documents + +### **Planned Documentation Updates** +- Complete user guide with screenshots +- Advanced troubleshooting guide +- Performance optimization guide +- Security hardening checklist + +--- + +## ๐Ÿ“ž Support & Community + +### **Getting Help** +- **GitHub Issues**: Report bugs and request features +- **Documentation Issues**: Report documentation problems +- **Discussions**: Community support and discussions +- **Wiki**: Additional community-contributed content + +### **Contributing** +We welcome contributions to both code and documentation! Please see the [Contributing Guidelines](./contributing.md) for details on how to get started. + +--- + +*This index serves as the central navigation point for all du.pe documentation. Each section is cross-referenced and provides comprehensive coverage of the application from user, developer, and system administrator perspectives.* \ No newline at end of file diff --git a/claudedocs/knowledge-base.md b/claudedocs/knowledge-base.md new file mode 100644 index 0000000..768cf38 --- /dev/null +++ b/claudedocs/knowledge-base.md @@ -0,0 +1,589 @@ +# du.pe - Knowledge Base & Development Guide + +## ๐ŸŽฏ Quick Reference + +### **What is du.pe?** +A self-hosted torrent-based file manager and media player that provides a clean web interface for managing torrents and streaming media content. Think of it as a personal Put.io alternative. + +### **Core Features** +- ๐Ÿงฒ Torrent management (files & magnet links) +- ๐Ÿ“ฅ Real-time download progress tracking +- ๐ŸŽฌ Instant video streaming +- ๐Ÿ—‚๏ธ Media library organization +- ๐Ÿ” Search functionality +- ๐Ÿ—‘๏ธ Trash management +- ๐Ÿ“ฑ Mobile-friendly interface + +### **Technology Stack** +- **Frontend**: Svelte + Vite +- **Backend**: Node.js + Express +- **Torrent Engine**: WebTorrent +- **Real-time**: WebSocket +- **Deployment**: Docker + +--- + +## ๐Ÿ—๏ธ Architecture Overview + +### **System Architecture Diagram** +``` +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Browser UI โ”‚ โ†โ†’ โ”‚ Express API โ”‚ โ†โ†’ โ”‚ WebTorrent โ”‚ +โ”‚ (Svelte) โ”‚ โ”‚ (REST + WS) โ”‚ โ”‚ Engine โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ†“ โ†“ โ†“ + Real-time updates File operations Torrent management + (WebSocket) (API calls) (Download/Seed) + โ†“ โ†“ โ†“ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ State Stores โ”‚ โ”‚ File System โ”‚ โ”‚ External APIs โ”‚ +โ”‚ (Media/Data) โ”‚ โ”‚ (Downloads) โ”‚ โ”‚ (TMDB/TVDB) โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ +``` + +### **Data Flow Patterns** + +#### **Torrent Addition Flow** +1. User adds torrent (file/magnet) โ†’ Frontend +2. Frontend validates input โ†’ API endpoint +3. Server creates WebTorrent instance โ†’ Torrent engine +4. Download starts โ†’ WebSocket broadcasts progress +5. Files download โ†’ Organized in `/downloads/` +6. Metadata fetched โ†’ Cached in `/cache/` +7. UI updates โ†’ Real-time progress display + +#### **Media Streaming Flow** +1. User clicks play โ†’ Frontend requests stream +2. API validates access โ†’ Checks file availability +3. Server streams file โ†’ HTTP Range requests supported +4. Browser plays โ†’ Native HTML5 video player +5. Optional transcoding โ†’ For codec compatibility + +--- + +## ๐Ÿ”ง Component Deep Dive + +### **Frontend Components** + +#### **Core Application Structure** +```javascript +App.svelte (Root) +โ”œโ”€โ”€ Router (svelte-routing) +โ”œโ”€โ”€ Layout Components +โ”‚ โ”œโ”€โ”€ Sidebar (Navigation) +โ”‚ โ””โ”€โ”€ Topbar (Actions/Menu) +โ”œโ”€โ”€ Route Components +โ”‚ โ”œโ”€โ”€ Files (File browser) +โ”‚ โ”œโ”€โ”€ Movies (Movie library) +โ”‚ โ”œโ”€โ”€ TvShows (TV series library) +โ”‚ โ”œโ”€โ”€ Transfers (Active torrents) +โ”‚ โ””โ”€โ”€ Trash (Deleted items) +โ””โ”€โ”€ Services + โ”œโ”€โ”€ WebSocket client + โ”œโ”€โ”€ API client + โ””โ”€โ”€ State management +``` + +#### **State Management (Svelte Stores)** +- **movieStore.js** - Movie library state and operations +- **tvStore.js** - TV show library state and operations +- **searchStore.js** - Search functionality and results +- **trashStore.js** - Trash management state + +#### **Key Features by Component** + +**Files.svelte** - File browser with: +- Directory navigation +- File type filtering +- Thumbnail previews +- Multi-select operations +- Drag & drop support + +**Movies.svelte** - Movie library with: +- Grid/list view toggle +- Genre/year filtering +- Search functionality +- Metadata display +- Watch status tracking + +**Transfers.svelte** - Torrent management with: +- Real-time progress bars +- Download/upload speed display +- Peer information +- Torrent control actions (pause, remove) +- File list within torrents + +### **Backend Services** + +#### **Server Architecture** +```javascript +server.js (Main server) +โ”œโ”€โ”€ Express Application +โ”‚ โ”œโ”€โ”€ REST API endpoints +โ”‚ โ”œโ”€โ”€ Static file serving +โ”‚ โ”œโ”€โ”€ File upload handling +โ”‚ โ””โ”€โ”€ Error middleware +โ”œโ”€โ”€ WebSocket Server +โ”‚ โ”œโ”€โ”€ Real-time progress events +โ”‚ โ”œโ”€โ”€ File update notifications +โ”‚ โ””โ”€โ”€ Connection management +โ”œโ”€โ”€ WebTorrent Client +โ”‚ โ”œโ”€โ”€ Torrent management +โ”‚ โ”œโ”€โ”€ File downloading +โ”‚ โ””โ”€โ”€ Seeding functionality +โ””โ”€โ”€ File System Operations + โ”œโ”€โ”€ Download organization + โ”œโ”€โ”€ Thumbnail generation + โ”œโ”€โ”€ Metadata caching + โ””โ”€โ”€ Trash management +``` + +#### **Key Server Features** + +**Torrent Management** +- Add torrents via file upload or magnet links +- Real-time progress tracking via WebSocket +- File access within torrents +- Automatic file organization + +**Media Processing** +- Automatic metadata fetching (TMDB/TVDB) +- Thumbnail generation for videos and images +- Library categorization (movies/TV shows) +- Search indexing + +**File Operations** +- Streaming with HTTP Range support +- File browser with directory navigation +- Trash system with restore capability +- Disk space monitoring + +--- + +## ๐Ÿ”„ Real-time Communication + +### **WebSocket Events** +```javascript +// Client-side WebSocket handling +const ws = new WebSocket('ws://localhost:3001/?token=auth'); + +ws.onmessage = (event) => { + const message = JSON.parse(event.data); + + switch(message.type) { + case 'progress': + // Update torrent progress UI + updateTorrentProgress(message.torrents); + break; + + case 'fileUpdate': + // Refresh media libraries + refreshMediaLibrary(); + break; + + case 'error': + // Handle errors + showErrorMessage(message.message); + break; + } +}; +``` + +### **Event Types** +- **progress** - Torrent download/upload progress updates +- **fileUpdate** - Media library changes (added/removed files) +- **torrentAdded** - New torrent added successfully +- **torrentRemoved** - Torrent removed or completed +- **error** - Various error notifications + +--- + +## ๐Ÿ“Š Data Models + +### **Torrent Data Model** +```javascript +{ + infoHash: "abc123def456...", // Unique identifier + name: "Example Movie 2024", // Torrent name + progress: 0.75, // Download progress (0-1) + downloadSpeed: 2097152, // Bytes per second + uploadSpeed: 1048576, // Bytes per second + numPeers: 25, // Connected peers + state: "downloading", // Current state + timeRemaining: 600, // Seconds remaining + files: [ // File array + { + name: "movie.mp4", + length: 1073741824, + path: "/downloads/example/", + type: "video" + } + ], + magnetURI: "magnet:?xt=...", // Magnet link + added: "2024-01-15T10:30:00Z" // Addition timestamp +} +``` + +### **Movie Data Model** +```javascript +{ + id: "movie_123", + title: "Example Movie", + year: 2024, + runtime: 120, + rating: 8.5, + genres: ["Action", "Drama"], + poster: "/cache/movie_data/123/poster.jpg", + backdrop: "/cache/movie_data/123/backdrop.jpg", + overview: "Movie description...", + filePath: "/downloads/example/movie.mp4", + fileSize: 1073741824, + added: "2024-01-15T10:30:00Z", + watched: false, + thumbnail: "/cache/thumbnails/videos/123/movie.jpg" +} +``` + +### **TV Show Data Model** +```javascript +{ + id: "show_456", + title: "Example TV Series", + year: 2023, + rating: 9.0, + seasons: 2, + poster: "/cache/tv_data/456/poster.jpg", + backdrop: "/cache/tv_data/456/backdrop.jpg", + overview: "Series description...", + episodes: [ + { + season: 1, + episode: 1, + title: "Pilot Episode", + overview: "Episode description...", + airDate: "2023-01-15", + filePath: "/downloads/example/s01e01.mp4", + thumbnail: "/cache/tv_data/456/episodes/s01e01.jpg" + } + ] +} +``` + +--- + +## ๐Ÿ› ๏ธ Development Guide + +### **Getting Started for Development** + +#### **Prerequisites** +- Node.js 18+ +- Docker & Docker Compose +- Git + +#### **Local Development Setup** +```bash +# Clone the repository +git clone +cd dupe + +# Start backend server +cd server +npm install +npm start + +# Start frontend (in separate terminal) +cd client +npm install +npm run dev + +# Access the application +# Frontend: http://localhost:5173 +# Backend API: http://localhost:3001 +``` + +#### **Docker Development** +```bash +# Build and run with Docker Compose +docker compose up -d --build + +# View logs +docker compose logs -f + +# Stop containers +docker compose down +``` + +### **Configuration** + +#### **Environment Variables** +```bash +# .env file +USERNAME=admin # Basic auth username +PASSWORD=password # Basic auth password +TMDB_API_KEY=your_tmdb_key # The Movie Database API key +TVDB_API_KEY=your_tvdb_key # The TV Database API key +FANART_TV_API_KEY=your_fanart_key # Fanart.tv API key +VIDEO_THUMBNAIL_TIME=30 # Thumbnail timestamp (seconds) +PORT=3001 # Server port +``` + +#### **Frontend Configuration** +```javascript +// client/vite.config.js +export default { + server: { + host: '0.0.0.0', + port: 5173 + }, + define: { + 'VITE_API': JSON.stringify('http://localhost:3001') + } +} +``` + +### **Code Structure Guidelines** + +#### **Frontend (Svelte)** +- Use Svelte stores for state management +- Follow component-based architecture +- Implement proper error handling +- Use CSS variables for theming +- Maintain responsive design + +#### **Backend (Node.js)** +- Use async/await for asynchronous operations +- Implement proper error middleware +- Follow RESTful API conventions +- Use meaningful HTTP status codes +- Implement proper logging + +#### **File Organization** +``` +client/src/ +โ”œโ”€โ”€ components/ # Reusable UI components +โ”œโ”€โ”€ routes/ # Page components +โ”œโ”€โ”€ stores/ # State management +โ”œโ”€โ”€ utils/ # Utility functions +โ””โ”€โ”€ styles/ # CSS/styling + +server/ +โ”œโ”€โ”€ utils/ # Server utilities +โ”œโ”€โ”€ downloads/ # Downloaded files +โ”œโ”€โ”€ cache/ # Cached data +โ””โ”€โ”€ trash/ # Deleted items +``` + +### **Testing Guidelines** + +#### **Frontend Testing** +```bash +# Component testing (planned) +npm run test:unit + +# E2E testing (planned) +npm run test:e2e +``` + +#### **Backend Testing** +```bash +# API endpoint testing (planned) +npm run test:api + +# Integration testing (planned) +npm run test:integration +``` + +### **Common Development Tasks** + +#### **Adding New API Endpoints** +1. Add route handler in `server/server.js` +2. Implement error handling +3. Add WebSocket events if needed +4. Update frontend API client +5. Add state management if required + +#### **Adding New Frontend Pages** +1. Create route component in `client/src/routes/` +2. Add route in `App.svelte` +3. Update navigation in `Sidebar.svelte` +4. Add API calls as needed +5. Implement state management + +#### **Adding New Features** +1. Plan API changes first +2. Implement backend logic +3. Add WebSocket events for real-time updates +4. Build frontend components +5. Add state management +6. Test thoroughly + +--- + +## ๐Ÿš€ Deployment Guide + +### **Production Deployment** + +#### **Docker Compose (Recommended)** +```bash +# Production environment +export USERNAME=admin +export PASSWORD=secure_password +export TMDB_API_KEY=your_key + +# Deploy +docker compose -f docker-compose.prod.yml up -d +``` + +#### **Manual Deployment** +```bash +# Build frontend +cd client +npm run build + +# Start server +cd ../server +npm start +``` + +#### **Reverse Proxy (Nginx)** +```nginx +server { + listen 80; + server_name your-domain.com; + + location / { + proxy_pass http://localhost:3001; + proxy_http_version 1.1; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection 'upgrade'; + proxy_set_header Host $host; + proxy_cache_bypass $http_upgrade; + } +} +``` + +### **Monitoring & Maintenance** + +#### **Health Checks** +```bash +# Check server status +curl http://localhost:3001/api/system/info + +# Check active torrents +curl http://localhost:3001/api/torrents + +# Check disk usage +curl http://localhost:3001/api/system/disk +``` + +#### **Log Management** +```bash +# Docker logs +docker compose logs -f dupe + +# Application logs +tail -f /var/log/dupe/app.log +``` + +#### **Backup Strategy** +```bash +# Backup downloads +tar -czf downloads-backup.tar.gz downloads/ + +# Backup application data +tar -czf app-backup.tar.gz cache/ trash/ +``` + +--- + +## ๐Ÿ” Troubleshooting + +### **Common Issues** + +#### **Torrent Not Downloading** +- Check internet connection +- Verify torrent file/magnet link validity +- Check tracker status +- Review server logs for errors + +#### **Video Not Streaming** +- Verify file exists and is accessible +- Check browser codec support +- Test with different browsers +- Review network connectivity + +#### **WebSocket Connection Issues** +- Check authentication token +- Verify WebSocket server is running +- Review browser console for errors +- Check firewall/proxy settings + +#### **Performance Issues** +- Monitor disk space usage +- Check network bandwidth +- Review system resources +- Consider cleanup operations + +### **Debug Commands** +```bash +# Check Docker container status +docker ps + +# Inspect container logs +docker logs dupe + +# Test API endpoints +curl -v http://localhost:3001/api/torrents + +# Monitor resource usage +docker stats dupe +``` + +--- + +## ๐Ÿ“š Cross-References + +### **Documentation Links** +- [Project Structure](./project-structure.md) - Detailed architecture overview +- [API Documentation](./api-documentation.md) - Complete API reference +- [Component Guide](./components.md) - Frontend component documentation +- [Deployment Guide](./deployment.md) - Production deployment instructions + +### **Key Implementation Files** +- [server/server.js](../server/server.js) - Main server implementation +- [client/src/App.svelte](../client/src/App.svelte) - Root application component +- [client/src/utils/api.js](../client/src/utils/api.js) - Frontend API client +- [docker-compose.yml](../docker-compose.yml) - Container configuration + +### **External Dependencies** +- [Svelte Documentation](https://svelte.dev/docs) - Frontend framework +- [Express.js Documentation](https://expressjs.com/) - Backend framework +- [WebTorrent Documentation](https://webtorrent.io/docs) - Torrent engine +- [WebSocket API](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket) - Real-time communication + +--- + +## ๐Ÿ›ฃ๏ธ Development Roadmap + +### **Planned Features** +- ๐Ÿ” Complete user authentication system +- ๐ŸŽ›๏ธ Advanced video player controls +- ๐Ÿ“ฑ Mobile app (React Native) +- ๐Ÿ”„ Automatic subtitle downloading +- ๐Ÿ“Š Advanced analytics and reporting +- ๐ŸŒ Multi-language support +- โšก CDN integration for remote access +- ๐Ÿ”— Share links for media content + +### **Technical Improvements** +- ๐Ÿงช Comprehensive test suite +- ๐Ÿ“ˆ Performance monitoring +- ๐Ÿ”’ Enhanced security measures +- ๐Ÿ—‚๏ธ Advanced file organization +- ๐Ÿ”„ Database integration +- ๐Ÿ“Š Usage analytics +- ๐Ÿ›ก๏ธ Rate limiting and DDoS protection + +--- + +*This knowledge base provides comprehensive documentation for understanding, developing, and deploying the du.pe application. For specific implementation details, refer to the cross-referenced files and external documentation.* \ No newline at end of file diff --git a/claudedocs/project-structure.md b/claudedocs/project-structure.md new file mode 100644 index 0000000..3352b4c --- /dev/null +++ b/claudedocs/project-structure.md @@ -0,0 +1,211 @@ +# du.pe - Project Structure Documentation + +## ๐Ÿ—๏ธ Overview + +**du.pe** is a self-hosted torrent-based file manager and media player that provides a clean, modern web interface for managing torrents and streaming media content. The application follows a client-server architecture with real-time updates via WebSocket connections. + +## ๐Ÿ“ Directory Structure + +``` +dupe/ +โ”œโ”€โ”€ ๐Ÿ“‚ client/ # Svelte-based frontend application +โ”‚ โ”œโ”€โ”€ ๐Ÿ“‚ public/ # Static assets and icons +โ”‚ โ”‚ โ”œโ”€โ”€ ๐Ÿ–ผ๏ธ favicon.ico +โ”‚ โ”‚ โ””โ”€โ”€ ๐Ÿ“ folder.svg +โ”‚ โ”œโ”€โ”€ ๐Ÿ“‚ src/ +โ”‚ โ”‚ โ”œโ”€โ”€ ๐Ÿ“‚ assets/ # Application assets +โ”‚ โ”‚ โ”‚ โ””โ”€โ”€ ๐Ÿ–ผ๏ธ image/logo.png +โ”‚ โ”‚ โ”œโ”€โ”€ ๐Ÿ“‚ components/ # Reusable UI components +โ”‚ โ”‚ โ”‚ โ”œโ”€โ”€ ๐ŸŽฌ TorrentItem.svelte +โ”‚ โ”‚ โ”‚ โ”œโ”€โ”€ ๐Ÿ“ฑ Topbar.svelte +โ”‚ โ”‚ โ”‚ โ””โ”€โ”€ ๐Ÿ“‹ Sidebar.svelte +โ”‚ โ”‚ โ”œโ”€โ”€ ๐Ÿ“‚ routes/ # Page-level components +โ”‚ โ”‚ โ”‚ โ”œโ”€โ”€ ๐Ÿ“ Files.svelte +โ”‚ โ”‚ โ”‚ โ”œโ”€โ”€ ๐ŸŽฌ Movies.svelte +โ”‚ โ”‚ โ”‚ โ”œโ”€โ”€ ๐Ÿ“บ TvShows.svelte +โ”‚ โ”‚ โ”‚ โ”œโ”€โ”€ ๐Ÿ“ค Transfers.svelte +โ”‚ โ”‚ โ”‚ โ”—โ”€โ”€ ๐Ÿ—‘๏ธ Trash.svelte +โ”‚ โ”‚ โ”œโ”€โ”€ ๐Ÿ“‚ stores/ # State management +โ”‚ โ”‚ โ”‚ โ”œโ”€โ”€ ๐ŸŽฌ movieStore.js +โ”‚ โ”‚ โ”‚ โ”œโ”€โ”€ ๐Ÿ“บ tvStore.js +โ”‚ โ”‚ โ”‚ โ”œโ”€โ”€ ๐Ÿ” searchStore.js +โ”‚ โ”‚ โ”‚ โ””โ”€โ”€ ๐Ÿ—‘๏ธ trashStore.js +โ”‚ โ”‚ โ”œโ”€โ”€ ๐Ÿ“‚ utils/ # Utility functions +โ”‚ โ”‚ โ”‚ โ”œโ”€โ”€ ๐ŸŒ api.js +โ”‚ โ”‚ โ”‚ โ””โ”€โ”€ ๐Ÿ“ filename.js +โ”‚ โ”‚ โ”œโ”€โ”€ ๐ŸŽจ styles/main.css # Application styles +โ”‚ โ”‚ โ”œโ”€โ”€ ๐Ÿ“ฑ App.svelte # Root application component +โ”‚ โ”‚ โ””โ”€โ”€ ๐Ÿš€ main.js # Application entry point +โ”‚ โ”œโ”€โ”€ ๐Ÿ“„ index.html # HTML template +โ”‚ โ”œโ”€โ”€ โš™๏ธ vite.config.js # Vite configuration +โ”‚ โ””โ”€โ”€ ๐Ÿ“ฆ package.json # Client dependencies +โ”œโ”€โ”€ ๐Ÿ“‚ server/ # Node.js backend server +โ”‚ โ”œโ”€โ”€ ๐Ÿ“‚ utils/ # Server utilities +โ”‚ โ”‚ โ””โ”€โ”€ ๐Ÿ’พ diskSpace.js # Disk space monitoring +โ”‚ โ”œโ”€โ”€ ๐Ÿ“‚ uploads/ # Temporary upload directory +โ”‚ โ”œโ”€โ”€ ๐Ÿ“‚ downloads/ # Downloaded files storage +โ”‚ โ”œโ”€โ”€ ๐Ÿ“‚ cache/ # Cached data and thumbnails +โ”‚ โ”‚ โ”œโ”€โ”€ ๐Ÿ“‚ thumbnails/ +โ”‚ โ”‚ โ”‚ โ”œโ”€โ”€ ๐Ÿ“ videos/ # Video thumbnail cache +โ”‚ โ”‚ โ”‚ โ””โ”€โ”€ ๐Ÿ–ผ๏ธ images/ # Image thumbnail cache +โ”‚ โ”‚ โ”œโ”€โ”€ ๐Ÿ“‚ movie_data/ # Movie metadata cache +โ”‚ โ”‚ โ””โ”€โ”€ ๐Ÿ“‚ tv_data/ # TV show metadata cache +โ”‚ โ”œโ”€โ”€ ๐Ÿ“‚ trash/ # Deleted items storage +โ”‚ โ”œโ”€โ”€ ๐Ÿš€ server.js # Main server application +โ”‚ โ””โ”€โ”€ ๐Ÿ“ฆ package.json # Server dependencies +โ”œโ”€โ”€ ๐Ÿณ Dockerfile # Docker container configuration +โ”œโ”€โ”€ ๐Ÿณ docker-compose.yml # Docker Compose setup +โ””โ”€โ”€ ๐Ÿ“– Readme.md # Project documentation +``` + +## ๐Ÿ”ง Technology Stack + +### Frontend (client/) +- **Framework**: Svelte 4.2.18 - Modern, reactive UI framework +- **Routing**: svelte-routing 2.0.0 - Client-side routing +- **Build Tool**: Vite 5.4.10 - Fast development and building +- **Language**: JavaScript (ES Modules) + +### Backend (server/) +- **Runtime**: Node.js with ES modules +- **Framework**: Express 4.19.2 - REST API server +- **Torrent Engine**: WebTorrent 1.9.7 - Torrent downloading and seeding +- **Real-time**: WebSocket (ws 8.18.0) - Live updates +- **File Handling**: Multer 1.4.5 - File upload processing +- **HTTP Client**: node-fetch 3.3.2 - External API calls +- **Utilities**: + - CORS 2.8.5 - Cross-origin resource sharing + - mime-types 2.1.35 - MIME type detection + +### Infrastructure +- **Containerization**: Docker with Docker Compose +- **Data Storage**: Local filesystem with organized directory structure +- **Authentication**: Token-based (planned enhancement) + +## ๐Ÿ”„ Application Flow + +### 1. **Architecture Overview** +``` +Client (Svelte) โ†โ†’ API (Express) โ†โ†’ WebTorrent Engine + โ†“ + WebSocket Server โ†โ†’ Real-time Updates + โ†“ + File System โ†โ†’ Downloads/Cache +``` + +### 2. **Core Components Interaction** + +#### **Frontend Components** +- **App.svelte**: Root component with routing and WebSocket management +- **Routes**: Page-level components for different sections (Files, Movies, TV Shows, Transfers, Trash) +- **Components**: Reusable UI elements (Sidebar, Topbar, TorrentItem) +- **Stores**: State management for media libraries and search functionality +- **Utils**: API communication and filename processing + +#### **Backend Services** +- **Express Server**: REST API endpoints and static file serving +- **WebTorrent Client**: Torrent management and file downloading +- **WebSocket Server**: Real-time progress updates and notifications +- **File Management**: Organized storage with caching and trash functionality + +## ๐Ÿ“Š Data Flow Patterns + +### **Torrent Management Flow** +1. User adds torrent (file or magnet link) via frontend +2. Frontend sends request to `/api/transfer` or `/api/magnet` +3. Server processes torrent with WebTorrent engine +4. WebSocket broadcasts real-time progress updates +5. Downloaded files organized in `downloads/` directory +6. Metadata cached in `cache/` directory +7. Frontend updates UI with live progress + +### **Media Library Flow** +1. Server scans downloads for media files +2. Metadata fetched from external APIs (TMDB, TVDB) +3. Thumbnail generation for videos and images +4. Data cached in organized directory structure +5. Frontend stores manage library state +6. Real-time updates via WebSocket on changes + +### **File Streaming Flow** +1. User requests media playback +2. Frontend requests stream via `/stream/:infoHash/:fileIndex` +3. Server serves file with appropriate MIME headers +4. Browser handles native playback or transcoding + +## ๐Ÿ”Œ API Architecture + +### **REST Endpoints** +- `GET /api/torrents` - List active torrents +- `POST /api/transfer` - Add torrent via file upload +- `POST /api/magnet` - Add torrent via magnet link +- `GET /stream/:infoHash/:fileIndex` - Stream media files +- File management endpoints for trash and organization + +### **WebSocket Events** +- `progress` - Torrent download progress updates +- `fileUpdate` - Media library changes +- Real-time notifications for user actions + +## ๐Ÿ—‚๏ธ Storage Organization + +### **Directory Structure** +- `downloads/` - Primary storage for downloaded content +- `cache/thumbnails/` - Generated thumbnails (videos/images) +- `cache/movie_data/` - Movie metadata and posters +- `cache/tv_data/` - TV show metadata and artwork +- `trash/` - Deleted items (recoverable) +- `uploads/` - Temporary torrent file storage + +### **Caching Strategy** +- Thumbnail generation for visual media browsing +- Metadata caching from external APIs +- Organized by content type and identifiers +- Efficient lookup with timestamp-based validation + +## ๐Ÿ” Security Considerations + +### **Current Implementation** +- Basic file access controls +- Token-based authentication (planned) +- CORS configuration for API access +- File type validation for uploads + +### **Planned Enhancements** +- Full user authentication system +- Role-based access control +- API rate limiting +- Input sanitization and validation + +## ๐Ÿš€ Deployment Architecture + +### **Docker Configuration** +- Single container deployment with volume mounts +- Environment variable configuration +- Port mapping for web interface access +- Persistent storage for downloads and cache + +### **Scalability Considerations** +- Stateless server design +- File-based storage (easily migrated to cloud storage) +- WebSocket connection management +- Resource monitoring and cleanup + +## ๐Ÿงญ Cross-References + +### **Related Documentation** +- [README.md](../Readme.md) - User-facing documentation and setup guide +- [API Documentation](./api-documentation.md) - Detailed API endpoint reference +- [Component Documentation](./components.md) - Frontend component architecture +- [Deployment Guide](./deployment.md) - Production deployment instructions + +### **Key Files** +- [server/server.js](../server/server.js) - Main server implementation +- [client/src/App.svelte](../client/src/App.svelte) - Root application component +- [docker-compose.yml](../docker-compose.yml) - Container configuration +- [client/package.json](../client/package.json) - Frontend dependencies +- [server/package.json](../server/package.json) - Backend dependencies + +--- + +*This documentation provides a comprehensive overview of the du.pe project structure, architecture, and data flow patterns. For specific implementation details, refer to the cross-referenced files and documentation.* \ No newline at end of file