Create a Standalone Python Image

[digitalrisedorset]

Summary

Create a self-contained Python service that exposes a reusable image optimisation API. The engine must be independent of ReactEdge and designed to integrate seamlessly with widgets, CDN providers, and commerce platforms such as Mage-OS.

Motivation

The image optimisation capability should become a reusable building block rather than a widget-specific implementation.

By isolating the optimisation logic behind a simple API, the same engine can be reused across multiple products and deployment models without duplicating business logic.

Objectives

• Build a lightweight Python service dedicated to image optimisation.
• Expose a stable API for requesting image optimisation.
• Keep the engine independent of ReactEdge, Mage-OS, or any specific platform.
• Make the engine suitable for both synchronous and asynchronous integrations.
• Provide a foundation for future approval workflows and optimisation pipelines.

Functional Requirements

The engine shall:

• Accept one or more image inputs.
• Validate supported image formats.
• Optimise images into configurable output formats.
• Store the generated assets in a configurable export location.
• Return the location and metadata of the generated assets.
• Handle optimisation failures gracefully.
• Be configurable without code changes.

API Design Principles

The API should:

• Be stateless.
• Be idempotent.
• Be transport agnostic where practical.
• Expose a small, stable interface.
• Be suitable for embedding behind a CDN or being consumed directly by applications.

Non-functional Requirements

• Self-contained deployment.
• Minimal runtime dependencies.
• Structured logging.
• Health endpoint.
• Configuration through environment variables.
• Unit and integration tests.
• Container-friendly deployment.

Out of Scope

• Widget integration.
• CDN integration.
• Mage-OS integration.
• Approval workflow.
• Notification pipeline.
• Metadata persistence.

These integrations will be implemented in subsequent issues.

Acceptance Criteria

• A standalone Python service can be started independently.
• The service exposes an image optimisation API.
• Images are successfully optimised and written to the configured output directory.
• The service can be invoked without any ReactEdge components.
• The API is documented for future consumers.
• The project structure supports future adapters for ReactEdge, CDN providers, and Mage-OS without modifying the optimisation engine.