Collaborative community

What does the full collaborative social community platform require, what exists, and what is still missing? This document is the requirements-and-evidence record for that active objective. It extends the earlier MVP scope. Passing the HTTP contracts does not complete the objective; editor synchronization, cursor overlays, conflict recovery and complete community journeys are still required. No hosted promotion or real social email campaign has been performed for this work.

Status: active work. Persistent social, notification, membership, presence and edit APIs pass SQLite and PostgreSQL fixtures; profile, discussion and collection UI is being qualified. See the table below and implementation status.

Entities#

%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#FAFAF7', 'primaryTextColor': '#1C1C1B', 'primaryBorderColor': '#1C1C1B', 'lineColor': '#64645F', 'fontFamily': 'DM Sans, Inter, system-ui, sans-serif'}}}%%
flowchart LR
  ACCOUNT["Account<br/>profile · picture · links · achievements"]
  PROJECT["Project (draft)<br/>members · roles · edits · sessions"]
  RELEASE[("Release / catalog entry<br/>immutable, public or not")]
  COLLECTION["Collection<br/>private · unlisted · public"]
  THREAD["Discussion thread<br/>anchored · public or team-only"]
  INBOX["Notifications<br/>center · preferences · deliveries"]

  ACCOUNT -->|follows| ACCOUNT
  ACCOUNT -->|likes · bookmarks| RELEASE
  ACCOUNT -->|owns| COLLECTION --> RELEASE
  ACCOUNT -->|invited viewer / commenter / editor| PROJECT
  PROJECT -->|publishes| RELEASE
  THREAD -.anchored to.-> RELEASE
  THREAD -.anchored to.-> PROJECT
  ACCOUNT -->|receives| INBOX
  ACCOUNT -.blocks · reports.-> ACCOUNT

  classDef source fill:#F0442E,stroke:#1C1C1B,color:#FAFAF7
  classDef shared fill:#DCEBDD,stroke:#1C1C1B,color:#1C1C1B
  classDef host fill:#DED8F0,stroke:#1C1C1B,color:#1C1C1B
  class RELEASE source
  class ACCOUNT,PROJECT,COLLECTION,THREAD shared
  class INBOX host

Mutable social data never enters a portable Toy or an immutable release package.

Requirements and evidence#

Identity and access#

SQLite migration 9 and PostgreSQL migration 10 add community, membership, session and edit records. Server-owned projects.parent_release records actual fork provenance separately from editable source for the remixer achievement. Achievements derive from real public work and contributions; no accounts or awards are invented.

Shared editing#

The API accepts a durable request key, an existing base project version and a shared authoring batch. It applies the batch to that admitted historical source, merges independent fields against the latest source, validates the complete result and commits through the existing applyBatch project writer. Scalar and array collisions reject with COLLABORATION_CONFLICT; invalid graph dependencies reject atomically. Toy identity stays stable. The authenticated account supplies the audit actor.

Undo reverses only the author's recorded change against the latest source, preserving unrelated peer work. A conflicting reversal rejects; an edit cannot be undone twice; Undo itself is recorded. Edit audit rows reference existing revision snapshots instead of duplicating whole source documents.

Presence stays outside Toys and audio callbacks.

Posts: reviews, comments and replies#

One posts table (SQLite migration 11, PostgreSQL 12) carries reviews, comments and replies, replacing the foundation comment table in place. services/api/src/posts.ts owns the rules; posts-store.ts owns storage and database triggers keep thread shape, depth, identity and the three-pin limit.

The web PostFeed renders Reviews (rating summary histogram filters, ReviewComposer, helpful sort) and Discussion tabs, threads with collapse below depth 2, reactions, pins, publisher responses, edit/remove/report and moderator actions. It replaces the Toy page discussion and editor team notes, and renders directly on the public React profile, collection and product pages inside the shared shell.

Notifications and operation#

Community events (follow, like, comment, reply, mention, invitation, collaboration edit) are written by notify() in the same transaction as the event. It drops self-notifications and blocked actors, deduplicates per account and collapses unread repeats with the same group key (for example likes on one Toy) into one row with a count. One NotificationRunner delivers every channel: it acquires a database lease, re-checks the verified address, current preferences, blocks and resource access, then calls the provider outside transactions. Retries keep provider identity; two runners cannot claim the same live lease. SES delivery is at-least-once across a crash after acceptance; exactly-once email is not claimed. Six attempts bound retries and rows retain delivery and failure evidence.

Email and push link to the authenticated app rather than embedding private source or comment text, and push bodies never name people or projects. Unsubscribe tokens are random, stored hashed, scoped to one category or all optional email, and can never disable required account, security or purchase notices. The unsubscribe page never mutates on GET; RFC 8058 one-click uses POST. The design and routes are in notifications and localization.

TUNETOYS_MODERATOR_ACCOUNT_IDS explicitly configures durable account IDs for report review. No administrator credential is seeded. PostgreSQL runtime privileges include the new tables. Offline import includes durable social data and orders threaded posts by insertion to preserve parent foreign keys. Cursor sessions are transient.

Verification#

The goal additionally requires every remaining workspace, cursor, conflict, reconnect and moderation item in the requirements table to be implemented and verified before completion.

Implementation#

• services/api — community.ts, community-routes.ts, community-access.ts, community-pages.ts, notifications.ts, notification-runner.ts, posts.ts, posts-routes.ts, posts-store.ts
• services/api/migrations — community and collaboration migrations
• packages/authoring — collaboration.ts merge and author Undo
• apps/web — CommunityApp.tsx, CollaborationPanel.tsx, PostFeed.tsx, ReviewComposer.tsx, RatingSummary.tsx, CreatorProfilePage.tsx, CollectionPage.tsx

Related#

• Discovery and public pages — creator pages and public routes
• Platform entities and API responsibilities
• Executable HTTP contract
• Authoring for people and agents — the single-author revision model this extends
• MVP scope — the authorization that added this objective