Product Requirements Document

• Product records live in different systems, and the IDs do not always match.
• Images and documents get uploaded, but it is not always clear which products they belong to.
• It is hard to tell which products are complete, incomplete, or have bad data.
• Duplicate data is easy to miss. Small differences in the data create confusion.
• Reviews often happen through email, spreadsheets, or chat instead of inside a clear workflow.
• Websites, reports, and internal tools end up using data that is inconsistent or missing important fields.
• Clients have trouble maintaining their own data because the process is not obvious, which leads to stale records and more cleanup later.

• Replace a full enterprise PIM or DAM system. This system is meant to pull from those sources and make the data easier to use in websites, web tools, and internal systems.
• Provide advanced image editing tools.
• Support every possible third-party integration.
• Automatically publish records without a person reviewing them first.
• Act as the final public-facing e-commerce storefront.
• Try to cover every possible use case. Some client needs will still require custom development from the engineering team.

• Product Manager: Needs visibility into product readiness, data quality, and launch blockers.
• Content Manager: Manages descriptions, images, specifications, and supporting files.
• Operations User: Uploads files, fixes records, reviews missing information, and monitors workflow status.
• Engineer: Needs reliable data structures, consistent identifiers, predictable APIs, and clear validation rules.
• Administrator: Manages permissions, required fields, categories, and system configuration.

As a product manager, I want to create and edit product records so the data is stored in one structured place instead of being managed through disconnected files and systems.

• Users can create a new product with the required fields.
• Users can edit product details after the record is created.
• Users can assign a product to one or more categories.
• Users can add outside identifiers such as SKU, vendor ID, part number, or another system ID.
• Users can connect a product to one or more images, including image categories or roles.
• Users can connect a product to one or more files, such as manuals, diagrams, spec sheets, or supporting documents.
• The system prevents duplicate primary identifiers.
• The system shows clear validation errors before the record is saved.

As a content manager, I want to upload images and files and connect them to products so each product has the right supporting assets.

• Users can upload supported image and document file types.
• The system automatically creates thumbnails and optimized versions for uploaded images.
• Users can upload a zip file containing individual product shots to generate a 360-degree image set.
• Each uploaded asset receives a unique system identifier.
• The system can detect exact duplicate files and help users avoid uploading the same asset multiple times.
• Users can associate one asset with one or more products.
• Users can mark an image as primary, secondary, detail, lifestyle, reference, or part of a 360-degree set.
• Users can remove a product association without deleting the underlying asset.
• The system tracks who uploaded the asset and when it was uploaded.

As a product manager, I want to see whether a product is complete so that I know whether it is ready for publishing or launch.

• The system calculates a completeness status for each product.
• Completeness rules can include required fields, images, documents, and category-specific requirements.
• Products are labeled with statuses such as Draft, In Review, Ready, Published, or Blocked.
• Users can filter products by missing data, missing images, missing documents, or failed validation.
• The system shows specific reasons why a product is incomplete.

As an operations user, I want the system to catch duplicate products, images, and files before they create cleanup problems or conflicting records.

• The system detects duplicate product identifiers or prevents them from being created in the first place.
• The system detects exact duplicate files using file hash comparison.
• The system flags possible duplicate product records using configurable matching rules.
• Users can review possible duplicates before deciding whether to merge them or dismiss the warning.
• All actions are tracked in the audit history, including who made the change, when it happened, and what changed.
• The system does not automatically merge records without user confirmation.

As a reviewer, I want product data and assets to go through a review process before they are treated as ready to use or publish.

• Users can submit a product for review when they believe the record is complete.
• Reviewers can approve the product, reject it, or request specific changes.
• If a reviewer rejects a product, they must include a reason so the next step is clear.
• The system records who reviewed the product, what decision was made, when it happened, and any comments added during the review.
• Products cannot be marked Ready or Published while required review steps are still incomplete.
• Users can see the current workflow status from the product detail page, list view, or dashboard.

