productdb.json: Single Source of Truth for Product Data

This article explains how productdb serves as the single source of truth for all product data, defining components, features, compatibility rules, and bill of materials in one centralized file.

The Problem: Scattered Product Data

Product data can be scattered across multiple systems:

  • Inventory system: Part costs and stock levels

  • ERP system: BOMs and manufacturing data

  • Website: Product descriptions and specifications

  • Accounting: Pricing and costing rules

When data is scattered, inconsistencies arise:

  • Website shows 16GB RAM, but ERP says 8GB

  • Pricing uses old cost data

  • BOMs are out of sync with actual products

  • Features don't match reality

We need a single source of truth that all systems reference.

The Solution: productdb.json

productdb.json is a JSON file that defines every component, its features, compatibility rules, and constituents. All systems load this file at startup.

This file is version-controlled in Git, ensuring all changes are tracked and auditable.

File Structure

The file is organized by component category:

{
  "Chassis": { ... },
  "Board": { ... },
# ... (implementation details omitted)

Each category contains components with their properties.

Component Definition

Each component has multiple properties:

Basic Properties

class: Component class for compatibility matching

"class": "THIN_MINI_ITX"

internal: Internal name for inventory and manufacturing

"internal": "Chassis, Treo"

external: Customer-facing name for website and marketing

"external": "Thinvent® Treo Mini PC"

weight: Physical weight in grams

"weight": 590

Compatibility Rules (allows)

The allows field defines which components can be used together:

"allows": {
  "Board": [
    {"class": "THIN_MINI_ITX"}
# ... (implementation details omitted)

This means:

  • Board: Only boards with class THIN_MINI_ITX are compatible

  • Flash: Only flash storage with class m.2_SATA is compatible

  • Accessories: All accessories are compatible

Compatibility can be specified by:

Class-based (dynamic):

{"class": "THIN_MINI_ITX"}

Part ID-based (explicit):

["N100", "N150", "i5-1335U"]

Bill of Materials (constituents)

The constituents field defines what parts make up this component:

"constituents": [
  {
    "Category": "Custom",
# ... (implementation details omitted)

This enables:

  • Cost calculation: Sum costs of all constituents

  • Manufacturing: Generate pick lists for assembly

  • Inventory: Track component usage

Feature Provision (provides)

The provides field defines features this component contributes:

"provides": {
  "Operating Temperature": "0°C ~ 40°C",
  "Operating Humidity": "20% ~ 80% RH, non condensing",
# ... (implementation details omitted)

These features are aggregated across all components in a SKU to create the product's complete specification.

Example: Treo Chassis

{
  "Treo": {
    "class": "THIN_MINI_ITX",
# ... (implementation details omitted)

Example: N100 Board

{
  "N100": {
    "class": "THIN_MINI_ITX",
# ... (implementation details omitted)

Loading productdb.json

The file is loaded at application startup:

import json

with open(PRODUCTDB_JSON_PATH, "r", encoding="utf-8") as productdb_file:
    productdb = json.load(productdb_file)

This creates an in-memory dictionary:

productdb = {
    "Chassis": {
        "Treo": { ... },
# ... (implementation details omitted)

All code references this dictionary for product data.

Accessing Component Data

Get Component by Category and ID

chassis = productdb["Chassis"]["Treo"]
board = productdb["Board"]["N100"]
ram = productdb["RAM"]["8"]

Get External Name

name = productdb["Board"]["N100"]["external"]
# Result: "Intel® N100 Processor"

Get Features

features = productdb["Board"]["N100"]["provides"]
# Result: {"Generation": "12th", "Series": "N", ...}

Get Constituents

constituents = productdb["Chassis"]["Treo"]["constituents"]
# Result: [{"Category": "Custom", "PartID": "base_treo", "qty": 1}, ...]

SKU Validation

We use productdb.json to validate SKUs:

def check_sku(sku:str) -> bool:
    parts = sku.split("-")
    mapped_parts = map_parts_to_fields(parts)
# ... (implementation details omitted)

See SKU Structure for details.

Feature Aggregation

We aggregate features from all components in a SKU:

def get_product_features(sku: str) -> dict:
    partids = sku.split("-")
    features = {}
# ... (implementation details omitted)

Example:

SKU: Treo-N100-8-256-2H-W6-11P

Features:

- Form Factor: Mini PC (from Treo)

- Generation: 12th (from N100)

- Series: N (from N100)

- Cores: 4 (from N100)

- Main Memory: 8 (from 8)

- SSD Storage: 256 (from 256)

- HDMI: 2 (from 2H)

- Operating System: Windows 11 Pro (from 11P)

See Feature Extraction for details.

Cost Calculation

We calculate SKU cost by summing constituent costs:

def calculate_cost(item: dict, partid: str) -> tuple:
    if "constituents" in item:
        # Composite item: sum constituent costs
# ... (implementation details omitted)

This recursive calculation handles nested constituents.

Composite Items

Some components are composite (made of other components):

Example: Keyboard + Mouse combo

{
  "KM": {
    "internal": "Keyboard + Mouse",
# ... (implementation details omitted)

This enables:

  • BOM generation: List all components needed

  • Cost calculation: Sum costs of keyboard + mouse + dongle

  • Inventory tracking: Track component usage

Updating productdb.json

Manual Editing

The file is edited manually in a text editor or IDE. Changes are committed to Git:

git add PATH_TO_FILE/productdb.json
git commit -m "Add new N150 board configuration"
git push

Validation

After editing, validate the JSON syntax:

python -m json.tool PATH_TO_FILE/productdb.json > /dev/null

This checks for syntax errors.

Deployment

After pushing to Git, the file is deployed to production

The application reloads the file on restart.

Integration with Other Systems

Website

The website uses productdb.json to:

  • Generate product pages

  • Display specifications

  • Filter products by features

  • Generate comparison tables

ERP

The ERP uses productdb.json to:

  • Validate SKUs

  • Generate BOMs

  • Calculate costs

  • Track inventory

Accounting

Accounting uses productdb.json to:

  • Calculate product costs

  • Generate invoices

  • Track COGS (Cost of Goods Sold)

SEO Pipeline

The SEO pipeline uses productdb.json to:

See SEO Pipeline Overview for details.

Benefits of Single Source of Truth

1. Consistency

All systems use the same data. No discrepancies.

2. Maintainability

Update once, propagate everywhere. No need to update multiple systems.

3. Auditability

All changes are tracked in Git. Easy to see who changed what and when.

4. Testability

Changes can be tested in staging before production deployment.

5. Simplicity

One file to understand. No complex database schemas or APIs.

6. Performance

In-memory dictionary provides O(1) lookup. No database queries needed.

7. Portability

JSON is human-readable and language-agnostic. Easy to parse in any language.

Limitations

1. Manual Editing

Changes require manual editing and Git commits. No web UI for non-technical users.

2. Restart Required

Application must restart to load changes. No hot-reload.

3. No Validation

JSON syntax is validated, but semantic validation (e.g., "does this part exist?") is not automatic.

4. Concurrency

Multiple people editing simultaneously can cause merge conflicts.

References

Technical Concepts

Related Articles

Summary

productdb.json is the single source of truth for all product data:

Structure:

  • Organized by component category (Chassis, Board, RAM, etc.)

  • Each component has properties (class, internal, external, weight)

  • Compatibility rules (allows)

  • Bill of materials (constituents)

  • Feature provision (provides)

Benefits:

  • Consistency across all systems

  • Maintainability (update once)

  • Auditability (Git tracking)

  • Testability (staging deployment)

  • Simplicity (one file)

  • Performance (in-memory O(1) lookup)

  • Portability (JSON format)

Use Cases:

  • SKU validation

  • Feature aggregation

  • Cost calculation

  • BOM generation

  • Website product pages

  • SEO pipeline feature extraction

This centralized approach ensures all systems reference the same product data, eliminating inconsistencies and simplifying maintenance.

← Back to Documentation Index