Architecture

Picture Optimizer uses a three-tier architecture where each component has a distinct responsibility.

System Overview

Components

WordPress Plugin

The plugin lives inside your WordPress installation and provides:

• Media Library integration — Process buttons on every image, bulk actions for batch processing
• Modal workflow UI — Step-by-step wizard for selecting pipeline mode, reviewing AI results, configuring export settings, and previewing samples
• File replacement — Downloads processed images from the API, replaces the original attachment, regenerates thumbnails, and updates all URL references across the site
• Revert system — Backs up every original file before replacement and supports one-click revert

The plugin communicates exclusively with the Flask API Gateway. It never contacts the SaaS platform directly.

Flask API Gateway

The gateway is a lightweight Flask application that acts as the authenticated entry point:

• API key validation — Every request from the WordPress plugin includes an API key. The gateway validates it before proxying.
• Credit enforcement — Before billable operations (analyze, export), the gateway checks the user's credit balance and pre-deducts credits. If insufficient, it returns a 402 error.
• Request proxying — Valid requests are forwarded to the SaaS platform's internal API endpoints, including SSE (Server-Sent Events) streams for real-time progress.
• Header forwarding — The X-API-Key header is passed through to the SaaS platform so it can resolve the user.

SaaS Platform (Next.js)

The SaaS platform is a Next.js application that provides:

• AI analysis engine — Sends images to a vision AI model (via OpenRouter) and parses structured metadata responses
• Image processing pipeline — Uses Sharp/libvips for compression, format conversion, resizing, and EXIF metadata writing
• User accounts & billing — Manages user registration, subscription plans, credit balances, and usage history
• API key management — Users generate API keys from their dashboard to connect their WordPress plugin
• Session management — Each processing batch creates a session that tracks uploaded images, analysis results, and exported files

Request Flow

Full Pipeline (Analyze & Export)

1. Upload — Plugin uploads images to Flask → SaaS creates a session and stores files
2. Credit check — Flask calls /api/credits/check to verify the user has enough credits, then deducts
3. Analyze — Flask proxies to SaaS /api/openrouter/analyze → SaaS sends images to AI → streams SSE progress events back
4. Review — User reviews and edits AI-generated metadata in the plugin modal
5. Export — Flask checks credits again, proxies to SaaS /api/export → SaaS compresses/converts images → streams SSE progress
6. Replace — Plugin downloads processed files, replaces WordPress attachments, updates URLs across the database

Analyze Only

Steps 1–4 from above, then the plugin applies metadata to WordPress attachment fields (title, alt, caption) without replacing the file.

Compress & Export Only

Steps 1, 2, 5, 6 — skips AI analysis entirely. Uses the original filename with the chosen export format.

Data Flow Diagram

WordPress Media Library
    │
    ▼
┌─────────────────────────┐
│   WordPress Plugin      │
│   (PHP + JS)            │
│                         │
│  ┌───────────────────┐  │
│  │ Modal UI          │  │
│  │ Upload → Analyze  │  │
│  │ Review → Export   │  │
│  │ Replace → Revert  │  │
│  └───────────────────┘  │
└────────────┬────────────┘
             │ HTTPS (API Key)
             ▼
┌─────────────────────────┐
│   Flask API Gateway     │
│   (Python)              │
│                         │
│  • Validate API key     │
│  • Check/deduct credits │
│  • Proxy requests       │
│  • Stream SSE events    │
└────────────┬────────────┘
             │ Internal HTTP
             ▼
┌─────────────────────────┐
│   SaaS Platform         │
│   (Next.js)             │
│                         │
│  • AI vision analysis   │
│  • Image compression    │
│  • EXIF writing         │
│  • Session management   │
│  • User accounts        │
│  • Credit billing       │
└─────────────────────────┘

Port Configuration