Product Image Auto Pack Generator

Automatically generates product image packs with watermarking, resizing, and format optimization for e-commerce channels.

Domain: E-commerce / Media

Note: All image processing is simulated. No actual image manipulation takes place -- the system generates metadata, transformation specifications, processing reports, and download manifests without any Pillow or binary image dependencies.

Features

Product Management

Register products with SKU, category, brand, and description
Attach image metadata (filename, dimensions, format, file size, DPI, color space, alpha channel, primary flag)
Product search and filtering

Channel Configurations

Pre-configured rules for Amazon, eBay, Shopify, Etsy, and Google Shopping
Per-channel image requirements: dimensions, format, max file size, background rules, DPI minimums
Per-channel watermark rules: position, opacity, size percentage
Custom channel creation and editing

Pack Generation

Select a product and target channels
System calculates all required transformations per image per channel
Generates detailed processing report
Creates download manifest (JSON) listing all output files
Status tracking: pending -> processing -> completed / failed

Processing Specifications

Source-to-target dimension mapping with resize detection
Aspect ratio analysis and crop strategy (center, smart)
Format conversion detection (e.g., PNG -> JPEG for Amazon)
Background change requirements (white, transparent, natural)
Watermark placement instructions
Estimated output file size calculation

Batch Processing

Generate packs for multiple products in one request
Parallel spec generation across channels

Dashboard

Total products, images, packs, and channels
Recent pack history with status indicators
Job completion statistics

Architecture

Client (React SPA)
       |
       v
  FastAPI Server
       |
       v
  Services Layer
  |- PackBuilder      -- orchestrates pack generation
  |- ChannelRulesEngine -- validates & provides channel rules
       |
       v
  SQLAlchemy ORM
       |
       v
  SQLite Database

All image processing is simulated at the services layer. The PackBuilder generates transformation specs and processing reports without touching actual image files.

Tech Stack

Layer	Technology
Backend	FastAPI 0.109
Frontend	React-style SPA
Database	SQLite + SQLAlchemy
Testing	pytest + httpx
Container	Docker

Getting Started

Prerequisites

Python 3.10+
pip

Quick Start

# Clone the repository
git clone https://github.com/youruser/image-pack-generator.git
cd image-pack-generator

# Run with the start script
chmod +x start.sh
./start.sh

Or manually:

python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
uvicorn app:app --host 0.0.0.0 --port 8036 --reload

The application will be available at http://localhost:8036.

Docker

docker-compose up --build

API Reference

Health

Method	Path	Description
GET	/api/health	Health check

Products

Method	Path	Description
POST	/api/products	Create product
GET	/api/products	List products
GET	/api/products/{id}	Get product
POST	/api/products/{id}/images	Register image metadata
GET	/api/products/{id}/images	List product images

Packs

Method	Path	Description
POST	/api/packs/generate	Generate image pack
POST	/api/packs/generate-batch	Batch generation
GET	/api/packs	List packs
GET	/api/packs/{id}	Get pack with manifest
GET	/api/packs/{id}/specs	Get pack specs
GET	/api/packs/{id}/report	Get processing report

Channels

Method	Path	Description
GET	/api/channels	List channel configs
POST	/api/channels	Create channel config
PUT	/api/channels/{id}	Update channel config

Jobs

Method	Path	Description
GET	/api/jobs	List processing jobs

Dashboard

Method	Path	Description
GET	/api/dashboard/stats	Dashboard statistics

Channel Configurations

Amazon