• Users can create, edit, view, soft-delete, and hard-delete product records when permissions allow it.
• The system supports required and optional product fields.
• Client-specific details can be stored in a dedicated JSON field so the core data model does not become too rigid or overloaded with one-off fields.
• The system supports category-specific fields when certain product types need extra information.
• Products can store external identifiers such as SKU, vendor ID, part number, or another system ID.
• Products can move through clear statuses such as Draft, In Review, Ready, Published, Blocked, or Archived.
• The system can calculate a readiness score based on missing fields, missing assets, validation issues, and review status.

• Users can upload images and documents.
• The system supports bulk asset uploads and background processing for larger batches.
• The system automatically extracts basic asset metadata, including file name, file type, file size, image dimensions, and quality-related details when available.
• The system creates thumbnails for uploaded images.
• The system creates web-optimized image versions for desktop and mobile so pages and tools are not loading oversized files.
• The system keeps the original uploaded asset unchanged. For images, optimized versions are served by default unless the original file is specifically requested.
• Assets can be connected to one or more products.
• Users can assign roles to assets, such as primary image, secondary image, detail image, manual, diagram, or supporting document.
• The system checks for duplicate assets so users do not keep uploading the same file.
• The system tracks processing status, including pending, processing, completed, failed, and needs review.

• The system checks that required fields are filled in before a product can move forward.
• The system prevents duplicate primary identifiers, such as SKU, product ID, or another required system ID.
• The system only allows supported file types for uploads.
• The system blocks files that are larger than the allowed size limit.
• The system checks that required image roles are present, such as a primary image when one is needed.
• The system checks that required document types are attached, such as manuals, diagrams, spec sheets, or compliance documents.
• The system supports category-specific rules, since different product types may need different fields, images, or files.

Products are the main records in the system. A product stores the core information that identifies the item, but it should not try to hold every relationship directly. Products can belong to one or more categories, can be connected to images and files, and can carry client-specific data when needed.

• product_id - unique internal product identifier
• name - product name shown to users and downstream systems
• sku - unique product number or client-facing identifier
• group_id - optional grouping field for product families, brands, collections, or client-specific groupings
• type_id - identifies the product type when different product types need different rules or fields
• description - general product description
• status - current product state, such as draft, active, inactive, archived, or blocked
• completeness_score - calculated score showing how complete the product record is
• meta - JSON field for internal data that does not fit in the standard product fields
• custom_data - JSON field for client specific data that does not fit in the standard product fields
• created_at - when the product record was created
• updated_at - when the product record was last changed
• created_by - user or system that created the product
• updated_by - user or system that last updated the product

Categories organize products into useful groups for websites, internal tools, reporting, filtering, and client-specific views. Categories can be nested, which makes it possible to support simple category lists or deeper category trees without changing the product table itself.

• category_id - unique internal category identifier
• name - category name shown in the interface or downstream systems
• parent_id - optional parent category, used when categories are nested
• description - short explanation of what belongs in the category
• status - controls whether the category is active, inactive, archived, or hidden
• completeness_score - optional score used when categories have required setup, rules, or metadata
• custom_data - JSON field for client specific data that does not fit in the standard product fields
• created_at - when the category was created
• updated_at - when the category was last changed
• created_by - user or system that created the category
• updated_by - user or system that last updated the category

Products and categories should be connected through a separate join table because one product can belong to multiple categories, and one category can contain many products. A composite unique key on product_id and category_id should prevent the same relationship from being created more than once.

• join_id - unique identifier for the relationship record, if a surrogate key is needed
• product_id - product being assigned to the category
• category_id - category assigned to the product
• created_at - when the relationship was created
• updated_at - when the relationship was last changed

Assets represent uploaded images, documents, manuals, diagrams, spec sheets, and other files. Assets are stored separately from products so the same file can be reused across multiple products without being uploaded more than once.

