~ knotless Search/
↑↓ move↵ open⇧↵ all results

chadtmiller.com/spaces-bookclub

Book club: a Svelte demo app for atproto spaces (@atproto/lex-space)

0
0
main
Go to filet
Code
README.md

Book club: an atproto spaces app

A Svelte app on @atproto/lex-space. Members of a club share book reviews that only other members can read. Every member keeps their reviews in their own repo, on their own PDS. The club's authority (its creator) hosts the member list and decides who may read.

Everything runs locally: a PLC directory, two PDSes, a lexicon authority and a handle resolver, all in one Node process.

flowchart LR
  app[Svelte app<br/>127.0.0.1:5173]
  plc[PLC directory<br/>:2582]
  hr[Handle resolver<br/>:2580]
  pds1[PDS 1 :2583<br/>alice, carol<br/>lexicon authority]
  pds2[PDS 2 :random<br/>bob]
  app -- OAuth, own repo --> pds1
  app -- OAuth, own repo --> pds2
  app -- space credential:<br/>other members' repos --> pds1
  app -- space credential --> pds2
  app -- DID docs --> plc
  app -- handles --> hr
  pds1 & pds2 -- resolve NSIDs --> pds1

Prerequisites

  • ../atproto checked out on permissioned-data-alpha and built (pnpm install && pnpm run build at its root). The @atproto/* dependencies are link:ed from it: they are not published yet.
  • Node ≥ 22.

Run

pnpm install
pnpm network   # terminal 1: PLC, PDSes, accounts, lexicons
pnpm dev       # terminal 2: http://127.0.0.1:5173

Use 127.0.0.1, not localhost: OAuth loopback clients redirect there.

Test accounts, all with password password: alice.test and carol.test (PDS 1), and bob.test2 (PDS 2). The network is in memory: restarting it wipes everything, so sign out first or the app will restore a dead session.

Try it

  1. Sign in as alice and create a club. Post a review, then add bob.test2 as a member and copy the club's invite link from Invite.
  2. Sign out and open the link. Sign in as bob: the app joins the club once he's back. Bob reads alice's review from PDS 1 with a space credential, then posts his own review into his repo on PDS 2.
  3. Sign in as carol and try to join. She gets SpaceNotFound.
  4. As alice, remove bob. His next load fails with SpaceNotFound.

How it fits together

FileWhat
lexicons/com/example/bookclub/club.jsonThe space type: TID keys, holding info and review records
lexicons/com/example/bookclub/info.jsonA club's name and description: one record (self) in the host's repo
lexicons/com/example/bookclub/review.jsonThe review record
src/lexicons/Generated by lex build (pnpm lex, run before dev, build and check)
src/lib/atproto.tsOAuth client and scopes, plus BookClubApp, which wraps every space call
src/styles/tokens.cssDesign tokens: a primitive palette, and the semantic tokens components use (remapped for dark mode)
src/components/UI, in atomic design layers: atoms → molecules → organisms (including every action dialog) → templates → pages
dev/network.tsLocal network, accounts, lexicon publishing, and the handle resolver

Scopes. These are requested in src/lib/atproto.ts:

  • space:com.example.bookclub.club?authority=*: read every club the user is in, and write the collections the space type declares.
  • space:com.example.bookclub.club?manage=create&manage=update&manage=delete: create clubs with the user as authority, and manage their members and lifecycle.

At consent, the PDS resolves the space type's lexicon to name it and to expand the first scope into its collections. That is why dev/network.ts publishes lexicons/ from the lexicon authority's repo, which both PDSes resolve every NSID against. On the real network, the NSID's domain owner publishes the lexicons instead.

Reading. SpaceClient.allRecords() reads every repo in the club's writer set. It fetches each repo from its own PDS and verifies it against the MAC from that PDS before returning any records. Reads of the user's own repo go through their OAuth session. Reads of other members' repos use a space credential, which the club's authority PDS issues in exchange for a delegation token from the user's PDS. lex-space handles all of this.

Discovery. listSpaces on the user's PDS only lists clubs the user created or has written to: membership is recorded on the authority's PDS. A new member therefore joins with an invite link, /join/<authority DID>/<space key> (see src/lib/invite.ts), which maps back to the space URI. The link survives the OAuth redirect in localStorage, and the app remembers the club until the member's first review.

Names. A space has no name of its own: its key is part of its URI, so it can't change. The club's name and description are an info record the host writes into their repo in the space, which every member already reads. Renaming is a put of that record. The sidebar needs each club's name before it's opened, which costs a credential per club; names are cached in localStorage (cleared on sign-out, since they're private to members).