Developer documentation

These docs are for developers building on atjam, or extending it for their own domain. They 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:

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.)
The contract is the on-network schemas. The 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.)
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

NSID	Written by	Purpose
`at.atjam.jam`	organizer	Container for a recurring or one-shot challenge.
`at.atjam.round`	organizer	One instance: assignment, milestones, accepted submission types, join policy.
`at.atjam.signup`	participant	Intent to take part in a round.
`at.atjam.invitation`	inviter	Authorizes a specific DID to join a `hosted`/`network` round.
`at.atjam.submission`	participant	Strong-ref to a deliverable on another app.

A sixth schema, at.atjam.playlist, sits beside these: an ordered list of strong-refs to records of any collection. It isn't part of a jam's lifecycle.

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

Find what you need (Diátaxis)

These docs are organized by the four kinds of developer need.

	Learning-oriented	Task-oriented
Practical steps	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).
Understanding	Explanation + How-to — Using the lexicons: integration overview, schemas-as-contract, the private-package reality, configuring the read layer.
	What atjam depends on: the shared services under atjam, and what breaks when each one is gone.
Showcase	Built on atjam: real adopters, plus an end-to-end worked example mapping a judged, votable game jam onto the extension points.
Information		Reference — API reference: every public export of `@atjam/lexicons` with exact signatures.

New here? Start with the Tutorial.