Workstream: File Relational Filesystem Explorer

Status: Planned · Component: Maximize developer productivity

Goal

The human face of the File Relational Filesystem: a file manager — delivered as both a desktop application and a web application — that opens any File Relational Filesystem store by its url:// address and makes a graph of files as tangible as a folder window makes a tree. Enter the URL of a store — a shared hosted instance, or a local instance backed by a single file on disk — and browse it: walk named links, follow backlinks, manage links, paths, and tags, and move files across the boundary between the store and the local operating system with ordinary drag-and-drop and copy/paste.

The graph layer deliberately ships no human surface, so this application is where the File Relational Filesystem becomes something a person can see: the first application-layer consumer, built entirely on the public Api with no private hooks into the engine.

The shape

The decisions below are settled.

Connect by URL — or create a store outright. The Explorer opens a store the way a browser opens a site: type (or pick from recents) a url:// address pointing at a File Relational Filesystem instance, and browse it. Nothing is installed on the store side — the Explorer is a pure client, and several stores can be open side by side. Creation is equally first-class: the desktop application's New store creates a local single-file store on disk and serves it at a local url:// in one gesture, and inside any store the Explorer creates files, containers, and saved-query files directly — including pasting text or an image from the clipboard as a new file.

Navigation is the trail. Browsing follows the model's own semantics rather than faking a tree: forward steps walk named links, Back/.. retraces the trail actually walked, the address bar shows the current route with the file's display path as its human-readable spelling, and arriving at the same file along two routes is visibly the same file, not two copies. Cycles are simply navigable, not errors — the breadcrumb trail marks when a step revisits a file it already holds. The address bar accepts typed routes with autocomplete over named links, and bookmarks and per-store recents hold file IDs rather than paths, so they survive any reorganization and merge redirects heal them.

One location, three views. The current location renders through whichever lens fits: a folder/icon view and a list view — the two idioms every desktop file manager has taught for decades, with the list's columns drawn from the model (link name, tags, sizes, journal dates) — and a graph view that shows the edges: named links, anonymous relations, and backlinks radiating n hops around the current file. The graph view is always a neighborhood, never a whole-store render — a compass for orientation and discovery, not a map of the world.

The whole model is on screen. A file's panel shows what the graph layer knows: outgoing named and anonymous links, first-class backlinks ("what links here"), tags and attributes editable in place, and a content preview. A search box runs over the same tag, attribute, and backlink indexes the query layer maintains, and a search worth keeping becomes a saved query file in one gesture. Saved queries appear as the smart folders they are — browsing into a query file walks its materialized result links, live via Observables so open views update as the graph changes. A file's properties read out the File Relational Filesystem's reachable vs. exclusive accounting — what a subgraph holds vs. what removing it would actually free — alongside its journal-derived timestamps.

Organizing is linking. Every organizing gesture maps to the model's primitives: dragging a file onto a container creates a named link; move is relink — the new link created and the old one removed as a single atomic batch, so no observer ever sees the file half-moved; copy within a store never duplicates content, it links. Multi-selection makes bulk gestures — retag fifty files, relink a selection — land as the single atomic batch they should be. Delete is unlink, and the retention window behind the model's GC gets its familiar face: a recently unlinked trash view with restore, alongside visible pins and leases ("keep this alive while I work on it").

Edits are optimistic; reconciliation is visible. Every mutation appears in the view immediately, and until the store has durably acknowledged it — synchronized, flushed, journaled — the affected file wears a small spinning refresh badge in the lower-right corner of its icon. The badge clears when reconciliation completes; if reconciliation fails, the badge becomes an error state offering retry or journal-backed revert. A change is never silently dropped, and never silently pretend-saved.

Content opens in the tools people already use. On desktop, open exports a file's content to a watched temp file, launches the native application, and writes saves back — a new blob, the file rebound, journaled like any change, with the reconciliation badge showing until the write-back lands. On the web, text edits in the browser and common types preview inline. Editing never bypasses the model: it is a content rebind, not a mutation of bytes in place.

