FreeEed Viewer — portable packaged web app (viewer mode + notes round-trip)

[markkerzner]

FreeEed Viewer — portable packaged web app for search/display + notes round-trip

The FreeEed Viewer is the FreeEedUI web app with viewer-mode changes, packaged as a portable web app. It runs from a thumb drive as a per-OS launcher (Windows .exe) — no install, offline. It does no processing and no tagging/redaction authoring; it offers search + document display + add/edit notes. It loads a finished production (created in FreeEedUI per FreeEedUI#61, ESI format #551) and its notes sync back into the FreeEedUI review case DB.

Lifecycle

1. FreeEed (workstation) processes data → loads it into FreeEedUI (today's flow).
2. FreeEedUI review: the lawyer tags documents (Responsive, Privileged, …) and produces a production (FreeEedUI#61 → Implement standard eDiscovery (ESI) production format (TIFF + text + metadata + load files) #551). The production carries the review notes.
3. Viewer pack (portable web app + produced set + notes) goes out — to court, to an attorney / investigator / paralegal, on a thumb drive.
4. Viewer: the user searches, reads, and adds/edits notes (no processing).
5. Sync-back: the returned notes are folded into the FreeEedUI review case DB.

The one writable artifact that round-trips is notes (a notes overlay). The production stays immutable.

Decisions

• Codebase: the FreeEedUI web app with viewer-mode changes. Same codebase, not a separate build, not the Swing app. Viewer mode is read-only — search + display + notes; processing and tagging/redaction authoring are disabled.
• Deployment: portable packaged web app on a thumb drive. Bundled web server (Tomcat) + bundled JRE + the war in viewer mode + a bundled search index/engine, started by a per-OS launcher (Windows .exe) that brings up the local server and opens the browser. No install, runs offline. Reuses the existing complete-pack packaging machinery (release_freeeed_complete.sh, NSIS/makeself); the Viewer pack is essentially a trimmed complete-pack in viewer mode + a launcher.
• Search: bundle Solr in the pack. Reuse the complete-pack's Solr (no new search code, keeps the Viewer "the same as FreeEedUI"); no embedded Lucene.
• Production engine: FreeEedUI drives the FreeEed production engine; assembly is not reimplemented (FreeEedUI#61).
• Activation gate (Build a relationship with our users: free registration, feedback, and updates (not licensing) #549): inherited-activation stamp. The gate lives only in the Swing FreeEed app today; FreeEedUI is ungated. Forward-looking: the export step stamps manifest.json with the producer's registered email + activation key; viewer mode never prompts and, if a gate is ever added, verifies that stamp offline via the verify-only Activation.isValid (Ed25519; the public verify-only key/class can be ported into FreeEedUI). Keeps Build a relationship with our users: free registration, feedback, and updates (not licensing) #549's intent (every use traces to a registered relationship — the producer's) with no new crypto.
• Sync-back conflict policy: non-destructive append/union; never silent overwrite; true divergences flagged for manual resolution; idempotent by note id. Notes coexist, attributed and timestamped.
  • A note is a record: (noteId, bates, caseId, author, source[viewer|review], createdAt, text, supersedesId?) — not a single mutable field. (Notes-overlay schema implication.)
  • Sync-back unions by noteId → idempotent re-import; multiple returned drives merge.
  • Edits create a new record with supersedesId (history preserved), never mutate in place.
  • True conflicts (two revisions of the same base note from different sources) are not auto-resolved — surfaced for manual resolution, both retained, choice written to the import audit log.

Implementation slices

1. Viewer mode (FreeEedUI) — viewer-mode changes to the web app: read-only (no processing, no tagging/redaction authoring), exposes search + display + notes. Never calls the activation prompt; verifies the manifest stamp offline.
2. Export a Viewer bundle (FreeEedUI) — package a produced set (FreeEedUI#61 / Implement standard eDiscovery (ESI) production format (TIFF + text + metadata + load files) #551) + the current notes overlay + manifest.json (schema version + caseId + producer activation stamp) + the search index.
3. Notes overlay (FreeEedUI) — add/edit notes in viewer mode, persisted as attributed/timestamped note records keyed by Bates + caseId; the production stays immutable.
4. Sync-back (FreeEedUI) — "Import Viewer notes" unions a returned overlay into the review case DB by noteId: idempotent, multi-source merge, manual resolution for true conflicts, import audit log.
5. Portable packaging (FreeEed release tooling) — build the per-OS Viewer pack: bundled Tomcat + Solr + JRE + viewer-mode war + search index + a launcher (.exe on Windows). Trimmed variant of the complete-pack machinery.

Repo placement

• App changes (slices 1–4): FreeEed Viewer — app-side implementation (viewer mode + bundle export + notes sync-back) FreeEedUI#70.
• Packaging/distribution (slice 5): this repo (FreeEed release tooling).
• This issue is the cross-cutting tracker (with use case FreeEed Viewer: portable production viewer with search and note-taking #550).

Out of scope (MVP)

• Processing — the Viewer never processes; it only consumes a finished production.
• Tagging / redaction authoring — done during review before production (tags: FreeEedUI; redaction authoring: FreeEedUI#69). The notes overlay schema stays extensible so a future version could carry redactions authored in the Viewer.

Forensic soundness

The Viewer makes no outbound calls and works fully offline. Sync-back is a returned file/bundle, not a live network sync.

Acceptance (MVP)

• FreeEedUI runs in a read-only viewer mode (search + display + notes; no processing/authoring)
• FreeEedUI can export a self-contained Viewer bundle (produced set + notes overlay + manifest with activation stamp + index)
• The Viewer pack runs from a thumb drive via a launcher (.exe on Windows) — no install, offline
• User can add/edit notes, persisted as attributed/timestamped note records (production immutable)
• FreeEedUI can import a returned overlay and union notes into the review case DB — idempotent, multi-source, manual conflict resolution, with an audit log
• Viewer mode does not prompt for registration/activation; verifies the manifest stamp offline (Build a relationship with our users: free registration, feedback, and updates (not licensing) #549)
• No outbound calls anywhere in the Viewer

References

• Use case: FreeEed Viewer: portable production viewer with search and note-taking #550
• Production (creates the produced set the Viewer ships): FreeEedUI#61
• Production format: Implement standard eDiscovery (ESI) production format (TIFF + text + metadata + load files) #551 / docs/specs/esi-production-format.md
• Gate exemption: Build a relationship with our users: free registration, feedback, and updates (not licensing) #549
• Redaction (future overlay extension): FreeEedUI#69
• App-side implementation: FreeEedUI#70

[markkerzner]

Implementation companion filed in the FreeEedUI repo: shmsoft/FreeEedUI#70 (carries the settled decisions, the notes-overlay schema, and the 4 work-item slices).

[markkerzner]

Production-engine entry point (the Viewer bundle's produced set depends on it) filed: #556.