Xompress — Portfolio PDF Compressor

Design portfolios routinely blow past application upload limits — my real samples ran 33 to 99MB against 10MB caps. Xompress is a web app that compresses a PDF to a user-chosen target size while protecting what matters: instead of squashing the file as a blob, it dissects every page into raster and vector elements, plans per-element compression with a pure-function decision engine, executes the plan, surgically reassembles the original PDF in place, and iterates until the output fits under the target. Text layers, transparency, and vector line work survive untouched. The system was built end-to-end in 15 verifiable phases — data contracts first, every stage a testable module — and ships as a live web app backed by an async REST API.

• Target-size compression with a convergence loop

  Pick a target (5/10/15/20MB); a one-dimensional search over a global aggressiveness parameter re-plans and re-runs until the output lands under the cap — real samples went 60.5→5.2MB, 75.9→8.3MB, 33.3→5.3MB.

• Pure-function decision engine with an honest cost guard

  Per-element plans (JPEG quality, DPI, vector simplify/rasterize) are computed from a config-driven cost model. A cost guard computes the incompressible floor first and rejects impossible targets with TARGET_TOO_SMALL instead of silently producing garbage.

• In-place surgery reassembly

  Compressed image streams are swapped by xref into a copy of the source PDF rather than redrawing pages — text layers (even fonts without ToUnicode maps), annotations, and layout survive byte-identical.

• Shared-stream deduplication

  Images referenced on many pages are detected by content, compressed once, and re-linked everywhere: one 99MB sample collapsed 12,573 image placements into 749 actual compressions.

• Transparency-safe pipeline

  Alpha is typed three ways (none/opaque/translucent); base images are re-encoded as JPEG while SMask references are preserved intact, so transparency and compression stay fully decoupled.

• Review checkpoint before final assembly

  The pipeline pauses at a review breakpoint; the web UI shows a page-preview grid so the user can inspect quality before committing, with tier warnings and actionable error messages throughout.

A PDF is never compressed as a blob — it is dissected, planned, executed, and reassembled. Eight pipeline stages hand typed data contracts to each other, every threshold lives in config, and an orchestrating state machine loops the whole thing until the file fits the target.

1. 1

   Split & Extract

   The PDF is split into per-page documents (with encryption/corruption detection and single-page fault tolerance); every raster and vector element is extracted with three-state alpha typing and content-deduplicated stream references.

2. 2

   Classify & Preprocess

   A heuristic classifier tags each page (all nine thresholds config-driven); font subsetting and fixed-overhead measurement establish the incompressible floor the budget math depends on.

3. 3

   Decide

   The pure-function engine allocates a raster budget (target minus fixed overhead, vector plans, and skipped pages), assigns per-element JPEG quality and DPI, and lets the cost guard reject infeasible targets honestly.

4. 4

   Compress

   Deduplicated streams are re-encoded once each with never-upscale fallback; a circuit breaker aborts the run if the success rate drops below 80%.

5. 5

   Assemble — In-Place Surgery

   Compressed streams are swapped into the source PDF by xref with SMask/Mask references preserved; text layers and page structure are never redrawn.

6. 6

   Converge & Deliver

   The orchestrator measures the real output size, steps the global aggressiveness, and re-runs until the target is met; results flow through the review checkpoint to the Next.js frontend via the REST API.