solpbc.org / vit
open source is social v-it.org
fork atom
vit / ARCHITECTURE.md
at main 3.3 kB view raw view code
Jer Miller Increase cap text limits to match skill lexicon
314935b8

architecture#

record types#

vit uses ATProto records stored in each user's PDS repository. three record types are used:

record type NSID custom? key purpose
cap org.v-it.cap yes tid structured change description
vouch org.v-it.vouch yes tid endorse a cap
follow app.bsky.graph.follow no (reused) tid subscribe to a handle

why caps use a custom NSID#

caps are structurally similar to Bluesky posts (app.bsky.feed.post) but serve a different purpose. using a custom NSID (org.v-it.cap) ensures:

  • caps live in their own collection (org.v-it.cap) and never appear in a user's Bluesky post feed.
  • Bluesky AppViews and feed generators ignore cap records (unknown collection).
  • vit tooling can query caps independently without filtering out posts.
  • the cap schema can evolve independently of app.bsky.feed.post.

why follows are reused#

app.bsky.graph.follow is generic enough to use as-is:

  • a follow's subject is a DID — it works regardless of what record types the followed account publishes.
  • reusing the official follow lexicon means follows are visible in Bluesky clients, which is useful for cross-network discoverability.

cap lexicon#

the cap lexicon (lexicons/org/v-it/cap.json) mirrors app.bsky.feed.post with these differences:

  • NSID: org.v-it.cap instead of app.bsky.feed.post.
  • deprecated fields removed: entities and textSlice are not carried over.
  • self-referencing replies: reply references org.v-it.cap#replyRef, so cap threads are self-contained.
  • descriptions updated: all description strings reference "cap" instead of "post".

fields carried over from app.bsky.feed.post and their cap-context meaning:

field type cap meaning
text string (max 50000 bytes / 15000 graphemes) primary cap content
facets array of app.bsky.richtext.facet rich text annotations (mentions, URLs, hashtags)
reply org.v-it.cap#replyRef thread structure (parent + root refs)
embed union of app.bsky.embed.* attached media, links, or record embeds
langs array of language strings (max 3) content language hints
labels com.atproto.label.defs#selfLabels content warnings
tags array of strings (max 8) additional hashtags
beacon string (max 512 bytes) beacon URI scoping this cap to a project
createdAt datetime client-declared creation timestamp

relationship to VOCAB.md#

VOCAB.md defines a cap as a markdown document containing free-form instructions for implementing a change — with sections for intent, scope, risk, implementation guide, and other context. the current lexicon mirrors app.bsky.feed.post, so most cap semantics are encoded in text, tags, threading, and embeds. beacon is a dedicated structured field for project scoping.

directory layout#

lexicon JSON files follow the NSID-to-path convention:

lexicons/
  org/
    v-it/
      cap.json            # org.v-it.cap
      vouch.json          # org.v-it.vouch

this mirrors the convention used in the ATProto repository.

future work#

  • provenance tracking across vet, remix, vouch, and ship lineage.