Skip to content

pubky.app

Markdown

pubky.app is a social application and reference implementation built on the Pubky protocol. People publish posts, follow one another, and discover content through feeds and tags. Developers can study how it combines user-controlled storage with an indexed social graph and a responsive web interface.

Tags and perspectives

Section titled “Tags and perspectives”

Tags are free-text labels people apply to profiles and posts, including those written by someone else. Each annotation records who applied the label and what it describes. A post might be tagged tutorial by one reader and privacy by another; those labels add context beyond a single like count.

Perspectives are saved views of a feed, combining filters and presentation settings. They let readers return to a particular view of the social data. Tags and follow relationships provide the building blocks for the broader semantic social graph.

Bookmarks are public social records. Treat bookmarked links as public data.

Reference architecture

Section titled “Reference architecture”

The application separates publishing, indexing, and presentation:

  1. The frontend keeps data locally. Its browser database holds records and feed data so the interface can show cached content and respond to user actions promptly.
  2. Users publish to Homeservers. The SDK writes social records using the user’s authorization. The records follow pubky-app-specs so other compatible apps can understand them.
  3. Nexus follows changes. Homeserver event feeds let Nexus discover updates, fetch public records, and index content and relationships across users.
  4. The frontend refreshes from Nexus. Indexed results update the local cache, which the interface reads to present feeds, profiles, and search results.

Local changes and indexed views do not become visible everywhere at once: the Homeserver write and subsequent Nexus indexing must complete. The local-first design explains the read, write, and refresh behavior in detail.

Building on the same data

Section titled “Building on the same data”

Another app can reuse the social data without adopting pubky.app’s interface. It can read known records directly from Homeservers, query Nexus for indexed views, and contribute compatible records with the user’s authorization. For example, a topic reader could use existing profiles and follow relationships while presenting a different feed.

pubky-app-specs defines the shared data model that makes this interoperability possible. Its Universal Tags let people label resources beyond pubky.app posts and profiles, such as an article tagged tutorial, so apps can discover both resources and the people who tagged them.

Choose the pieces your app needs; the app architecture guide covers the alternatives.

For development and integration, see: