Flock · atproto Spaces

Team chat can live on the open web without a vendor-owned database

Flock is an alpha Slack-style workspace where channels and membership live on members’ PDSes. This talk is about why we built it that way and how we stay aligned as Spaces evolves.

https://github.com/atproto-sandbox/atprotocol-slack-clone

Mike Staub · bsky.app/profile/mikestaub.social

Demo: docs/media/bdd-session.mp4 — full UI scenario walkthrough

Part 1

Why

Why

Workspaces should be portable, permissioned, and readable without our servers

  • No app database of record. Workspace state is spaces + member lists on each person’s host.
  • Permission follows the protocol. If you’re on the member list, you can read; the app doesn’t re-decide.
  • Anyone can verify. Our independent reader rebuilds workspaces from lexicons and PDS data alone.

Apps still need a small operator: someone trusted to apply membership changes safely and tell clients when repos change—without holding the messages.

Why now

Spaces are moving fast; app builders need a reference that tracks upstream

Alpha

Targeting ATProto Spaces proposal work (not a frozen release)

We expect breakage—and plan for it

68

Browser scenarios exercise the product every CI run

Plus protocol acceptance tests

Open

Lexicons, operator, and tests are in the repo

Feedback welcome

Part 2

How

How · data flow

Messages live on PDSes; the operator journals changes and relays “something changed” without holding content

Animated packets (loop) show direction; captions stay plain language

Web app

Operator

Admin action · service auth

Operator

Space PDS

Journaled writes · roster / channels

Space PDS

Operator

Wake · repo cursor (no message body)

Web app

Operator

Change feed · long poll

Web app

Space PDS

STAR read · space credential

Operator URL serves XRPC; web talks to member PDSes directly for reads

Privacy assumptions

Channel chat is governed by the PDS; DMs stay off the app server; the operator is a control plane—not a message store

  • Who can read channels. Only accounts on each space’s member list (enforced by the host). The app does not run a shadow ACL or central message database.
  • Where messages live. Authors write to their own repos; other members pull with space credentials in the browser. What you see is merged client-side (and cacheable in IndexedDB on your device).
  • Direct messages. Reads and writes go browser → participant PDS only. Our Next.js app and operator APIs do not carry DM bodies; losing the vendor does not delete your DM repo.
  • What the operator must see. Journaled admin actions, encrypted workspace-authority OAuth, and content-free “something changed” hints—enough to resume invites and channel setup, not enough to render history.

How · lexicons

Forty-one new.flock lexicons, A–Z down each column (com.atproto.* is vendored separately)

new.flock.acceptance
new.flock.admin
new.flock.app.action
new.flock.app.command
new.flock.app.declaration
new.flock.app.inbox
new.flock.app.install
new.flock.channel
new.flock.channel.message
new.flock.channel.reaction
new.flock.channel.roster
new.flock.directory
new.flock.dm.conversation
new.flock.dm.declaration
new.flock.dm.header
new.flock.dm.inbox
new.flock.dm.message
new.flock.dm.reaction
new.flock.dm.request
new.flock.ext.install
new.flock.ext.tasks
new.flock.ext.tasks.comment
new.flock.ext.tasks.project
new.flock.ext.tasks.projectEdit
new.flock.ext.tasks.task
new.flock.ext.tasks.taskEdit
new.flock.inbox
new.flock.joinDecision
new.flock.joinRequest
new.flock.operator.createWorkspace
new.flock.operator.execute
new.flock.operator.getChanges
new.flock.operator.getOperation
new.flock.operator.listInboxWriters
new.flock.operator.listStalledOperations
new.flock.operator.startAuthorityFlow
new.flock.permissions.member
new.flock.permissions.workspaceAuthority
new.flock.workspace
new.flock.workspace.profile
new.flock.workspace.roster

packages/protocol/lexicons/new/flock · sorted ascending

How · public API

Flock exposes three surfaces: operator service, web OAuth metadata, and direct PDS Spaces XRPC

SurfaceEndpointWho calls
Operator service (OPERATOR_URL)
procedure/xrpc/new.flock.operator.executeBrowser (admin)
query/xrpc/new.flock.operator.getOperationBrowser
query/xrpc/new.flock.operator.listInboxWritersBrowser
query/xrpc/new.flock.operator.listStalledOperationsBrowser
procedure/xrpc/new.flock.operator.getChangesBrowser (change feed)
procedure/xrpc/new.flock.operator.createWorkspaceBrowser
procedure/xrpc/new.flock.operator.startAuthorityFlowBrowser
procedure/xrpc/com.atproto.space.notifyWriteSpace PDS → operator
procedure/xrpc/com.atproto.space.notifySpaceDeletedSpace PDS → operator
GET/.well-known/did.jsonDiscovery
GET/authority/start · /authority/callback · client-metadata · jwksWorkspace authority OAuth
Web app (APP_URL) — no member XRPC on the server
GET/oauth/client-metadata.jsonMember OAuth (browser only)
Member PDS (browser + space credential)
—com.atproto.space.* (STAR read/write, credentials)Browser sync engine
—com.atproto.memberspace.*Operator journal + browser
—com.atproto.server.getServiceAuthService JWT → operator

How we stay current

Pin upstream, regenerate lexicons, mirror the PDS in tests, then migrate the operator in focused waves

Pin

Known good commit

  • Reproducible builds
  • Documented checkout

Test

Fake network

  • Same rules as upstream
  • Fast feedback

Ship

Operator + UI

  • Journaled migrations
  • Recorded UI demo

Active branch: chore/protocol-drift-6747610 (R12 alignment work)

Part 3

Next steps

Next steps

We are finishing operator notify alignment, then inviting collaborators to stress-test Spaces apps

  1. For product teams: Clone the repo, run the playground, watch the recording on slide 1.
  2. For protocol folk: Tell us where app-hosted webhooks feel sharp-edged (renewal, grace, multi-tenant tokens).
  3. For us: Land R12c, refresh the demo video, publish a short migration note for app operators.

Next steps

Explore the code, run the tests, and tell us what would make Spaces easier for your app

Repository

https://github.com/atproto-sandbox/atprotocol-slack-clone

Quick start: README → playground · Tests: pnpm test:bdd · Developer onboarding (Spaces guide)

Mike Staub · bsky.app/profile/mikestaub.social