Skip to content

Collaboration Infrastructure

Last synthesized: 2026-04-29
Operational source: Current collaboration architecture discussion plus repo review of D:\02_Code\45_merged_macos_colabui_dfmanim
Purpose: Capture what RapidDraft must build for professional model collaboration, and separate the current prototype capability from the target production architecture.

Why This Page Exists

RapidDraft's collaboration feature should not be treated as just "comments on a model." The current repo already proves that model-attached comments are possible, but the professional version is closer to a lightweight Google Docs or Drive-style engineering review space: users upload CAD files, discuss the model, attach screenshots, recover activity, and share access with controlled permissions.

The key architectural point is that collaboration needs its own backend domain. It cannot remain a set of local JSON files, browser cache exports, and UI-only controls if the product is expected to support real customers and a small number of parallel users.

Current Repo Findings

The current RapidDraft integration repo has moved from prototype-only collaboration to a useful pilot-grade CAD Drive foundation:

  • product session/auth wiring exists for signed-in users
  • database-backed collaboration state exists for model documents, revisions, artifacts, tickets, replies, share links, and model access grants
  • STEP/STP upload persists model artifacts and registers model metadata
  • the file tree includes both owned and grant-shared models
  • share links and email invites are exposed through the CAD Drive share modal
  • comments are attached to a model through /api/models/{model_id}/tickets
  • comment pins store model-space position, normal, and camera state
  • replies, assignees, priority, status, resolved state, markdown, and @mention rendering exist
  • revisions can be uploaded, listed, selected, and used as comment-origin context
  • short polling refreshes comments and revisions across open browsers
  • local dev can run the full collaboration path through a SQLite-backed fallback database

This is enough for a small trusted-user share. It is not enough for broad production collaboration.

Target Collaboration Architecture

The minimum professional collaboration layer should include:

Capability Target architecture Current status Complexity
Model-attached comments Comments stored as first-class records against a model/document, not imported sidecars Partially present Low
Real database PostgreSQL or equivalent with transactions, indexes, migrations, and backup policy Present for collaboration core; backup rehearsal still open High
Authentication Product auth plus optional Cloudflare Access for protected pilot surfaces Working foundation High
User profiles Users, display names, avatars/initials, organizations, and team membership Users + initials present; organizations/team membership still thin Medium
Roles and permissions Owner, admin, editor, commenter, viewer, and guest policy enforced in backend Owner/edit/read grants and share-link scopes present; richer roles still open High
Admin flows Invite, revoke, role changes, team/project administration, access audit Invite/revoke/role changes present for model access; team/project admin still open High
Onboarding flows Account creation, invite acceptance, first workspace/project/model setup Absent Medium
Guest or view-only URL sharing Share tokens with viewer/commenter/editor mode, expiration, revocation, optional password Share links present for read/edit; broader guest policy still open Medium-High
Password-controlled sharing Password hash on share link, verification session, lockout/rate limit PIN gate present; rate/abuse controls still open Medium
Screenshot attachments Viewer capture uploaded to server storage and linked to comments/activity Partial Medium
Activity recovery Append-only activity log covering uploads, comments, replies, screenshots, reviews, permission changes UI-derived activity only; durable backend stream still open Medium
Backend format conversion Async ingestion pipeline for non-STEP CAD inputs so upload does not fail immediately Format metadata present; routing/conversion still incomplete High
Parallel users Concurrency-safe persistence, optimistic updates, polling or realtime event stream Short-poll foundation present; SSE/WebSocket still open High

The collaboration domain should be database-backed. A first production schema can stay modest:

users
organizations
organization_members
documents
document_versions
model_artifacts
comments
comment_replies
screenshots
activity_events
share_links
document_permissions
ingestion_jobs

documents should become the product object users share. A document owns the uploaded model, generated viewer artifacts, comments, screenshots, review sessions, and activity log. The current model_id can remain the internal geometry identifier, but it should sit under a document-level permission boundary.

Permission Boundary

Frontend controls are not sufficient for collaboration. The backend must enforce permission checks on every document-scoped write.

Recommended roles:

Role Can view Can comment Can edit review state Can manage sharing Can administer
Owner Yes Yes Yes Yes Yes
Admin Yes Yes Yes Yes Yes
Editor Yes Yes Yes No No
Commenter Yes Yes No No No
Viewer Yes No No No No
Guest link viewer Yes No No No No

