package-tools/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 comparison first reports metadata-only candidates as unverified. On an explicit user action it reopens up to 512 comparable entries within a 128 MiB expanded-byte budget, verifies container integrity and hashes decompressed bytes with SHA-256. Differing small JSON, static XML, manifest and text files receive bounded semantic summaries; DTDs/entities remain rejected.
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.

Supply-chain inspection is declaration-only: bounded package.json, requirements, Maven/JAR and conventional licence paths produce evidence rows without registry access, resolution, vulnerability lookup or legal inference. Signature inventory correlates companion .SF/.RSA/.DSA/.EC entries and reports declared digest algorithm names, but never verifies signed bytes or a certificate chain. Explicit entry handoff uses the browser's user-mediated Web Share surface; verified download is retained as the predictable fallback.

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.