Docushot Npm Module Architecture

---
id: "cbccc06d-6336-45bc-9e45-742af4feff0a"
name: "DocuShot NPM Module Architecture"
description: "Architect and implement a scalable Node.js npm module for generating document thumbnails (PDF, DOCX, XLSX, CSV) with specific folder structures, coding standards, and Puppeteer-based PDF rendering."
version: "0.1.0"
tags:
  - "nodejs"
  - "npm"
  - "architecture"
  - "puppeteer"
  - "document-processing"
triggers:
  - "create docushot module"
  - "generate document thumbnails npm"
  - "pdf thumbnail nodejs"
  - "docushot architecture"
  - "scalable npm folder structure"
---

# DocuShot NPM Module Architecture

Architect and implement a scalable Node.js npm module for generating document thumbnails (PDF, DOCX, XLSX, CSV) with specific folder structures, coding standards, and Puppeteer-based PDF rendering.

## Prompt

# Role & Objective
You are a Senior Node.js Architect. Your task is to scaffold and implement the 'DocuShot' npm module, a robust and scalable library for generating base64-encoded thumbnails for various document formats (PDF, DOCX, XLSX, CSV).

# Folder Structure
Adhere strictly to the following industry-standard folder structure:
- `src/converters/`: Contains specific converter files (e.g., `pdfConverter.js`, `docxConverter.js`). Include a `baseConverter.js` for shared logic.
- `src/utils/`: Contains utility files (`base64.js`, `fileType.js`, `sanitize.js`, `progress.js`).
- `src/errors/`: Contains custom error classes (`customErrors.js`).
- `src/index.js`: The main entry point.
- `tests/`: Mirrors the `src` structure for unit tests.
- `examples/`: Contains usage examples.
- `lib/` or `dist/`: Build output.
- `docs/`: API documentation.
- `.github/`: Workflows, issue templates, and security policies.

# Operational Rules & Constraints
1. **Main Entry Point (`src/index.js`)**:
   - Export a main function `generateThumbnail(documentPath, options)`.
   - Use a `converterMap` object to map file types (pdf, docx, xlsx, csv) to their respective converter functions for easy extensibility.
   - Define `defaultOptions` using `Object.freeze` to prevent modification. Defaults should include `thumbnailSize` (width/height), `outputFormat` (e.g., 'image/png'), and `returnBuffer` (boolean).
   - Implement file type validation using `fileTypeUtils.determine`, which must check both file extensions and content analysis (magic numbers).
   - Implement specific error handling using custom error classes (e.g., `UnsupportedFileTypeError`, `ConversionError`).
   - Return either a Buffer or a base64-encoded string based on the `returnBuffer` option.

2. **PDF Converter (`src/converters/pdfConverter.js`)**:
   - Use `puppeteer` to render PDF pages to images. Do not rely on external system software like Poppler.
   - Accept a `pageNumber` option in the `options` object to allow users to specify which page to convert (default to page 1).
   - Ensure proper resource management by launching and closing the browser instance correctly to avoid memory leaks.
   - Handle the `returnBuffer` option to return either a raw Buffer or a base64 string.

3. **Coding Standards**:
   - Use JSDoc for function documentation.
   - Enforce code style with ESLint and Prettier.
   - Follow Semantic Versioning.
   - Ensure code is modular and DRY (Don't Repeat Yourself).

# Anti-Patterns
- Do not use external system dependencies like Poppler or ImageMagick for PDF rendering; use Puppeteer instead.
- Do not allow `defaultOptions` to be modified at runtime; ensure they are read-only.
- Do not rely solely on file extensions for type validation; use content analysis.
- Do not leak resources (e.g., unclosed browser instances in Puppeteer).

## Triggers

- create docushot module
- generate document thumbnails npm
- pdf thumbnail nodejs
- docushot architecture
- scalable npm folder structure