• asset_id - unique internal asset identifier
• file_name - original or display file name
• file_type - file format or MIME type, such as image/jpeg, image/png, or application/pdf
• file_size - size of the uploaded file
• storage_path - location of the file in storage
• meta - JSON field for extra internal metadata that does not need a dedicated column yet
• checksum - file hash used for duplicate detection and file integrity checks
• width - image width when the asset is an image
• height - image height when the asset is an image
• thumbnail_path - location of the generated thumbnail, when available
• upload_status - current processing state, such as pending, processing, completed, failed, or needs review
• custom_data - JSON field for client specific data that does not fit in the standard product fields
• created_at - when the asset was uploaded or created
• uploaded_by - user or system that uploaded the asset

Products and assets should also be connected through a relationship table. This makes it possible for one product to have many assets and for one asset to be reused by many products. The relationship also stores how the asset is used, such as whether it is the primary image, a manual, a diagram, or a supporting file.

• product_id - product connected to the asset
• asset_id - asset connected to the product
• asset_role - explains how the asset is used, such as primary image, secondary image, manual, diagram, spec sheet, or reference file
• sort_order - controls display order when a product has multiple assets
• is_primary - marks the main asset for the product when applicable
• created_at - when the relationship was created
• created_by - user or system that created the relationship

• Duplicate SKU: If a user attempts to create a product with an existing SKU, the system blocks the save and links to the existing product.
• Reused Asset: If the same image applies to multiple products, the system allows reuse instead of requiring duplicate uploads.
• Failed Thumbnail Generation: The original file remains stored, the asset is marked with a processing error, and the user can retry processing.
• Deleted Product With Shared Assets: Shared assets are not automatically deleted when a product is removed.
• Asset Uploaded Before Product Exists: Users can upload assets into an unattached asset library and associate them later.
• Category Rule Changes: Existing products are revalidated when category requirements change.
• Conflicting Updates: The system prevents silent overwrites when two users edit the same record at the same time.

Assets should be stored separately from products because the same image, manual, diagram, or file may apply to more than one product. This avoids duplicate uploads and lets the team manage file quality, metadata, and processing status without tying everything directly to one product record.

Product-to-asset relationships should be stored in their own table instead of saving asset IDs directly on the product. This makes it easier to track the role of each asset, control display order, mark primary images, reuse files, and add audit history later.

Products and assets should usually be soft-deleted instead of removed immediately. This keeps history intact and makes it easier to recover from mistakes, troubleshoot data problems, or understand past changes. Hard deletes should be limited to administrators and used only when the data is no longer needed.

A flexible data model can support many product types, client rules, asset types, and relationships, but it can also make the system harder to understand. The system should keep the normal workflow simple and only show the extra complexity when users actually need it.

Automated validation and duplicate detection can save a lot of cleanup time, but the system may still flag records that are not actually a problem. For that reason, the system should point out issues and suggest actions, but users should make the final decision before important records are merged, changed, or published.

• Percentage of products with complete required fields.
• Percentage of products with required images.
• Percentage of products with required documents.
• Reduction in duplicate product records.
• Reduction in orphaned assets.
• Reduction in oversized image usage while preserving acceptable visual quality.

• Time from product creation to approval.
• Time from asset upload to successful product association.
• Number of manual correction tasks required per launch or update.
• Percentage of products approved without rework.
• Time saved when preparing product data for websites, internal tools, reports, or client exports.

• Reduction in total image storage size after optimized versions are generated.
• Reduction in bandwidth usage from serving optimized images instead of originals.
• Storage cost by asset type, including originals, thumbnails, optimized images, and documents.
• Processing cost for thumbnail generation, optimization, metadata extraction, and duplicate detection.
• Use of appropriate storage tiers to balance performance, access needs, and cost.

• Upload success rate.
• Asset processing success rate.
• Background job failure rate.
• API error rate.
• Average response time for key product and asset endpoints.