privacy-tools/docs/ARCHITECTURE.md

Architecture

Privacy Tools is a relocatable Vite/React static application. The core domain model in src/privacy is serializable: scan inputs cross a worker boundary as transferred ArrayBuffers and results contain only strings, numbers, booleans, arrays, and plain objects. No parser returns HTML or a live third-party object.

Pipeline

1. scan-client checks file count and declared byte totals before reading the batch, transfers buffers to a dedicated worker, reports progress, and terminates the worker on cancellation.
2. detect compares magic bytes, filename extension, and browser-claimed MIME. scanner hashes bytes, dispatches the bounded project parser, runs ExifReader as a distinct secondary adapter, and normalizes findings and coverage.
3. Project parsers walk JPEG segments, PNG chunks, WebP RIFF chunks, TIFF IFDs, IPTC datasets, and bounded inert XMP text. They validate offsets, lengths, counts, PNG CRCs, compression expansion, TIFF cycles/depth, and trailing bytes. They do not follow URLs or instantiate XML/HTML.
4. sanitize runs only for complete, static, bounded JPEG/PNG/WebP scans. A browser decoder produces pixels, the EXIF display orientation is normalized, and Canvas creates a fresh same-format file. No input container block is copied.
5. The encoded bytes are passed back through the same independent scanner API, hashed, dimension-checked, and compared using a deterministic 256-pixel-edge decoded sample. buildSanitizationReport assigns verified/warning/failed based on explicit coverage and output findings.
6. archive serializes bounded deterministic JSON and creates stored ZIP entries from application-generated images/ paths. Safe-share archives use generic sequential image names and a reduced report; detailed reports remain an explicit, separate download for local auditing.
7. policy applies frozen, versioned category rules to normalized findings. It creates pseudonymous per-file evidence across every inventoried format and separately reports whether the requested removal can be executed by the existing verified re-encode path. New policy profiles can be added without changing a container parser.

Pixel decoding and Canvas encoding currently run on the main browser context because portable cross-browser image encoder support is there; metadata parsing and hashing run in the terminable worker. UI state does not retain data after a page refresh and no IndexedDB/localStorage persistence is used by this app.

Trust boundaries

• Project parsers and ExifReader independently contribute coverage; one parser's success does not suppress the other's warning.
• Unknown structures are reported or cause partial coverage. Clean-copy eligibility requires a complete project container scan.
• Browser image decoders, Canvas encoders, Web Crypto, and the JS runtime are in the trusted computing base.
• ExifReader is pinned to 4.44.0. Dependency updates require malformed-container regression fixtures and licence review.
• The Toolbox shell receives the application manifest but never receives file bytes or findings.