History is browsable, not just recorded. The journal surfaces as a per-file timeline ("who linked this here, and when"), a store-wide activity feed, and time travel: browse the store as it stood at an earlier instant, reconstructed from the journal, and diff a subgraph between two instants. Undo stops being a rescue and becomes a place you can look.

Merging happens here. The model's merge-is-forwarding primitive refuses a conflicted merge unless every clash is resolved in one atomic batch — an unfriendly contract for an API caller and a natural one for a dialog. Select two files, pick the survivor, resolve name, attribute, and content conflicts interactively, and commit as one batch; inspect a file's alias set ("what IDs has this file had"); un-merge from the history view. The Explorer also surfaces content twins — files whose content is the identical blob — as the natural feeder for merge decisions.

Sharing is a capability, and links are durable. Sharing a file or subgraph mints an attenuated W3Wallet capability for a person or an agent; the Explorer always shows which capability the current session is browsing with, and what a file's access control is. Web deep links wrap a store address and file ID into an ordinary https URL that lands a teammate in the same view — durable by construction, since IDs are stable and merge redirects heal moved identities.

The OS boundary is import/export, not a mount. Dragging files in from the local operating system imports them: content into the store's blob layer, new files linked where they were dropped — and dragging in a folder maps its hierarchy to container files and named links, the tree-ingest pattern. Dragging out — or copying in the Explorer and pasting in the native file manager — exports ordinary copies onto the local filesystem, and exporting a container materializes a directory tree of copies, reachability-bounded and cycle-safe, each file written once (NTFS, APFS, ext4 — it makes no difference; copies at the edge are just bytes). The Explorer never mounts the graph into the OS and never pretends the two sides share semantics: it is the projection layer, honest on the graph side and conventional on the OS side.

Why it accelerates developers

• A primitive nobody can see doesn't get adopted. The Explorer makes the File Relational Filesystem inspectable from day one — the debugging and demo surface for every other consumer, the way a database browser is for a database.
• The on-ramp for real data. Drag-and-drop import and export move actual files into and out of graph organization without writing a line of code against the Api.
• Trust through visibility. Backlinks, display paths, journal-backed undo, live views, and visible reconciliation demonstrate the model's promises interactively — the fastest way to teach graph organization to people raised on trees.

Plan / roadmap

Milestones in proposed order; each earns its detailed design in its implementation repository as it starts.

• [ ] Read-only browser. Connect by url://, trail navigation with display paths and address-bar routes, folder/icon and list views, link/backlink/tag/attribute panels, content preview, and index-backed search — desktop and web from one codebase.
• [ ] Creation. New store on desktop (a local single-file store served at a local url://); new files, containers, and saved-query files; clipboard paste-in.
• [ ] Organizing. Create, rename, and remove links; edit tags and attributes; move-as-relink and multi-select bulk operations as atomic batches; journal-backed undo; the trash view, pins, and leases — with reconciliation badges on every pending change.
• [ ] Content editing. The desktop open-with round-trip (watched temp file, write-back as a content rebind) and in-browser text editing with inline previews.
• [ ] The OS boundary. Import and export via drag-and-drop and copy/paste in both directions, including recursive folder import and cycle-safe tree export.
• [ ] Live views. Query files as smart folders and Observables-driven updates, so open views track the graph in real time.
• [ ] Graph view. The neighborhood lens: links, relations, and backlinks radiating from the current file.
• [ ] History and merge. The per-file timeline, activity feed, browse-as-of and subgraph diff; the interactive merge workflow with conflict resolution, alias inspection, un-merge, and content-twin surfacing.
• [ ] Sharing. Capability minting and display (W3Wallet), and durable web deep links.
• [ ] Later phases. Query authoring in the UI; side-by-side multi-store windows with copy-between-stores via the File Relational Filesystem's subgraph export/import.

Graduation

This workstream depends on the File Relational Filesystem core engine and query layer existing first. It graduates when a person can point the desktop or web application at a real store over url:// and complete the whole loop — browse by trail, search, reorganize by linking, edit a file's content in a native application, undo a mistake, and round-trip files to and from their local operating system — at which point it becomes a first-class project with a Documentation Repository project page and an ALL_PROJECTS.md entry.