# 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

Generate:
- thumbnail
- medium
- large/responsive derivatives

Modern formats such as WebP/AVIF may be used where appropriate.

Retain originals where practical.

## 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.