CatalogMetrix Mini

Product catalog enrichment tool for e-commerce. Import CSV, enrich titles/descriptions, validate completeness, export marketplace-ready files.

---

Overview

CatalogMetrix Mini is a lightweight product catalog enrichment tool designed for e-commerce teams. It helps you:

• Import product data from CSV files with auto-column detection
• Enrich product titles and descriptions using template-based rules
• Validate completeness per marketplace channel
• Export marketplace-ready CSV files for Shopify, Magento, and WooCommerce

No external AI APIs are used. All enrichment is performed using template-based generation with keyword expansion, abbreviation maps, and SEO templates.

---

Features

CSV Import with Auto-Detection

Upload any product CSV file and CatalogMetrix will automatically detect column mappings. Supports various naming conventions:

Your Column	Detected As
Product Name, Title, Item Name	title
Description, Body HTML, Desc	description
Price, Retail Price, Unit Price	price
SKU, Product Code, Article Number	sku
Category, Product Type, Department	category
And many more...	Auto-mapped

Template-Based Enrichment

Enrich product data without any external API calls:

• Abbreviation Expansion: Blk Ctn T-Sht M becomes Black Cotton T-Shirt - Medium
• Description Generation: Create structured descriptions with bullet points from product title and category
• SEO Meta Tags: Auto-generate meta titles (60 chars) and meta descriptions (160 chars)
• Keyword Insertion: Add category-relevant SEO keywords

Completeness Scoring

Each product gets a completeness score based on required fields per marketplace channel:

Channel	Required Fields
Shopify	title, description, price, sku, weight, category, image_url
Magento	title, description, price, sku, weight, category, image_url, meta_title, meta_description
WooCommerce	title, description, price, sku, category, image_url

Scores are displayed as color-coded badges:

• Green (90%+): Complete
• Yellow (60-89%): Partial
• Red (<60%): Incomplete

Before/After Diff View

Review enrichment changes with a side-by-side diff view showing:

• Original vs. enriched title
• Original vs. enriched description
• Generated meta title and description
• Accept or reject changes per product

Multi-Channel Export

Export your catalog to marketplace-specific CSV formats:

• Shopify: Handle, Title, Body (HTML), Variant SKU, Variant Price, etc.
• Magento: sku, name, description, meta_title, meta_description, etc.
• WooCommerce: SKU, Name, Description, Regular price, Categories, etc.

---

Tech Stack

Component	Technology
Backend	FastAPI (Python 3.10+)
Frontend	React-style SPA (vanilla JS)
Database	SQLite with SQLAlchemy ORM
Enrichment	Template-based (no external AI)
Testing	pytest with httpx TestClient

---

Quick Start

Prerequisites

• Python 3.10 or higher
• pip

Installation

# Clone the repository
git clone https://github.com/your-org/catalogmetrix-mini.git
cd catalogmetrix-mini

# Create virtual environment
python -m venv venv
source venv/bin/activate  # or venv\Scripts\activate on Windows

# Install dependencies
pip install -r requirements.txt

Run the Application

# Start the server
uvicorn app:app --host 0.0.0.0 --port 8030 --reload

# Or use the start script
chmod +x start.sh
./start.sh

Open your browser at http://localhost:8030

Run with Docker

# Build and run
docker-compose up --build

# Or just Docker
docker build -t catalogmetrix-mini .
docker run -p 8030:8030 catalogmetrix-mini

---

API Reference

Health Check

GET /api/health

Returns application health status and basic statistics.

Import

POST /api/import/csv
Content-Type: multipart/form-data
Body: file=<CSV file>

Import products from a CSV file. Returns import statistics and column mapping.

Products

GET /api/products?page=1&page_size=25&search=&category=&enrichment_status=
GET /api/products/{id}

List and retrieve products with filtering and pagination.

Enrichment

POST /api/enrich/{id}          # Enrich single product
POST /api/enrich/batch          # Enrich all pending products
POST /api/products/{id}/accept-enrichment
POST /api/products/{id}/reject-enrichment

Validation

GET /api/validate/{id}

Validate product completeness across all marketplace channels.

Export