This role model can be extended later, but the first version should keep write permissions simple and auditable.

Sharing Model

The share feature should create a server-side share_link record rather than exposing raw model_id access.

Minimum share-link fields:

{
  "id": "share_...",
  "document_id": "doc_...",
  "token_hash": "...",
  "role": "viewer",
  "password_hash": null,
  "expires_at": null,
  "revoked_at": null,
  "created_by_user_id": "user_..."
}

The public URL should resolve through a token route such as /share/{token}. The token grants only the role encoded in the share link. If a password is configured, the backend should verify the password before issuing a short-lived share session.

Ingestion and Format Conversion

The current upload path is strongest for STEP/STP. Production collaboration should not make non-STEP input die at ingestion. Instead, upload should create an ingestion_job with clear states:

uploaded -> queued -> converting -> preview_ready -> canonical_ready -> failed

The first response should create the document and show progress. Conversion can run asynchronously, with the UI showing whether preview geometry, canonical selection data, DFM review readiness, and screenshots are available.

This aligns with the existing RapidDraft viewer direction:

preview mesh first -> canonical manifest second -> lazy semantic detail third

Parallel User Behavior

The first professional version does not need full Google Docs-style realtime editing. It does need clean behavior for a small number of users viewing and commenting at the same time.

Minimum acceptable behavior:

  • database transactions for all comment/reply/permission writes
  • stable ordering by server timestamps
  • optimistic UI updates with server reconciliation
  • polling or server-sent events for new comments and activity
  • conflict-safe updates for comment status and permissions

Realtime cursors and live presence can come later.

Implementation Slices

  1. Activity and event stream hardening
    Add durable backend activity events and SSE/WebSocket delivery for comments, replies, resolve, version upload, and access changes.
    Complexity: Medium-High.

  2. Auth, profiles, and organization membership
    Deepen the current product-user foundation into organization/team membership, while preserving Cloudflare Access as a pilot-surface identity provider where useful.
    Complexity: High.

  3. Model document permissions
    Expand the current owner/read/edit model into commenter/viewer/guest policies and audit coverage.
    Complexity: High.

  4. Version carry-forward UX
    Add explicit carry-forward, re-pin, and anchor-confidence behavior for comments across revisions.
    Complexity: Medium.

  5. Screenshot attachments and activity log
    Reuse existing viewer capture, upload screenshots, and append document activity events for recovery.
    Complexity: Medium.

  6. Async non-STEP ingestion
    Strengthen format-specific preview routing and add conversion jobs/progress states for non-STEP inputs.
    Complexity: High.

  7. Small-team concurrency
    Add polling or SSE, optimistic reconciliation, and transaction-backed updates.
    Complexity: Medium-High.

Product Boundary

For the next version, collaboration should mean:

  • a shared model document
  • persistent model-attached comments
  • screenshot and activity recovery
  • authenticated users
  • roles and permissions
  • guest/view-only sharing by URL
  • safe handling of parallel comment activity
  • upload/conversion states that do not strand non-STEP users

It should not yet mean:

  • full realtime co-editing
  • multi-cursor CAD editing
  • native CAD PDM replacement
  • complex enterprise IAM beyond the first auth and organization model

Open Questions

  • Which database should be the first production target: Supabase Postgres, Railway Postgres, Neon, or another managed Postgres option?
  • Should share links allow commenter access in v1, or should v1 be view-only plus authenticated editor invites?
  • Which non-STEP formats matter first for pilots: SLDPRT, IGES, STL, OBJ, DXF, or native NX?
  • Should screenshots be stored in database-backed object storage from day one, or filesystem/object storage with database metadata?
  • What is the minimum admin surface: owner-only sharing settings, or full organization admin?

Sources

  • Current repo reviewed: D:\02_Code\45_merged_macos_colabui_dfmanim
  • Comment UI: web/src/components/CommentForm.tsx
  • Review types: web/src/types/review.ts
  • Viewer capture and pinning: web/src/components/ModelViewer.tsx
  • App comment/session wiring: web/src/App.tsx
  • Backend comment endpoints: server/main.py
  • Comment persistence: server/review_store.py
  • Pilot identity/auth: server/access_auth.py
  • Related wiki page: CAD Viewer and Annotation Architecture