Libraries Folder Structures and Scanning

Adding a Library

1. Open Settings → Libraries.
2. Click Add Library.
3. Provide a Display Name (e.g., "Main Collection") and the Folder Path inside the container (e.g. /comics).
4. Select the organization mode: Metadata Mode or Folder Mode.

Metadata Mode vs. Folder Mode

Feature	Metadata Mode (Default)	Folder Mode
Hierarchy	Root Folder → Publisher → Series → Issue	Root Folder → Folder 1 → Folder 2 → File
Source of Truth	Embedded ComicInfo.xml or sidecar	Physical filesystem layout on disk
Best For	Curated collections, standardized naming	Unsorted collections, custom directory trees
Filtering	By publisher, publication year, volume	By folder name

Scan Pipeline & Error Safeguards

When a scan is triggered (manually or via schedule):

1. Recursive Traversal: Scans all subdirectories for .cbz, .cbr, and .pdf files.
2. Metadata Extraction: Reads ComicInfo.xml from the archive or adjacent .ComicInfo.xml sidecar.
3. Format Conversion: Automatically converts PDFs or CBRs to CBZ (if enabled in settings).
4. Thumbnail Generation: Extracts the first page and saves an optimized WebP thumbnail into /app/data/thumbnails/.
5. Database Sync: Adds new records and updates modified files.
6. I/O Error Safeguard: If any directory fails to read during traversal (e.g. an unmounted NAS share), the server aborts missing file cleanup immediately. This prevents accidental deletion of reading progress or lists due to temporary disk disconnects.

Scan Intervals & Scheduling

In Settings → General Settings:

• Configure Scan Interval: Set how frequently the server checks for new comics (e.g., every 6 hours, 24 hours, or a custom cron expression).
• Toggle Full Rescan vs Quick Scan: Quick scans inspect modified timestamps; Full rescans re-evaluate all metadata and covers.