Image Everything

Native work stays private

The repository began in February as a Next.js scaffold. The first tools arrived in May 2026, one phase at a time: metadata, cleaning, compression, resize, conversion and transforms. The Nest backend that grew out of them carried its own Sharp engine in backend/src/lib/engine.ts. That put native decoding on the same event loop as the public HTTP work. By September the active routes already forwarded to a worker, yet the dead engines and their native dependencies still shipped in the API. I deleted them and made the separation a CI failure rather than a habit. pnpm check:boundaries parses the gateway, console and contract sources with the TypeScript compiler. It fails on any import of sharp, exifr, heic-decode, archiver, canvas, jimp, gm or imagemagick.

One registry, three consumers

packages/image-contracts/ is the source of truth. TOOL_IDS lists the 57 tools, and V2_ROUTE_REGISTRY turns them into 58 POST routes, since comparison has a JSON route and an image difference route. Each route records a public path under /api/v2/images, a worker path under /v2, an input kind and a result kind. Inputs are single, single-overlay, multiple or compare, and results are an image, JSON or a ZIP. getToolOptionsSchema validates options in the gateway, again in the worker, and parses each tool’s defaults in web/lib/tools/manifest.ts. web/app/[tool]/page.tsx serves each tool at its own URL, and the console calls the public API exactly as a script would.

Gateway and worker

The Nest gateway checks an optional bearer key, rate limits at 120 requests a minute by default, and enforces upload limits. It validates options, then forwards files over authenticated multipart to the worker on port 3020. The worker is a plain node:http server, split into src/core/ operations and src/http/ transport. sniffImageFormat reads magic bytes instead of trusting a filename or a MIME type. Inputs decode under pixel limits, and animated or multi-page files are rejected rather than flattened. HEIC goes through a heic-decode fallback. The worker admits two active requests by default and answers the rest with a retryable 503 before buffering anything. Readiness probes the installed Sharp runtime and fails when a baseline codec is missing.

A pipeline request

curl -H "Authorization: Bearer $API_KEY" \
  http://localhost:3001/api/v2/images/process \
  -F [email protected] \
  -F 'options={"steps":[{"op":"resize","options":{"width":800}},{"op":"filter","options":{"kind":"grayscale"}}],"output":{"format":"webp","quality":80}}' \
  -o processed.webp

Every processing route takes multipart: file plus JSON in options. Multi-image tools use files, comparison uses file and other, and image watermarks add overlay. A pipeline accepts up to 20 steps drawn from fourteen pixel-safe operations, with encoding as a terminal setting. Image results carry X-Output-Width and X-Output-Height headers. Failures are application/problem+json with a stable code: 413 for limits, 415 for codecs, 422 for corrupt or animated input, 503 when the worker is full. GET /api/v2/capabilities reports which codecs this deployment actually has.

Decisions and costs

• Run all 57 tools in one worker. They share Sharp, libvips and the HEIC fallback, so a container per operation would repeat the runtime without adding an isolation boundary. OCR or background removal would need a second worker.
• Keep requests synchronous and stateless. Uploads and results live in memory for one request and are never stored. The cost is a 30 second worker deadline by default, and a chained operation resends the image.
• Assert decoded content, not encoder bytes. Tests check dimensions, formats, metadata and representative pixels, because encoder output varies across libvips builds. Headless Chrome drives three representative tools rather than one flow per tool.
• Keep the 24 advanced tools out of pipelines. Duotone after a resize takes two requests and two uploads, and that is the decision I would revisit.

Scope and limits

The scope is still images, and the README says so. Animated editing, SVG, RAW, PSD, PDF, video, OCR, AI background removal, neural upscaling, asynchronous jobs, accounts and billing are explicitly deferred. Files cap at 25 MiB each and 100 MiB together, and pixel effects preflight a 25 MiB RGBA buffer. The API key is optional, and any NEXT_PUBLIC_API_KEY ships in browser JavaScript, so it is never a secret. The published Compose file runs the API and worker, while the console needs the source build. IMAGE_TAG=sha-<full-commit> pins both images to one build. pnpm smoke drives production builds through all 58 routes and re-decodes the results. It is MIT licensed.