T-HUB/docs/design/2026-10-12-collectives-architecture.md

Collectives architecture — participation, rooms, subcollectives, diffusion

Status — P1 shipped (implementation note). The three scope pillars of P1 are in: groups.parent_id/groups.kind/group_rooms (migration 030_collectives.sql), the participation-manual landing page at the app root (apps/web/src/app/page.tsx, copy in packages/core/src/participation-manual.ts), and the provisioner port + Matrix implementation (apps/api/src/collectives/). Join-by-invite is unchanged: an invite token claims workspace membership exactly as before; GET /collectives-public/for-invite/:token adds names-only collective labelling to the join card. Room addresses in the UI, directory, and the UI/state re-parenting surface remain P2+.

Status: design for build (phase 1 dispatch in flight) Date: 2026-10-12 Decides: landing flow, collective model, room matrix, provisioning, diffusion

Product shape

app.occupymedia.cc lands on the participation manual (Spanish-first, English toggle) with three paths:

1. Join an existing collective — invite link (/join/[token], exists).
2. Start a collective — creates the collective + its room set + onboarding.
3. Solo user — account + onboarding room (channels + guide bot explains how to plug in); can join or start a collective later.

Account tiers, signup, membership (amended 2026-10-12)

Self-serve accounts are now part of the product. The site lets anyone create an account without belonging to any collective. Posture reconciliation: the homeserver keeps registration token-gated; the Hub mediates account creation (the Hub holds the registration capability and provisions the Matrix account server-side after its own signup checks). Direct registration on chat.occupymedia.cc stays closed — the Hub is the only door, and it can add rate-limiting / verification later without touching the homeserver.

• Solo account: gets the platform's storage (R2-backed files space) and PeerTube access — the full media-maker toolkit, no collective.
• Membership is many-to-many: one media maker can belong to several collectives at once (group_members already models this); solo users can be invited into collectives later, or request to join.
• Account is the unit of identity; collective membership is a set, not a home.

Contribution policy (per collective, disclosed at join time)

Every collective defines what happens to members' contributions:

• Default and stated plainly at join: deleting your account does NOT delete your contributions. Content already submitted to a collective stays in its library/archive, attributed, under the collective's retention rules.
• Collectives may override (e.g., "contributions are removed on request", "contributions are anonymized after 90 days") — the policy is a field on the collective, shown on the join screen and in the collective's settings.
• Enforcement is schema-level: contributions must not ON DELETE CASCADE from the user row. User deletion detaches attribution per policy; it never silently rips content out of a collective archive.

Telegram access to open rooms

Open rooms bridge to Telegram (mautrix-telegram, already scaffolded in the chat CT's compose): a collective's open room can attach a Telegram group so outsiders participate from Telegram with no Matrix account at all — same bridge pattern as Matrix federation for open rooms, different door. Bridged rooms are verified for encryption state (never treated as plaintext by assumption); archiving follows the same open-room rules.

Collective model (maps to what exists)

A collective is a group in the Hub's group tree — groups.parent_id becomes self-referencing (top-level groups = collectives, children = subcollectives, recursive). This rides the existing groups/RBAC/files machinery (group_files, group_members, chat_media_archive are all keyed workspace+group) instead of fighting workspace isolation with cross-tenant writes. Workspace-per-collective stays available later if isolation demands it.

• Root group = collective. Children = subcollectives ("report to the top one").
• Files: each collective/subcollective keeps its own group folder in the files app (already how group_file_shares is laid out: <ws>/<group>).
• Chat: room set per collective (below), bound to the group via the existing ROOM_MAPPINGS-style immutable mapping.

Rooms per collective

Collective creation includes the Open (public) room by default — a visible toggle lets the founder opt out. A collective that opts out is fully private from day one; one that keeps it gets the outsider door (federated Matrix + optional Telegram bridge, below).

Room	Visibility	Encryption	Federation	Purpose
Open	Public, listed	Never (bot-readable)	Yes	Outsiders (any Matrix server) talk to the collective
Closed (production)	Invite-only	E2EE default	No	Internal production
Onboarding	Invite-only, per user	No	No	Guide bot posts the participation manual, ES/EN

Open rooms are federated: outsiders join from their own Matrix accounts on any server — no accounts minted on ours for outsiders (registration stays token-gated; outsiders never get local credentials). Closed rooms are local-only + E2EE: ciphertext on the server, nothing readable by seizure. Archive mirroring applies to Open rooms only (bot-readable by definition); closed-room material stays in the room (members' clients = the backup) until the phase-B encrypted-export flow gives admins self-service copies.

Provisioning

A provisioner bot account (distinct from the archive bot; both crypto-blind) creates the room set on collective creation:

• creates Open room (public, federated, history_visibility: shared), sets power levels (collective admins = PL 100, members = PL 0 + post), posts the room address into the Hub group record
• creates Closed room (invite-only, m.room.encryption state set at creation — the bot sets ciphertext it can never read, invites the founding members)
• creates the founder's Onboarding room + posts the manual sequence (ES first)
• records everything in the Hub DB (group ↔ room mapping table — extends the existing archive mapping pattern)

Encrypted-by-default is thus structural: every production room is born encrypted; the only unencrypted rooms are Open (by product definition) and Onboarding (bot-posted guide, disposable).

Diffusion (push content upward)

Subcollectives push content to the parent's diffusion queue; the parent releases. Maps onto the existing publishing pipeline (drafts → approvals → schedule → dispatch):

• New table diffusion_submissions: id, from_group_id, to_group_id (parent), draft_id or file_ref, submitted_by, status (submitted|approved|released|rejected), approver, timestamps.
• Submission = the existing approval request, cross-group: the parent collective's approvers see it in their Approvals queue with origin labeling ("from subcollective X").
• Release = the existing publish dispatch. No new publish machinery.

Recursive trees compose naturally: a sub-subcollective pushes to its parent; that parent can push its own (and forwarded) content further up.

Participation manual

Spanish-first static page at the app root (/), English toggle. Structure: what this platform is → the three paths → room etiquette (open vs closed) → safety model summary (E2EE, token-gated accounts, redaction behavior) → how to get help (onboarding room). Source content: the Acampada 26S kit copy where applicable; written new where not. Lives in the app (i18n dictionaries), not a PDF.

Build phases

1. P1 (dispatched): groups.parent_id migration + collective create/join APIs + landing page (manual + three paths) + provisioner bot (room set + onboarding rooms) + onboarding guide content (ES/EN).
2. P2: files UI shows the collective tree; open/closed room addresses surfaced per collective; Element spaces mapping (one Element space per collective: open + closed rooms together).
3. P3: diffusion submissions (push/approve/release across the tree) with origin labeling in Approvals.
4. P4: phase-B encrypted export bundles (in flight separately) extended to per-collective admin keys.

Security posture recap

• Outsiders: federated into Open rooms only; zero local credentials.
• Production rooms: E2EE at birth; server stores ciphertext.
• Onboarding rooms: disposable, bot-posted guide only.
• Seizure: E2EE ciphertext + admin-held export keys (phase B) reconstruct the archive; Open-room content was public by definition.