File System Architecture

Scope

The file system layer defines OS-native file and artifact primitives for Prox OS apps. @prox-os/files owns file/folder/storage contracts, file browsing and picker primitives, preview view models, transfer-state primitives, adapter examples, mock data, and Storybook examples.

Real storage, upload/download transport, sync conflict resolution, provider credentials, browser file-system permissions, persistence, permission enforcement, routing, and execution remain outside this package.

Position

Files owns file objects, storage refs, file UI, previews, transfer state, and adapters.
Apps own domain meaning.
Runtime and backend layers own storage providers, transfers, permissions, routing, and execution.

This lets Prox OS represent docs, media, datasets, exports, imports, AI artifacts, developer artifacts, workspace files, and community resource packs without binding frontend primitives to a cloud drive backend.

Files Versus Storage Backend

@prox-os/files models what a file is and how the UI can display or select it. A storage backend decides where bytes live, how URLs are signed, how versions are retained, how conflicts are resolved, and how permissions are enforced.

Phase 1 ships only mock provider refs such as local mock storage, Prox OS mock storage, Cloudflare R2 future storage, and external URLs.

Runtime-Agnostic Storage Provider Boundary

Future provider adapters can implement a narrow boundary:

list(path, scope)
get(fileId)
createFolder(input)
rename(fileId, name)
move(fileId, folderId)
delete(fileId)
restore(fileId)
createUpload(input)
completeUpload(taskId)
getPreview(fileId)
getSignedDownloadUrl(fileId)
subscribeToTransfers(scope, callback)

Provider candidates remain future choices:

• local mock or local storage provider;
• Cloudflare R2 provider;
• S3-compatible provider;
• WebDAV provider;
• Google Drive or Dropbox adapter;
• OPFS or browser File System Access provider;
• per-workspace storage routing.

No provider SDK is installed in Phase 1.

Event Flow

flowchart LR
  UI["File UI"] --> Event["OsFileEvent"]
  Event --> Ref["OsFileActionRef"]
  Ref --> Intent["OsAction intent"]
  Intent --> Runtime["App or OS runtime"]
  Runtime --> Provider["Future file provider"]
  Provider --> Backend["Future backend/storage"]

The UI emits file events and action refs. Runtime decides whether a file opens inside the OS, a new tab, an editor, a media viewer, a download flow, a permission dialog, or a backend transfer.

Search Flow

flowchart LR
  File["OsFileNode"] --> Document["OsSearchDocument"]
  Document --> Search["Search adapter/provider"]
  Search --> Result["OsSearchResult"]
  Result --> Intent["Open/preview/copy action intent"]

Files provides fileToSearchDocument. Search owns query, filters, facets, ranking, highlights, and result UI.

Notification Flow

flowchart LR
  Transfer["OsFileTransferTask"] --> Draft["OsNotification draft"]
  Event["OsFileEvent"] --> Draft
  Draft --> Notifications["@prox-os/notifications"]

Files can create notification drafts for upload complete, upload failed, sync conflict, export ready, file shared, or restricted access attempted. The notifications package owns presentation and preferences.

Collaboration Flow

flowchart LR
  File["OsFileNode"] --> Resource["OsCollaborationResourceRef"]
  Resource --> Threads["Threads/reviews/presence"]

Files can map a file into a collaboration resource ref. Collaboration owns comments, threads, reviews, sharing, and presence.

Data Model Sketch

classDiagram
  class OsFileNode {
    id
    kind
    fileKind
    name
    size
    status
    location
    accessLevel
  }
  class OsFolderNode {
    childCount
    children
  }
  class OsStorageProviderRef {
    id
    kind
    label
    workspaceId
  }
  class OsFileLocation {
    path
    provider
    route
    href
  }
  class OsFilePreview {
    kind
    title
    body
    rows
  }
  class OsFileTransferTask {
    kind
    status
    progress
    conflictWith
  }
  class OsFileActionRef {
    kind
    label
    actionId
  }

  OsFolderNode --|> OsFileNode
  OsFileNode --> OsFileLocation
  OsFileLocation --> OsStorageProviderRef
  OsFileNode --> OsFilePreview
  OsFileNode --> OsFileActionRef
  OsFileTransferTask --> OsFileNode

Relationship To Frontend Packages

Privacy, Permission, And Retention Considerations

• File nodes can express accessLevel, visibility, sensitive, provider metadata, and mock scan state, but real permission enforcement belongs to runtime/backend policy.
• Public links, external URLs, and AI artifacts should carry provenance and retention metadata once providers are real.
• Provider implementations must avoid leaking signed URLs or private paths into public search or notification surfaces.
• Upload queues can reveal local file names and should be scoped to the current workspace once persisted.
• Browser file-system permissions must be requested only by a runtime adapter with explicit user action, not by this primitives package.

Why Phase 1 Avoids Real Storage APIs

Files touches credentials, signed URLs, tenancy, upload reliability, sync conflict resolution, retention, data residency, malware scanning, privacy, and permission enforcement. Phase 1 keeps the package reviewable by shipping the contracts, helpers, mock data, UI primitives, and adapter seams first.

Phase Roadmap

Phase 1: File Contracts And Mock Primitives

• Types.
• Helpers.
• Mock file tree.
• Mock storage providers.
• Mock transfer queue.
• React primitives.
• Action, search, notification, collaboration, workspace, AI artifact, security, and resource adapters.
• Storybook examples.
• Docs.

Phase 2: Provider Boundary And Local State

• OsFileProvider interface.
• Mock provider and local storage provider.
• File picker provider boundary.
• Upload queue state adapter.
• Recent and pinned files persistence.
• Optimistic rename, move, delete, and restore UI state.

Phase 3: OS Runtime Integration

• OS file picker runtime API.
• File open handoff for apps, windows, editors, media viewers, and resources.
• Recent files in command and search.
• Notification and activity integration.
• Workspace-scoped storage view.

Phase 4: Real Storage Providers

• Cloudflare R2 provider.
• S3-compatible provider.
• WebDAV provider.
• Google Drive and Dropbox adapters.
• OPFS and browser File System Access evaluation.
• Signed upload and download URLs.
• Versioning, retention, recycle bin, and permission-aware routing.

Phase 5: AI And Community Artifacts

• AI artifact lifecycle.
• File summarization and question answering.
• Public dataset and media sharing for creator routes.
• Community app assets, templates, and resource packs.

Non-Goals

• No real cloud drive backend.
• No upload, download, sync, import, or export transport.
• No browser file-system permission prompt.
• No OPFS, IndexedDB, or File System Access provider.
• No storage SDKs.
• No virus scanning, DLP, encryption, or audit enforcement.
• No search, notification, collaboration, command, editor, workspace, security, AI, or activity ownership.
• No OS Shell private imports.