Collaboration System Architecture

Scope

The collaboration system defines an OS-native collaboration object model and UI primitive layer for Prox OS apps. @prox-os/collaboration owns participants, presence, comments, threads, mentions, share state, review requests, approval cards, collaboration panels, mock data, and adapter examples.

Runtime execution, persistence, realtime transport, notification delivery, search indexing, audit, workspace policy, and OS routing remain outside this package.

Position

Collaboration owns collaboration objects and UI primitives.
Apps own domain meaning.
Runtime and backend layers own execution, persistence, realtime, and policy.

This makes collaboration reusable across documents, media, maps, data tables, charts, AI sessions, settings, founder workflows, and future public creator resources without turning the package into a team chat product.

OS-Native Resource Model

OsCollaborationResourceRef identifies a resource without importing Shell or app internals:

• id
• kind
• title
• appId
• workspaceId
• route
• href
• icon
• metadata

Resource kinds include app, window, document, note, media, map place, data table, chart, file, workspace, workflow, AI session, and system resources.

Runtime-Agnostic Provider Boundary

Phase 1 ships components and mock data. It does not bind to a provider.

Future provider adapters should implement a narrow interface that can read and mutate collaboration objects while the UI continues to receive serializable contracts:

getPresence(resource)
listThreads(resource)
createComment(thread, body)
resolveThread(thread)
updateShare(resource, targets)
requestReview(resource, reviewers)
approveReview(review)
subscribe(resource, callback)

Provider candidates are documented as future choices:

• Yjs for local-first or CRDT document collaboration.
• Liveblocks for managed realtime collaboration.
• Supabase Realtime for Postgres-centric app collaboration.
• Cloudflare Durable Objects for workspace-aware coordination.
• WebRTC or local-first sync for peer-first experiments.

No provider is installed in Phase 1.

Event Flow

flowchart LR
  UI["Collaboration primitive"] --> Event["OsCollaborationEvent"]
  Event --> Action["Action intent"]
  Action --> Runtime["App or OS runtime"]
  Runtime --> Backend["Future backend/provider"]
  Backend --> Notify["Future notifications"]
  Backend --> Search["Future search/activity"]
  Backend --> Audit["Future audit"]

The UI emits collaboration events and optional action intents. The app/runtime decides what to execute, which provider to call, and which permission or audit rules apply.

Action Boundary

The package consumes @prox-os/actions for action intent helpers:

• open resource in OS;
• resolve thread;
• share resource;
• request review;
• approve review.

It does not execute the action. The Shell, app runtime, backend API, permission layer, and audit layer decide whether an action can run and what side effects it has.

Editor Boundary

Editors can create collaboration anchors:

• text selection anchors;
• block anchors;
• document resource refs.

@prox-os/collaboration does not render or own the editor. It maps editor-like selection data into OsThreadAnchor, which keeps comments portable across Tiptap, CodeMirror, future Lexical, or future document adapters.

Relationship To Future Packages

These packages should consume collaboration objects instead of redefining participants, threads, share state, or review status from scratch.

Data Model Sketch

classDiagram
  class OsParticipant {
    id
    kind
    name
    handle
    status
    role
  }
  class OsCollaborationResourceRef {
    id
    kind
    appId
    workspaceId
    route
  }
  class OsPresenceEntry {
    participant
    resource
    scope
    activity
  }
  class OsCommentThread {
    resource
    anchor
    status
    comments
    assignees
  }
  class OsComment {
    author
    body
    status
    mentions
    reactions
  }
  class OsShareState {
    resource
    visibility
    targets
  }
  class OsReviewRequest {
    resource
    status
    author
    reviewers
    checklist
  }

  OsPresenceEntry --> OsParticipant
  OsPresenceEntry --> OsCollaborationResourceRef
  OsCommentThread --> OsCollaborationResourceRef
  OsCommentThread --> OsComment
  OsShareState --> OsCollaborationResourceRef
  OsReviewRequest --> OsCollaborationResourceRef

Security And Privacy Considerations

• Presence can reveal attention and work patterns. Production providers need workspace policy and privacy controls.
• Mentions can notify users or agents. Future notification bridges should rate limit and respect user preferences.
• Public-link sharing must be decided by app/runtime/backend policy, not by UI state alone.
• AI agent participants must be labeled and audited.
• Comments may contain sensitive data. Search and activity indexing must be permission-aware.
• Thread anchors can point to media regions, map coordinates, or data cells; those anchors should not leak private resource context.

Why Phase 1 Avoids Realtime Backend

Realtime collaboration has high migration cost because it touches identity, permissions, audit, storage, search, conflict handling, and privacy. Phase 1 keeps the package testable and reusable by shipping the object model, UI surface, mock data, and adapter seams first.

Phase Roadmap

Phase 1: Collaboration Contracts And Primitives

• Types.
• Helpers.
• Mock data.
• React primitives.
• Storybook examples.
• Action, editor, and resource adapters.
• Docs.

Phase 2: Provider Adapters

• OsCollaborationProvider interface.
• Mock provider.
• Local storage provider.
• Optional Yjs, Liveblocks, Supabase Realtime, Durable Objects, or local-first adapter evaluation.

Phase 3: OS Runtime Integration

• Resource-level collaboration context.
• Window-level presence.
• Workspace-level permission-aware share state.
• Notifications, activity, search, and AI summary integration.

Phase 4: Community And Multi-Home Collaboration

• Public creator resource collaboration.
• Moderated comments.
• App review workflows.
• Dataset and document review workflows.

Non-Goals

• No chat app.
• No realtime backend in Phase 1.
• No collaborative editor engine.
• No notification center.
• No search index.
• No activity timeline.
• No permission or security policy engine.
• No OS Shell private imports.