personal_development/ServerManagerWebApp/documentation/APPLICATION_GUIDE.md

Server Manager Web App - Application Guide

Overview

The Server Manager Web App is a Python-based full-stack application designed to manage home media server resources. It provides a user-friendly web interface for interacting with Samba file shares, identifying video duplicates, and organizing comic book libraries.

Architecture

The application follows a standard client-server architecture:

Backend

• Framework: FastAPI (Python)
• Database: SQLite (managed via SQLAlchemy)
• Role: Handles API requests, performs complex logic (duplicate detection, file operations, comic conversion), and manages database state.
• Key Modules:
  • samba_manager.py: Handles SMB protocol interactions (listing, moving, deleting files).
  • duplicates_manager.py: Implements logic for identifying duplicate video files based on duration, visual hashing, and metadata.
  • comics_manager.py: Manages the conversion of .zip to .cbz and organizes files into hierarchical folders.

Frontend

• Framework: Vue.js 3
• Build Tool: Vite
• Styling: CSS
• Role: Provides the interactive UI for the user. It communicates with the backend via RESTful API calls.
• Key Components:
  • SambaExplorer.vue: A file browser interface for SMB shares.
  • VideoDuplicatesManager.vue: A dashboard to view duplicate reports and take action (delete/archive).
  • ComicsManager.vue: Tools for triggering comic organization tasks.

Features

1. Samba File Explorer:

   • Browse files on configured Samba shares.
   • Upload, download, delete, and rename files.
   • View file details.

2. Video Duplicate Finder:

   • Scans specified directories for potential duplicate videos.
   • Uses visual similarity (image hashing), duration, and file size.
   • Presents a report allowing users to resolve duplicates.

3. Comics Organizer:

   • Scans for comic archives (.zip).
   • Converts them to the standard .cbz format.
   • Sorts comics into folders based on series names.

Configuration

• Backend Dependencies: Listed in backend/requirements.txt.
• Frontend Dependencies: Listed in frontend/package.json.
• Database: Uses a local SQLite file (default test.db or similar defined in config.py or database.py).

Running the Application

Helper scripts are provided in the root directory:

• Start: ./start_app.sh - Starts both the backend API and the frontend development server.
• Stop: ./stop_app.sh - Stops the running backend and frontend processes.