Backend: File Management

Relevant source files

The following files were used as context for generating this wiki page:

• client/products/memotron/capture/capture.store.ts
• README.md
• WARP.md
• client/cx/contemporaries/notion.json
• client/cx/contemporaries/obsidian.json
• client/products/memotron/node/node.type.ts

The file management system in Nucleus is responsible for handling the capture, processing, and storage of user-generated content, including text, images, audio, and web clips. This system is designed to be robust, handling various file types and extracting relevant metadata to enrich the user's knowledge base. While the full backend implementation on Cloudflare (Workers, D1, R2) is planned for the future, the current architecture is heavily defined by the client-side implementation which prepares and sends files to the backend.

This document primarily details the client-side file management logic as implemented in the memotron product. It orchestrates all file capture operations, from handling user input to interacting with the backend storage service.

Sources: README.md:38-41, client/products/memotron/capture/capture.store.ts

Architecture Overview

The file management process begins on the client when a user initiates a capture action (e.g., uploading a file, taking a picture, recording audio). The ActiveCaptureStore class manages the state of the capture, processes the file, extracts metadata, and finally uses a service (abstracted as account.uploadFileV2) to upload the file to the backend. The backend is intended to be a cloud storage solution like Cloudflare R2.

The following diagram illustrates the high-level flow of a file capture operation.

Client-Side Orchestration: ActiveCaptureStore

The ActiveCaptureStore is the central component for handling all file and content capture on the client side. It manages the lifecycle of a capture session, from initiation to saving the final Node object and uploading the associated binary data.

Sources: client/products/memotron/capture/capture.store.ts:110-117

Key Responsibilities

Responsibility	Description	Key Methods
State Management	Manages the state of the current capture, including content, links, properties, and UI state.	constructor, init, reset, load
Capture Handling	Provides methods to save various types of content like files, audio, camera captures, and webpages.	saveFile, saveMultipleFiles, saveAudioRecording, saveCameraCapture, saveWebpage
Metadata Extraction	Parses metadata from files (e.g., EXIF from images, ID3 from audio) and resolves geolocation.	parseMetadata, resolveLocation
Backend Interaction	Abstractly calls the backend service to upload the file data.	account.uploadFileV2 (called within save methods)
Node Creation	Constructs the INodeCapture object with all its data and metadata before persisting it.	saveMarkdownCapture, postSave

Sources: client/products/memotron/capture/capture.store.ts

File Upload Sequence

The following diagram shows the sequence of events when a user uploads a single file.

Capture Methods

The ActiveCaptureStore implements several methods to handle different types of content capture.

Media File Capture (saveFile, saveMultipleFiles)

These methods handle the upload of one or more files. The process involves:

1. Resolving the NodeType from the file's MIME type using resolveContentTypeForFile.
2. Uploading the file binary via account.uploadFileV2, which returns a unique file ID.
3. Parsing file-specific metadata using parseMetadata.
4. Creating an INodeCapture object of the appropriate contentType (e.g., IMAGE, AUDIO).
5. Persisting the new node via nodeStore.create.

Sources: client/products/memotron/capture/capture.store.ts:655-703, 769-854

Device Capture (saveCameraCapture, saveAudioRecording)

The system supports direct capture from device hardware.

• saveCameraCapture: Captures an image blob, uploads it as a JPEG, extracts metadata (EXIF, device info, location), and creates an IMAGE node.
• saveAudioRecording: Takes a WebM audio blob, converts it to WAV using convertWebMToWav, uploads the WAV file, and creates an AUDIO node with metadata like duration and location.

Sources: client/products/memotron/capture/capture.store.ts:881-912, 976-1043

Web Content Capture (saveWebpage)

This method is used for saving URLs. It can handle generic web pages or specific types like YouTube videos.

1. It creates an INodeCapture object with contentType of WEB_PAGE or YOUTUBE_VIDEO.
2. If the user is logged into the cloud, it attempts to fetch server-side metadata for the URL (e.g., title, description, thumbnail) via new Persistence().retrieveUrlData(text).
3. For YouTube videos, it specifically calls fetchYouTubeMetadata to get video details.
4. The resulting IWebPage node is then created.

Sources: client/products/memotron/capture/capture.store.ts:1045-1100

Metadata Extraction

A key feature of the file management system is its ability to extract rich metadata from files on the client side before upload. This reduces server-side processing and enriches the data from the point of capture.

The parseMetadata function is the core of this process.

// client/products/memotron/capture/capture.store.ts:553-653
private async parseMetadata(file: File) {
    try {
      if (file.type.startsWith("image/")) {
        let metadata: IImageMetadata = {};
        const colors = await getImageColorsFromFile(file, 10);
        const tags = await ExifReader.load(file);
        const importantMetadata = extractImportantMetadata(tags);
        // ...
        return metadata;
      }
      if (file.type.startsWith("audio/")) {
        let metadata: IAudioMetadata = {};
        let parsedMetadata = await parseBuffer(
          new Uint8Array(await file.arrayBuffer())
        );
        // ...
        return metadata;
      }
    } // ...
}

Metadata Types

File Type	Library Used	Extracted Metadata
Image	exifreader	Device info (make, model), image details (dimensions, orientation), camera settings (aperture, ISO), GPS location.
Audio	music-metadata	Album, artist, title, year, duration, bitrate, and embedded cover art (which is uploaded as a separate image).

Additionally, the system attempts to get the user's current geolocation using the browser's Geolocation API via the getGeoLocation utility for captures that don't have embedded location data.

Sources: client/products/memotron/capture/capture.store.ts:553-653, client/products/memotron/node/node.type.ts:12-29

Backend and Deployment

The client-side code interacts with the backend through an abstracted account.uploadFileV2 function. While the implementation details are not in the provided files, the project's README.md indicates a future plan for a full backend deployment using Cloudflare services.

• Storage: Cloudflare R2 is the intended object storage service.
• Compute: Cloudflare Workers will likely handle API requests, such as generating upload URLs or processing files.
• Database: Cloudflare D1 is mentioned for database needs.

This suggests a serverless architecture where the client gets a pre-signed URL (or similar mechanism) from a Worker to upload the file directly to R2.

Sources: README.md:38-41, client/products/memotron/capture/capture.store.ts:670-677