Utils-tool
28 image, PDF, file and developer tools in one codebase that runs fully local or serverless — no database, no accounts, no cloud uploads.
- 28
- Tools
- 2
- Runtime environments
- 0
- Databases
- 0
- Accounts required
- Role
- Author
- Year
- 2026
- Status
- Live
- Type
- Local-first media utility suite
01Overview
Utils-tool is a suite of 28 tools for images, PDFs, files and developer assets: compression, background removal, format conversion, resizing, cropping, watermarking, PDF merge and split, favicon and SVG generation, QR and barcode generation, and more.
One codebase runs two ways — locally with the full feature set, or on Vercel as a serverless app. No database, no Redis, no accounts, no cloud uploads.
The design problem was that those two environments cannot do the same things. Ghostscript and rembg exist locally and do not exist in a serverless function.
02The problem
Online file tools ask you to upload private documents to a stranger's server. Local tools mean installing something. I wanted both from one codebase without maintaining two forks.
But feature parity is impossible: heavy native binaries and ML models run locally and cannot run serverless. Shipping a tool that appears in the UI and then fails at runtime is worse than not shipping it.
So the environment had to become something the code could reason about, rather than a deploy-time assumption.
03Architecture
- 01
Capability system
Every tool declares its runtime requirements. On boot the backend reports what the current environment actually supports, and the frontend shows, hides or disables each tool accordingly. A tool that cannot run is never offered.
- 02
Layered FastAPI backend
Routes → controllers (validation and HTTP) → services (the actual work) → repositories (persistence) → infrastructure adapters. All 28 tools follow the same path, so adding the twenty-ninth is mechanical.
- 03
Pluggable storage
A storage abstraction resolves to the local filesystem when running locally and to Vercel Blob when deployed. Nothing above it knows which.
- 04
Infrastructure adapters
rembg for background removal, Pillow for images, pikepdf and Ghostscript for PDFs, qrcode and python-barcode for generation, plus a ZIP adapter — each behind an interface, so an absent binary is a capability signal rather than a crash.
- 05
Secure upload pipeline
Magic-byte validation instead of trusting file extensions, hard size limits, and decompression-bomb protection — because the whole product is accepting arbitrary files from strangers.
- 06
Batch queue
Multi-file tools run through a shared queue with real per-file progress, not a spinner that resolves when everything finishes.
04Key decisions
Capabilities as data, not configuration
The alternative was environment flags in a config file, which drift the moment a dependency changes. Probing at runtime means the UI is never wrong about what the server can do.
No database at all
Files in, files out. Adding persistence would have meant accounts, retention policy and a privacy story. Statelessness is the feature.
Static frontend
Plain HTML, CSS and JS with a shared tool-kit module. Twenty-eight near-identical tool pages is exactly the case where a framework buys nothing and a template buys everything.
Magic-byte validation
Extension checks are trivially bypassed. Reading the header is a few lines and closes the entire class of upload-type confusion.
05Stack
- Python
- FastAPI
- Pillow
- pikepdf
- Ghostscript
- rembg
- Vercel Blob
- HTML/CSS/JS
- Ruff