Dimensions: 1000x1000px
Format: JPEG
Background: Pure white (#FFFFFF)
Watermark: Not allowed
Max size: 10MB

eBay

Dimensions: 500x500px
Format: JPEG
Background: Any
Watermark: Bottom-right, 30% opacity, 15% size
Max size: 7MB

Shopify

Dimensions: 2048x2048px
Format: PNG
Background: Transparent
Watermark: Center, 15% opacity, 25% size
Max size: 20MB

Etsy

Dimensions: 2000x2000px
Format: JPEG
Background: Natural
Watermark: Bottom-left, 20% opacity, 12% size
Max size: 15MB

Google Shopping

Dimensions: 800x800px
Format: JPEG
Background: White
Watermark: Not allowed
Max size: 16MB

Pack Generation Workflow

Select Product -- choose a product with registered images
Select Channels -- pick target e-commerce channels
Preview Specs -- review calculated transformations
Generate -- system creates specs, simulates processing, produces manifest

Processing Report Example

For each image x channel combination, the report includes:

Source dimensions and format
Target dimensions and format
Whether resize/crop is needed
Crop strategy (center, smart)
Format conversion required
Background changes
Watermark placement
Estimated output file size
Output filename

Frontend SPA

The single-page application provides these views:

Route	Description
#/	Dashboard with stats and recent packs
#/products	Product grid with image counts
#/product/:id	Product detail with image gallery
#/generate	Pack generation wizard (4 steps)
#/packs	Generated pack history
#/pack/:id	Pack detail with specs and manifest
#/channels	Channel configuration table

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_pack_builder.py -v

The test suite includes 15+ tests covering:

API endpoints (products, images, packs, channels, jobs)
Database models
Pydantic schema validation
Pack builder service (spec generation, manifest, batch)
Channel rules engine (validation, transformation summaries)

Deployment

Docker Compose

docker-compose up -d --build

Manual

uvicorn app:app --host 0.0.0.0 --port 8036

Environment Variables

Variable	Default	Description
IPG_PORT	8036	Server port
IPG_DEBUG	false	Debug mode
DATABASE_URL	sqlite:///...	Database connection

Project Structure

image-pack-generator/
├── app.py                          # FastAPI entry point
├── config.py                       # Configuration
├── requirements.txt                # Python dependencies
├── Dockerfile                      # Container image
├── docker-compose.yml              # Container orchestration
├── start.sh                        # Start script
├── LICENSE                         # MIT License
├── .gitignore                      # Git ignore rules
├── .github/workflows/ci.yml        # CI pipeline
├── models/
│   ├── __init__.py                 # Model exports
│   ├── database.py                 # SQLite setup & seeding
│   └── schemas.py                  # ORM models & Pydantic schemas
├── routes/
│   ├── __init__.py                 # Route exports
│   ├── api.py                      # REST API endpoints
│   └── views.py                    # SPA view serving
├── services/
│   ├── __init__.py                 # Service exports
│   ├── pack_builder.py             # Pack generation orchestration
│   └── channel_rules.py            # Channel-specific rules engine
├── frontend/
│   ├── index.html                  # SPA entry page
│   └── static/
│       ├── css/app.css             # Stylesheet
│       └── js/app.js               # SPA JavaScript
├── tests/
│   ├── conftest.py                 # Test fixtures
│   ├── test_api.py                 # API endpoint tests
│   ├── test_models.py              # Model tests
│   ├── test_services.py            # Service tests
│   ├── test_channel_rules.py       # Channel rules tests
│   ├── test_pack_builder.py        # Pack builder tests
│   ├── test_schemas.py             # Schema validation tests
│   └── test_routes.py              # Route integration tests
└── seed_data/
    └── data.json                   # Sample products & channels

Contributing

Fork the repository
Create a feature branch (git checkout -b feature/amazing)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing)
Open a Pull Request

License

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

Name		Name	Last commit message	Last commit date
Latest commit History 10 Commits
.github/workflows		.github/workflows
frontend		frontend
models		models
routes		routes
seed_data		seed_data
services		services
tests		tests
.gitignore		.gitignore
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
app.py		app.py
config.py		config.py
docker-compose.yml		docker-compose.yml
requirements.txt		requirements.txt
start.sh		start.sh

Folders and files

Latest commit

History

Repository files navigation

Product Image Auto Pack Generator

Table of Contents

Features

Product Management

Channel Configurations

Pack Generation

Processing Specifications

Batch Processing

Dashboard

Architecture

Tech Stack

Getting Started

Prerequisites

Quick Start

Docker

API Reference

Health

Products

Packs

Channels

Jobs

Dashboard

Channel Configurations

Amazon

eBay

Shopify

Etsy

Google Shopping

Pack Generation Workflow

Processing Report Example

Frontend SPA

Testing

Deployment

Docker Compose

Manual

Environment Variables

Project Structure

Contributing

License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages