Content Ingestion Lifecycle

MehguViewer Core Nodes support a robust ingestion pipeline designed to handle large archives (ZIP/CBZ/EPUB) efficiently. This process is asynchronous to ensure the API remains responsive.

The Upload Flow

1. Metadata Creation

First, the Administrator creates the Series container. This establishes the urn:mvn:series:{uuid} and defines the media type (Manga, Video, Novel).

2. Archive Upload (Bulk)

The Administrator uploads a chapter as a single archive file.

Endpoint: POST /api/v1/series/{id}/chapters
Format: multipart/form-data
Parameters:
- file: The .zip/.cbz archive.
- metadata: JSON string (title, number).
- parser_config: (Optional) JSON string to configure filename parsing (e.g., regex).
Response: 202 Accepted

The server does not process the images immediately. It streams the file to temporary storage and returns a Job ID.

3. Manual Upload (Granular)

For finer control, or when using external CDNs, Administrators can use the granular upload flow.

Create Unit Container:
- POST /api/v1/series/{id}/units
- Payload: { "unit_number": 1, "title": "Chapter 1" }
- Returns: { "id": "unit_uuid", ... }
Add Pages:
- POST /api/v1/units/{unit_id}/pages
- Option A (Binary): Upload image via multipart/form-data.
- Option B (Link): JSON payload { "url": "https://cdn.example.com/page1.jpg", "page_number": 1 }.

4. Background Processing

A background worker picks up the job (for bulk uploads) and performs the following:

Unpacking: Extracts the archive.
Hashing: Calculates a cryptographic hash for every image. This allows for deduplication across the node.
Asset Generation: Creates urn:mvn:asset:{uuid} records for each file.
Optimization: (Optional) Generates web-optimized versions (WebP/AVIF) if configured.
Finalization: The Chapter (Unit) is marked as READY and becomes visible to users.

Error Handling

If the background process fails (e.g., corrupt zip file), the Job status is updated to FAILED. Administrators can query the job status to see the error log.

Content Ingestion