# bluesky-social/atproto architecture

> Architecture diagram of the GitHub repository bluesky-social/atproto, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bluesky-social/atproto
- Repository: https://github.com/bluesky-social/atproto

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External & Client Layer
    subgraph "External & Client Layer"
        EC["External Clients (Web/Mobile)"]:::client
        API["API Library (@atproto/api)"]:::client
        XRPC_CLIENT["XRPC Client (@atproto/xrpc)"]:::client
        XRPC_SERVER["XRPC Server (@atproto/xrpc-server)"]:::library
    end

    EC -->|"APIcalls"| API
    API -->|"uses"| XRPC_CLIENT
    XRPC_CLIENT -->|"calls"| XRPC_SERVER

    %% Core Packages
    subgraph "Core Packages"
        COMMON["Common (@atproto/common)"]:::library
        COMMON_WEB["Common-Web (@atproto/common-web)"]:::library
        CRYPTO["Crypto (@atproto/crypto)"]:::library
        IDENTITY["Identity (@atproto/identity)"]:::library
        LEXICON["Lexicon (@atproto/lexicon)"]:::library
        REPO["Repo (@atproto/repo)"]:::library
        SYNTAX["Syntax (@atproto/syntax)"]:::library
    end

    %% Service Layers
    subgraph "Service Layers"
        %% PDS Service
        subgraph "PDS Service"
            PDS_CORE["PDS Core (packages/pds)"]:::service
            PDS_WRAPPER["PDS Wrapper (services/pds)"]:::service
            PDS_CORE --> PDS_WRAPPER
        end
        %% Bsky Service
        subgraph "Bsky Service"
            BSKY_CORE["Bsky Core (packages/bsky)"]:::service
            BSKY_WRAPPER["Bsky Wrapper (services/bsky)"]:::service
            BSKY_CORE --> BSKY_WRAPPER
        end
        %% Bsync Service
        subgraph "Bsync Service"
            BSYNC_CORE["Bsync Core (packages/bsync)"]:::service
            BSYNC_WRAPPER["Bsync Wrapper (services/bsync)"]:::service
            BSYNC_CORE --> BSYNC_WRAPPER
        end
        %% Ozone Service
        subgraph "Ozone Service"
            OZONE_CORE["Ozone Core (packages/ozone)"]:::service
            OZONE_WRAPPER["Ozone Wrapper (services/ozone)"]:::service
            OZONE_CORE --> OZONE_WRAPPER
        end
    end

    %% Schemas & Tests
    subgraph "Schemas & Tests"
        LEXICONS["Lexicons (Schemas)"]:::schema
        INTEROP["Interop Test Files"]:::schema
    end

    %% Infrastructure
    INFRA["CI/CD & Docker"]:::infra

    %% Relationships between layers
    XRPC_SERVER -->|"exposes"| PDS_WRAPPER
    XRPC_SERVER -->|"exposes"| BSKY_WRAPPER
    XRPC_SERVER -->|"exposes"| BSYNC_WRAPPER
    XRPC_SERVER -->|"exposes"| OZONE_WRAPPER

    %% Service wrappers using core libraries
    PDS_WRAPPER ---|"uses"| CRYPTO
    PDS_WRAPPER ---|"uses"| IDENTITY
    PDS_WRAPPER ---|"uses"| REPO
    PDS_WRAPPER ---|"validatesWith"| LEXICON

    BSKY_WRAPPER ---|"uses"| CRYPTO
    BSKY_WRAPPER ---|"uses"| IDENTITY
    BSKY_WRAPPER ---|"uses"| REPO
    BSKY_WRAPPER ---|"validatesWith"| LEXICON

    BSYNC_WRAPPER ---|"uses"| CRYPTO
    BSYNC_WRAPPER ---|"uses"| IDENTITY
    BSYNC_WRAPPER ---|"uses"| REPO
    BSYNC_WRAPPER ---|"validatesWith"| LEXICON

    OZONE_WRAPPER ---|"uses"| CRYPTO
    OZONE_WRAPPER ---|"uses"| IDENTITY
    OZONE_WRAPPER ---|"uses"| REPO
    OZONE_WRAPPER ---|"validatesWith"| LEXICON

    %% Lexicon relation to schemas
    LEXICON -->|"defines"| LEXICONS
    INTEROP -->|"tests"| LEXICONS

    %% Infrastructure supports the entire system
    INFRA ---|"build/deploy"| EC
    INFRA ---|"build/deploy"| API
    INFRA ---|"build/deploy"| XRPC_SERVER
    INFRA ---|"build/deploy"| PDS_WRAPPER
    INFRA ---|"build/deploy"| BSKY_WRAPPER
    INFRA ---|"build/deploy"| BSYNC_WRAPPER
    INFRA ---|"build/deploy"| OZONE_WRAPPER

    %% Class Definitions
    classDef library fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef service fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef schema fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef infra fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;
    classDef client fill:#f8d7da,stroke:#721c24,stroke-width:2px;

    %% Click Events
    click API "https://github.com/bluesky-social/atproto/tree/main/packages/api"
    click COMMON "https://github.com/bluesky-social/atproto/tree/main/packages/common"
    click COMMON_WEB "https://github.com/bluesky-social/atproto/tree/main/packages/common-web"
    click CRYPTO "https://github.com/bluesky-social/atproto/tree/main/packages/crypto"
    click IDENTITY "https://github.com/bluesky-social/atproto/tree/main/packages/identity"
    click LEXICON "https://github.com/bluesky-social/atproto/tree/main/packages/lexicon"
    click REPO "https://github.com/bluesky-social/atproto/tree/main/packages/repo"
    click SYNTAX "https://github.com/bluesky-social/atproto/tree/main/packages/syntax"
    click XRPC_CLIENT "https://github.com/bluesky-social/atproto/tree/main/packages/xrpc"
    click XRPC_SERVER "https://github.com/bluesky-social/atproto/tree/main/packages/xrpc-server"
    click PDS_CORE "https://github.com/bluesky-social/atproto/tree/main/packages/pds"
    click PDS_WRAPPER "https://github.com/bluesky-social/atproto/tree/main/services/pds"
    click BSKY_CORE "https://github.com/bluesky-social/atproto/tree/main/packages/bsky"
    click BSKY_WRAPPER "https://github.com/bluesky-social/atproto/tree/main/services/bsky"
    click BSYNC_CORE "https://github.com/bluesky-social/atproto/tree/main/packages/bsync"
    click BSYNC_WRAPPER "https://github.com/bluesky-social/atproto/tree/main/services/bsync"
    click OZONE_CORE "https://github.com/bluesky-social/atproto/tree/main/packages/ozone"
    click OZONE_WRAPPER "https://github.com/bluesky-social/atproto/tree/main/services/ozone"
    click LEXICONS "https://github.com/bluesky-social/atproto/tree/main/lexicons"
    click INTEROP "https://github.com/bluesky-social/atproto/tree/main/interop-test-files"
    click INFRA "https://github.com/bluesky-social/atproto/blob/main/pnpm-workspace.yaml"
```
