atjamalpha

Developer documentation

For developers building on atjam, or extending it for their own domain.

These docs cover the at.atjam.* data contract and the @atjam/lexicons reference implementation that ships alongside it. If you just want the wire schemas and the records table, see the package README. For getting the schemas onto the AT Protocol network, see PUBLISHING.md.

The mental model

Three ideas carry most of the weight:

  1. atjam coordinates; you bring your own deliverable records. A submission strong-refs a record on whatever app already owns the data — a fm.plyr.track, an app.bsky.feed.post, a site.standard.document. atjam does not host audio, video, or posts. (Design principle #1.)
  2. The contract is the on-network schemas. The five at.atjam.* lexicons are published as com.atproto.lexicon.schema records on the authority DID, resolvable network-wide via the _lexicon.atjam.at DNS record — ATProto's standard lexicon-resolution mechanism. To use them, resolve the NSID the way ATProto SDKs do: the DNS record gives the authority DID, then you fetch at://<did>/com.atproto.lexicon.schema/at.atjam.round and generate types in any language — automated by tools like goat or @atproto/lexicon-resolver. (The @atjam/lexicons TypeScript package is just this repo's reference implementation: "private", not on npm. The schemas are the contract.)
  3. There's no central database — records live on their authors' PDSes. Each of the five record types is written by whoever creates it, on their own PDS; no server owns the whole graph. Reads stitch the records back together with a backlinks index (Constellation) plus per-DID PDS reads.

The five records

NSIDWritten byPurpose
at.atjam.jamorganizerContainer for a recurring or one-shot challenge.
at.atjam.roundorganizerOne instance: assignment, milestones, accepted submission types, join policy.
at.atjam.signupparticipantIntent to take part in a round.
at.atjam.invitationinviterAuthorizes a specific DID to join a hosted/network round.
at.atjam.submissionparticipantStrong-ref to a deliverable on another app.

See the records table in the package README for the wire-level field reference.

Find what you need

These docs are organized by the four kinds of developer need (Diátaxis).

  • Tutorial — Getting started: one guided path from reading a round to writing your first jam, round, and signup.
  • How-to — Reading, writing, validating: recipes for each read and write, plus signup validation and eligibility.
  • How-to — Extending atjam: the headline guide — adopt atjam for your own domain via the open extension points (the EPTSS pattern).
  • Explanation — Using the lexicons: integration overview, schemas-as-contract, the private-package reality, configuring the read layer.
  • Showcase — Built on atjam: real adopters, plus an end-to-end worked example mapping a judged, votable game jam onto the extension points.
  • Reference — API reference: every public export of @atjam/lexicons with exact signatures.

New here? Start with the Tutorial.