wisecolt/dupe
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

readme index eklendi

Browse Source
This commit is contained in:
szbk
2025-11-03 22:46:44 +03:00
parent dee1ed696f
commit f4c9d4ca41
4 changed files with 1690 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

653
claudedocs/api-documentation.md Normal file
View File

@@ -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
<video controls>
<source src="http://localhost:3001/stream/abc123def456/0" type="video/mp4">
</video>
```
---
### **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.*

237
claudedocs/index.md Normal file
View File

@@ -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.*

589
claudedocs/knowledge-base.md Normal file
View File

@@ -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 <repository-url>
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.*

211
claudedocs/project-structure.md Normal file
View File

@@ -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.*