petrifiedsage/origo

Purpose and Runtime Model

Origo is an archived, browser-only research application for analyzing Google Takeout media/JSON sidecars and optionally restoring metadata into local media files. It has no backend or uploads: Next.js/React runs the UI, while Web Workers execute WebAssembly-backed ExifTool/ZeroPerl. The application entry point is src/app/page.tsx, within the Next.js shell in src/app/layout.tsx.

User Workflow and UI Orchestration

The page coordinates local directory/file selection, scan execution, results display, metadata-writing actions, and downloads. UI is decomposed into workflow-facing panels rather than server routes: src/components/DropZone.tsx, src/components/ResultsTable.tsx, and src/components/DownloadPanel.tsx. Browser File System Access APIs are the boundary for reading source exports and writing processed outputs locally.

Takeout Discovery Pipeline

The scanner recursively traverses selected Takeout content and identifies media plus sidecar JSON candidates. src/lib/scanner.ts produces the input inventory consumed by the matching and analysis stages. This boundary isolates browser filesystem traversal from Takeout-specific interpretation.

Sidecar Correlation and Analysis

Media files are deterministically paired with their Google supplemental metadata sidecars, then parsed and normalized into application-level records. Core stages are src/lib/matcher.ts, src/lib/parser.ts, and src/lib/normalizer.ts. src/lib/jsonAnalyzer.ts and src/lib/matcherDebugger.ts support format investigation and explainability for ambiguous or unexpected Takeout layouts.

Metadata Transformation and Reporting

Parsed Takeout metadata is mapped into tags suitable for writing to EXIF/QuickTime-capable files. src/lib/mapper.ts defines that translation boundary; shared processing/result shapes are in src/lib/types.ts. Outcomes are summarized and exported through src/lib/report.ts and src/lib/exporter.ts, separating analysis artifacts from binary media modification.

Browser Metadata Writing Boundary

The application-facing metadata writer dispatches work to a browser worker, avoiding UI-thread blocking and transferring binary data efficiently. Relevant paths are src/lib/writer.ts and src/workers/exiftool-worker.ts. This is the boundary between the Takeout pipeline and the reusable ExifTool runtime; supported research targets include JPEG, HEIC, and MP4.

Reusable origo-exiftool Engine

packages/origo-exiftool encapsulates WebAssembly ExifTool execution rather than exposing its internals to the app. Its public surface is packages/origo-exiftool/src/index.ts; packages/origo-exiftool/src/pool/WorkerPool.ts and packages/origo-exiftool/src/pool/ScheduledWorkerPool.ts provide persistent, scheduled worker concurrency and progress-aware batch processing. Worker-side execution lives in packages/origo-exiftool/src/worker/exiftool-worker.ts.

ZeroPerl/WASM Execution Infrastructure

The engine hosts ExifTool through ZeroPerl and a worker-local filesystem abstraction, keeping Perl/WASM state off the main thread. Core integration paths are packages/origo-exiftool/src/zeroperl/zeroperl.ts, packages/origo-exiftool/src/zeroperl/exiftool.ts, and packages/origo-exiftool/src/zeroperl/filesystem.ts. WASM assets are prepared for browser delivery by scripts/copy-wasm.mjs; the material external dependency is ExifTool running through ZeroPerl/WebAssembly, not a remote service.