fragginwagon
961ed44055
Define thumbnail, medium, and large WebP derivative variants behind an injected renderer and write them through ImageStorage with deterministic keys. Add focused tests and document the remaining worker-backed renderer. Verification: npm test passed 70 tests and integration passed 14 tests. No build script is configured.
2.4 KiB
Image Management
Requirements
Multiple images are core functionality.
Use cases include:
- card front/back
- corners
- edges/whitening
- holographic details
- merchandise angles
- defects/details
Workflow
Upload → Validate → Store Original → Queue Processing → Generate Derivatives → Complete
Support:
- multiple-file upload
- drag/drop
- preview
- reorder
- primary image
- delete
- add images later
Image count is configurable.
Storage
Images are not stored in PostgreSQL.
Use an ImageStorage abstraction.
Initial:
- Docker-mounted local storage
Future:
- S3-compatible object storage
The API uses an ImageStorage contract with put, get, and delete
operations. The current local adapter rejects absolute and traversal paths and
does not overwrite an existing key. It stores bytes outside PostgreSQL; image
metadata remains in inventory_images.
Processing
Validate:
- MIME type
- file signature where practical
- size
- image dimensions
- configured image count
The metadata service currently enforces JPEG, PNG, and WebP MIME types, a 10 MiB default file-size limit, and a 10,000-pixel maximum width and height. Multipart upload validation now checks the declared MIME type against JPEG, PNG, and WebP signatures before storage. Image dimensions are supplied by the upload transport until a decoder-backed dimension extractor is added.
Generate:
- thumbnail
- medium
- large/responsive derivatives
Modern formats such as WebP/AVIF may be used where appropriate.
Retain originals where practical.
Derivative orchestration currently defines thumbnail, medium, and large WebP
variants and writes them through ImageStorage using an injected renderer.
The concrete decoder/encoder and worker queue remain separate infrastructure
work so local development does not depend on a machine-specific binary.
Metadata
Store:
- storage key
- original filename
- MIME type
- file size
- dimensions
- alt text
- order
- primary flag
- processing status
- timestamps
Alt text
Generate an initial suggestion automatically, but require the seller to be able to review/edit it.
Do not invent details not visible or supplied by the seller.
Accessibility
Public galleries must support:
- keyboard operation
- accessible controls
- visible focus
- meaningful names
- focus management
- screen-reader-friendly state
Primary images power cards, search results, homepage previews, and social/share metadata.