POST /api/export
Content-Type: application/json
Body: {"channel": "shopify", "use_enriched": true}

Export products to a channel-specific CSV format. Returns a downloadable CSV file.

Supported channels: shopify, magento, woocommerce

Import History

GET /api/imports?page=1&page_size=25
GET /api/imports/{id}

Statistics

GET /api/stats
GET /api/channels

---

Project Structure

catalogmetrix-mini/
├── app.py                    # FastAPI application entry point
├── config.py                 # Application configuration
├── requirements.txt          # Python dependencies
├── README.md                 # This file
├── Dockerfile                # Docker build file
├── docker-compose.yml        # Docker Compose configuration
├── start.sh                  # Start script
├── LICENSE                   # MIT License
├── .gitignore                # Git ignore rules
├── .github/
│   └── workflows/
│       └── ci.yml            # GitHub Actions CI
├── models/
│   ├── __init__.py           # Models package
│   ├── database.py           # SQLAlchemy models
│   └── schemas.py            # Pydantic schemas
├── routes/
│   ├── __init__.py           # Routes package
│   ├── api.py                # JSON API endpoints
│   └── views.py              # HTML view routes
├── services/
│   ├── __init__.py           # Services package
│   ├── csv_parser.py         # CSV parsing with auto-detection
│   ├── enricher.py           # Template-based enrichment
│   └── exporter.py           # Multi-channel CSV export
├── frontend/
│   ├── index.html            # SPA entry point
│   └── static/
│       ├── css/
│       │   └── app.css       # Application styles
│       └── js/
│           └── app.js        # SPA JavaScript
├── tests/
│   ├── conftest.py           # Shared test fixtures
│   ├── test_api.py           # API endpoint tests
│   ├── test_models.py        # Database model tests
│   ├── test_services.py      # Service integration tests
│   ├── test_csv_parser.py    # CSV parser unit tests
│   ├── test_enricher.py      # Enricher unit tests
│   └── test_exporter.py      # Exporter unit tests
└── seed_data/
    ├── data.json             # Seed data (25 products)
    └── sample_catalog.csv    # Sample CSV for testing

---

Testing

# Run all tests
pytest tests/ -v

# Run with coverage
pytest tests/ -v --cov=. --cov-report=term-missing

# Run specific test file
pytest tests/test_enricher.py -v

# Run specific test
pytest tests/test_api.py::test_enrich_product -v

---

Configuration

Environment variables:

Variable	Default	Description
CATALOGMETRIX_PORT	8030	Server port
CATALOGMETRIX_DEBUG	false	Enable debug mode
DATABASE_URL	sqlite:///instance/catalogmetrix.db	Database URL
SECRET_KEY	catalogmetrix-dev-key...	Application secret key
MAX_UPLOAD_SIZE_MB	50	Maximum CSV upload size

---

Enrichment Rules

Abbreviation Map (excerpt)

Abbreviation	Expansion
Blk	Black
Wht	White
Ctn	Cotton
Ply	Polyester
Lth	Leather
T-Sht	T-Shirt
Snkrs	Sneakers
Wrlss	Wireless
Bt	Bluetooth
Rchrgbl	Rechargeable
Prtbl	Portable
M / L / XL	Medium / Large / Extra Large

Category Keywords

Each category has associated SEO keywords that are automatically inserted during enrichment:

• Clothing: comfortable, stylish, everyday wear, machine washable
• Electronics: high performance, energy efficient, modern design
• Home: home decor, easy to clean, modern style
• Sports: athletic, high performance, moisture wicking
• Beauty: premium quality, skin friendly, long lasting
• Toys: educational, safe materials, age appropriate

---

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/my-feature)
3. Make your changes
4. Run tests (pytest tests/ -v)
5. Commit (git commit -am 'Add my feature')
6. Push (git push origin feature/my-feature)
7. Create a Pull Request

---

License

This project is licensed under the MIT License. See LICENSE for details.

---

Acknowledgments

• Built with FastAPI
• Database powered by SQLAlchemy
• Styled with custom CSS (no external frameworks)
• Template-based enrichment -- no external AI APIs required