How bluesky-social/atproto works
Major Components
• Core Packages: These are the foundational libraries chiefly under the “@atproto/*” namespace. For example:
• @atproto/api – the client library for API consumption.
• @atproto/common and @atproto/common-web – shared utilities (one for Node environments, one for browsers).
• @atproto/crypto – for cryptographic signing and key management.
• @atproto/identity – DID and handle resolution.
• @atproto/lexicon – which provides the schema definition language (think similar to JSON Schema/OpenAPI for AT Protocol).
• @atproto/repo – for data storage structures, involving MST (Merkle Search Trees) and related repository functionality.
• @atproto/syntax – for identifier parsing.
• @atproto/xrpc and @atproto/xrpc-server – for HTTP API helpers (client- and server-side, respectively).
• Higher-Level Services: These are essentially wrappers built on top of these libraries that implement actual protocol endpoints or business logic:
• PDS (“Personal Data Server”): Hosts the repository content for atproto accounts. Implementation code is primarily under packages/pds and its runtime is found in services/pds.
• Bsky (“AppView service”): Implements the app.bsky.* APIs and is the backend for Bluesky’s social app. Its code is largely in packages/bsky; the service is wrapped under services/bsky.
• Other supportive services like bsync, ozone (a service likely related to communications, moderation, or real-time processing), etc.
• Lexicons and Interop Test Files:
• Lexicons reside under the “lexicons” directory. They specify schemas for two major namespaces – “com.atproto.*” and “app.bsky.*”. They play a critical role in API validation and message consistency.
• The interoperability test data under “interop-test-files” provide language-neutral tests that ensure that any implementation stays aligned with the protocol specifications.
Relationships and Interactions
• The core packages provide shared functionality that is consumed by both the services and client libraries.
• The client library (@atproto/api) is built on top of the xrpc layer and lexicon schemas for API communication.
• The services (e.g., PDS and AppView/Bsky) integrate core packages to expose HTTP endpoints and business logic. Their implementations also rely on common packages for cryptography, identity resolution, and repo management.
• External interactions include communications with a browser or mobile client (via the API clients) and interfacing with other network peers according to the AT protocol. Additionally, Dockerfiles and deployment scripts indicate containerization for deployment.
Architectural Patterns and Principles
• Modular / Micro-Module Architecture: Each package encapsulates a distinct concern (e.g., crypto, identity, lexicon, repo, syntax) and is built to be reusable.
• Separation of Concerns: Distinct services (PDS for personal data management and Bsky for application-facing endpoints) encapsulate different parts of the system.
• Clear API Contracts: Lexicons are used as the formal schema for API requests and responses ensuring strong data contracts.
• Use of Containers & CI/CD: The presence of Dockerfiles and GitHub workflows in the file tree implies containerized environments and automated builds/deployments.
• Test-Driven and Interop Coverage: The large number of tests and interoperability test files help guarantee protocol compliance.
Components
• Service Layers:
• PDS Service: Represent this as a container or microservice that integrates repo management, account management, and interacts with external clients.
• Bsky Service: Represent as another microservice handling AppView APIs, feed processing, notifications, and moderation.
• Lexicon and Interop: Show a repository of JSON schema definitions that both the services (server-side) and client libraries depend upon.
• Datastores & Persistence: Although not immediately visible in every package, there are many DB migration files and schema definitions (e.g., under packages/bsky and packages/pds) – add a database (or multiple databases) that the services interact with.
• CI/CD/Build & Infrastructure: Represent Docker, GitHub workflows, and deployment files that manage automated builds, testing, and container orchestration.