# marshalx/atproto architecture

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

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

## Overview

##### Main Components

a. Core Packages (represented as major modules):
- atproto_client: Main XRPC client implementation
- atproto_core: Core functionality (NSID, URI, CID handling)
- atproto_crypto: Cryptographic operations
- atproto_firehose: Data streaming capabilities
- atproto_identity: Identity resolution
- atproto_lexicon: Protocol lexicon parsing
- atproto_server: Server-side utilities

b. External Integration Points:
- Bluesky API
- AT Protocol Network
- PLC Directory
- DID Web
- Client Applications

##### Architecture Layers

Top to Bottom:
##### Client Interface Layer
- Sync Client
- Async Client
- High-level API methods
- Raw API methods

##### Service Layer
- XRPC Communication
- Authentication
- Session Management
- Data Streaming

##### Core Processing Layer
- Lexicon Processing
- Model Generation
- Identity Resolution
- Cryptographic Operations

##### Data Model Layer
- Generated Models
- Record Types
- Response Types
- Common Types

##### Key Relationships

**Client Applications**
- ↓
**High-level Client Interface**
- ↓
**XRPC Client (Sync/Async)**
- ↙     ↓     ↘
**Identity  Repo  Firehose**
- ↓      ↓      ↓
**Core Services (Crypto, URI, CID)**
- ↓
**AT Protocol Network**

##### Implementation Details

- Modular architecture with clear separation of concerns
- Both sync and async client implementations
- Automatic code generation from lexicons
- Multiple abstraction levels (high-level vs low-level API)
- External service integration points

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Client["Client Applications"]
        App[Client Application]:::client
    end

    subgraph Interface["Client Interface Layer"]
        SyncClient["Sync Client"]:::interface
        AsyncClient["Async Client"]:::interface
        HighLevel["High-level API"]:::interface
        RawAPI["Raw API Methods"]:::interface
    end

    subgraph Service["Service Layer"]
        XRPC["XRPC Communication"]:::service
        Auth["Authentication"]:::service
        Session["Session Management"]:::service
        Stream["Data Streaming"]:::service
    end

    subgraph Core["Core Processing Layer"]
        Lexicon["Lexicon Processing"]:::core
        Models["Model Generation"]:::core
        Identity["Identity Resolution"]:::core
        Crypto["Cryptographic Operations"]:::core
        CoreUtils["Core Utilities"]:::core
    end

    subgraph External["External Services"]
        ATP["AT Protocol Network"]:::external
        PLC["PLC Directory"]:::external
        DIDWeb["DID Web"]:::external
        Bluesky["Bluesky API"]:::external
    end

    %% Relationships
    App --> SyncClient & AsyncClient
    SyncClient & AsyncClient --> HighLevel
    HighLevel --> RawAPI
    RawAPI --> XRPC
    XRPC --> Auth & Session & Stream
    Auth & Session & Stream --> Lexicon & Models & Identity & Crypto & CoreUtils
    Identity --> PLC & DIDWeb
    CoreUtils --> ATP
    ATP --> Bluesky

    %% Click Events
    click SyncClient "https://github.com/MarshalX/atproto/blob/main/packages/atproto_client/client/client.py"
    click AsyncClient "https://github.com/MarshalX/atproto/blob/main/packages/atproto_client/client/async_client.py"
    click Identity "https://github.com/MarshalX/atproto/tree/main/packages/atproto_identity"
    click Crypto "https://github.com/MarshalX/atproto/tree/main/packages/atproto_crypto"
    click Stream "https://github.com/MarshalX/atproto/blob/main/packages/atproto_firehose/firehose.py"
    click Lexicon "https://github.com/MarshalX/atproto/tree/main/packages/atproto_lexicon"
    click Models "https://github.com/MarshalX/atproto/blob/main/packages/atproto_codegen/models/generator.py"
    click Auth "https://github.com/MarshalX/atproto/tree/main/packages/atproto_server/auth"
    click CoreUtils "https://github.com/MarshalX/atproto/tree/main/packages/atproto_core"

    %% Styles
    classDef client fill:#f9f,stroke:#333,stroke-width:2px
    classDef interface fill:#ff9,stroke:#333,stroke-width:2px
    classDef service fill:#9cf,stroke:#333,stroke-width:2px
    classDef core fill:#9f9,stroke:#333,stroke-width:2px
    classDef external fill:#ddd,stroke:#333,stroke-width:2px

    %% Legend
    subgraph Legend
        Client1[Client]:::client
        Interface1[Interface]:::interface
        Service1[Service]:::service
        Core1[Core]:::core
        External1[External]:::external
    end
```
