package-tools/public/docs/ARCHITECTURE.md

Architecture

The React workbench is a thin UI over four bounded layers:

1. src/archive validates ZIP metadata, paths, sizes, compression ratios and selected-entry extraction using zip.js without workers.
2. src/package/analyze.ts selects at most 512 metadata files / 16 MiB, determines a package adapter, parses static XML or bounded JSON, and builds references and diagnostics.
3. Tree and comparison modules create deterministic projections without reading entry payloads.
4. The preview path reopens the package and performs strict CRC/overlap checks for one bounded entry. Markup is text-only; only browser-supported raster image/audio/video blobs receive local object URLs.

The UI lazy-loads the workbench beneath the shared toolbox shell. The app uses relative URLs so it works under nested portal paths, and a service worker caches same-origin resources after first use.