office-tools/public/docs/ARCHITECTURE.md

Architecture

Office Tools is a static React application with four deliberately separated layers:

1. The Toolbox shell owns navigation, application identity, theme preferences, help and source links.
2. The ingestion boundary checks extension, source size and an eight-byte signature; renamed OLE/RTF and non-ZIP inputs fail with clear diagnostics. Each parser then validates package identity and enforces resource limits.
3. Format adapters convert office packages into one application-owned, read-only document model.
4. Viewer components render that model as document pages, spreadsheet sheets or presentation slides without trusting imported markup.

The original File is immutable. “Save exact copy” passes that Blob directly to the shared download helper, so there is no parse/rebuild round trip. Opening a new file cancels obsolete work and releases prior buffers and object URLs. Expensive parsing belongs in a module worker so the shell stays responsive and cancellation has a clear boundary.

Office Open XML input uses the pinned @silurus/ooxml Rust/WebAssembly parser and Canvas renderer. OpenDocument input uses project-owned TypeScript adapters over fflate and @xmldom/xmldom; it is not routed through an online converter. The adapters share detection, size-policy and diagnostics contracts while retaining their intentionally different rendering paths.

The OpenDocument module worker verifies central and local ZIP declarations, normalized paths, CRC and expansion limits before namespace-aware XML parsing. It rejects DTDs, entities, external resources and active XML, and returns only a typed, serializable model plus transferable packaged image buffers.

The semantic ODF adapter retains default/named style inheritance, page geometry, spreadsheet row/column defaults and visibility, drawing transforms, comments, notes and active-content notices. Derived text, CSV, outline and JSON inspection exports are bounded and labelled separately from the byte-exact source path.

Deployment contract

Vite emits relative URLs (base: './'). toolbox-app.json sits beside index.html, and the application works with or without a same-origin Toolbox catalogue. toolbox-check dist verifies manifest identity, files and nested-path operation. The service worker handles requests only inside its own scope.

Rendering contract

The OpenDocument model records source kind, ordered blocks/sheets/slides, text runs, whitelisted style data, tables, local images, notes and diagnostics. ODS keeps source repeats compressed, trims office-suite full-grid tails and renders at most 200 rows per page and 256 columns. Adapters emit warnings for omitted embedded objects and other approximations. Source markup is never inserted as HTML, formulas are never evaluated, and document URLs are never fetched.