211 lines
8.7 KiB
Markdown
211 lines
8.7 KiB
Markdown
# 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.* |