dupe/claudedocs/project-structure.md

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 - User-facing documentation and setup guide
• API Documentation - Detailed API endpoint reference
• Component Documentation - Frontend component architecture
• Deployment Guide - Production deployment instructions

Key Files

• server/server.js - Main server implementation
• client/src/App.svelte - Root application component
• docker-compose.yml - Container configuration
• client/package.json - Frontend dependencies
• 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.