pokemon-inventory/docs/DATA-MODEL.md

Data Model

Core relationship

User → Seller → Product → Inventory Item → Listing
                                  │
                                  ├── Images
                                  ├── Acquisition
                                  ├── Pricing Observations
                                  ├── Market Valuations
                                  └── Activity

Sale → Sale Items → Inventory Items

Product

Represents what the item is, independent of physical ownership.

Examples:

• Charizard ex — SV151 — #199/165
• Pokémon Center Worlds 2025 Pikachu Plush

Products persist after all inventory is sold.

Inventory Item

Represents one physical copy.

Each copy has its own:

• condition
• images
• acquisition
• asking price/listing
• market valuation
• notes
• status

Do not model multiple physical copies as a quantity field on one Inventory Item.

Listing

Represents how an Inventory Item is currently offered publicly.

A Product can have many physical Inventory Items with different conditions and asking prices.

Sale

A manual external transaction. One Sale can contain multiple Sale Items.

Provider Product Mapping

Provider mappings are Product-level relationships.

Recommended fields:

• id
• product_id
• provider_id
• mapping_type (PRODUCT or SEARCH)
• external_identifier
• search_query / search parameters
• source_url
• status
• metadata
• created_at
• updated_at
• disabled_at

A provider can support one or both mapping types.

eBay supports both:

• specific product/catalog mappings where appropriate
• search/query mappings where no canonical product is appropriate

Mappings can be replaced without destroying historical records.

Only one active/default mapping per provider should be used for normal pricing unless a provider integration explicitly supports multiple active sources.

Suggested pricing tables

pricing_providers

id, name, code, is_enabled, priority, configuration, created_at, updated_at

product_pricing_providers

product_id, provider_id, is_enabled

pricing_provider_mappings

As described above.

pricing_observations

id, product_id, inventory_item_id, provider_id, source_identifier, source_url, condition_id, price_minor, currency, observed_at, quality_score, is_outlier, outlier_reason, raw_reference

market_valuations

id, inventory_item_id, value_minor, currency, strategy, confidence, source_count, calculated_at

market_value_overrides

id, inventory_item_id, value_minor, currency, reason, created_by, created_at, removed_at

pricing_jobs

id, job_type, status, requested_by, started_at, completed_at, total_items, processed_items, successful_items, failed_items, error_summary, created_at

Conditions

condition_profiles:

• id
• category_id
• name
• active
• sort

conditions:

• id
• condition_profile_id
• name
• code
• quality_rank
• description
• active
• sort

Images

inventory_images:

• id
• inventory_item_id
• storage_key
• original_filename
• mime_type
• file_size
• width
• height
• alt_text
• sort_order
• is_primary
• processing_status
• created_at
• updated_at

Acquisitions

acquisitions:

• id
• inventory_item_id
• method
• cost_minor
• currency
• date
• source
• location
• shipping_minor
• tax_minor
• other_fees_minor
• estimated_trade_value_minor
• notes
• created_at
• updated_at

Sales

sales:

• id
• seller_id
• sale_date
• sale_location
• sold_price_minor
• currency
• platform_fees_minor
• payment_processing_fees_minor
• shipping_cost_minor
• taxes_minor
• other_fees_minor
• buyer_name
• buyer_contact
• notes
• created_by
• created_at
• updated_at

sale_items:

• id
• sale_id
• inventory_item_id
• sold_price_minor
• cost_basis_minor

Activity

Activity records retain:

• affected Product/Inventory Item
• event
• previous value where applicable
• new value
• actor
• timestamp

Security events are stored separately.

Money

Store money as integer minor units. Negative values are prohibited; zero is valid. USD is canonical for stored/calculated market values unless a documented external representation requires another currency.