readme index eklendi
This commit is contained in:
653
claudedocs/api-documentation.md
Normal file
653
claudedocs/api-documentation.md
Normal 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
237
claudedocs/index.md
Normal 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
589
claudedocs/knowledge-base.md
Normal 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
211
claudedocs/project-structure.md
Normal 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.*
|
||||
Reference in New Issue
Block a user