Glossary
Key terms used throughout the HappyView documentation. For a broader introduction to the atproto, see the official ATProto glossary.
atproto terms
AppView — A backend service that indexes atproto records and serves them through an API. HappyView is an AppView. See the ATProto docs for more.
DID (Decentralized Identifier) — A persistent, globally unique identifier for an account (e.g. did:plc:abc123).
Firehose — A real-time stream of all record events (creates, updates, deletes) across the atproto network. HappyView consumes a filtered slice of this via Jetstream.
Handle — A human-readable name for an account (e.g. user.bsky.social). Handles resolve to a DID via a DNS TXT record or an HTTP .well-known/atproto-did lookup.
Lexicon — A schema definition for atproto data types and API methods. Lexicons define what records look like, what endpoints exist, and what parameters they accept. See Lexicons.
NSID (Namespaced Identifier) — A reverse-DNS identifier for a lexicon (e.g. xyz.statusphere.status). The authority is everything except the last segment.
PDS (Personal Data Server) — The server that hosts a user's data. Users can be on any PDS — there's no single server. HappyView proxies writes back to each user's PDS.
PLC directory — A public service (e.g. plc.directory) that maps DIDs to their DID documents, which contain the user's PDS endpoint and other metadata.
Record — A single piece of data in an atproto repository, identified by an AT URI (e.g. at://did:plc:abc/xyz.statusphere.status/abc123).
Relay — A network service that aggregates repository data from many PDSes. HappyView queries the relay during backfill to discover which repos contain records for a given collection, then fetches each repo's records directly from its PDS.
rkey (Record Key) — The unique key for a record within a collection and repo. These are most commonly TIDs (timestamp-based) or NSIDs.
TID (Timestamp Identifier) — A 13-character sortable identifier used as a record key. Generated from the current timestamp.
XRPC — The HTTP-based RPC protocol used by the atproto. Query methods map to GET requests, procedure methods map to POST requests. See XRPC API.
Jetstream — A filtered firehose that delivers atproto record commit events as JSON over WebSocket. Not part of the core atproto spec, but widely used. HappyView subscribes to Jetstream with a collection filter built from its indexed record lexicons, and persists a cursor for resume on reconnect.
HappyView-specific terms
Backfill — The process of bulk-indexing existing records from the network. HappyView discovers repos via the relay and fetches each repo's records directly from its PDS. Runs when a new record-type lexicon is uploaded or triggered manually. See Backfill.
Network lexicon — A lexicon fetched directly from the atproto network via DNS authority resolution, rather than uploaded manually. See Lexicons - Network lexicons.
Permission — A granular access control right that authorizes a specific action in the admin API. HappyView defines 20 permissions organized by category (e.g. lexicons:create, users:read). See Permissions.
Permission template — A predefined set of permissions that can be applied when creating a user. Templates are: Viewer (read-only access), Operator (viewer + backfill and API key management), Manager (operator + lexicon and record management), and Full Access (all 20 permissions).
Super user — The bootstrapped user created on first login to a fresh HappyView instance. The super user has unrestricted access to all endpoints regardless of permissions, can transfer super status to another user, and cannot be deleted.
Target collection — The record collection that a query or procedure lexicon operates on. Set via the target_collection field when uploading a lexicon.