ActivityPub Diagrams v1.0

Creative Commons Attribution 4.0 International License (CC BY 4.0)

This article presents a series of visual representations that break down ActivityPub’s complex architecture and workflows, originally created during my personal exploration of federated networks. While developing these diagrams for my own understanding, they’ve proven invaluable in grasping ActivityPub’s core concepts and federation mechanisms. The diagrams focus on architectural components and workflows, but are part of my broader research journey into practical challenges like spam prevention, database design, concurrency handling, protocol compliance, and operational concerns like monitoring and load balancing. Future articles will explore these critical aspects, including content moderation strategies. For now, these diagrams serve as my foundation for understanding ActivityPub’s key components and their interactions in decentralized social networks.

1. ActivityPub Implementation Architecture

This diagram provides a detailed view of an ActivityPub implementation’s technical infrastructure, focusing on critical operational aspects. It highlights how different components interact through caching layers, asynchronous processing, and error handling mechanisms. The diagram is particularly useful for understanding how to build a robust, production-ready ActivityPub service that can handle scaling challenges. Note that while this represents the core architecture, practical implementations should also consider database schema design, monitoring solutions, and content moderation workflows.

2. ActivityPub System Architecture

This comprehensive diagram illustrates the core social networking features and their integration with ActivityPub protocols. It demonstrates how user actions flow through the system, from client interface to federation endpoints, emphasizing security layers and WebSub implementation. The visual organization helps understand how different components work together to create a cohesive social networking platform. While focusing on protocol flows, implementers should also consider data persistence strategies and API versioning approaches.

3. ActivityPub System Architecture (Detailed View)

This detailed workflow diagram emphasizes the practical implementation aspects of ActivityPub, particularly focusing on media handling and real-time updates. It shows how activities flow from client actions through federation, including error handling at various stages. The diagram highlights critical integration points between different system components, though additional consideration should be given to content moderation frameworks and scaling strategies.

4. ActivityPub Core Workflow and Security

This final diagram focuses on the security aspects and core processing workflow of ActivityPub implementations. It demonstrates how activities are created, validated, and distributed while maintaining security through signature verification and access control. The diagram emphasizes error handling and stream processing, though production implementations will need additional considerations for rate limiting strategies and authentication mechanisms.

Future Considerations

As these diagrams evolve, future iterations and articles will address:

• Database schema patterns optimized for ActivityPub data structures
• Scaling strategies for high-traffic instances
• Monitoring and observability implementations
• Content moderation workflows and tools
• API versioning and evolution approaches
• Federation protocol compliance verification
• Migration strategies for system updates
• Load balancing and high availability patterns

These aspects will be crucial for moving from architectural understanding to practical implementation.

ActivityPub Architecture: Raw mermaid diagram

Note: These diagrams were created for personal learning and private usage. While I’ve strived for accuracy, they represent my understanding of ActivityPub as an amateur enthusiast and should not be considered an authoritative reference.

This is taken from private repository which contains raw Mermaid diagram definitions for visualizing ActivityPub architecture and workflows. These diagrams are compatible with GitHub Markdown rendering, Hugo static site generator (with Mermaid support), and standard Mermaid.js libraries. Each diagram can be directly used in documentation, technical specs, or educational materials about ActivityPub implementations.

The primary goals of sharing these raw diagrams are:

• Providing ready-to-use technical visualizations for ActivityPub architecture
• Ensuring compatibility across different Mermaid renderers
• Making it easier to understand federation workflows through visual representation
• Offering a base template that others can modify for their needs

graph TD
    classDef objectModel fill:#e3f2fd,stroke:#1565c0
    classDef clientActions fill:#e1f5fe,stroke:#01579b
    classDef mediaHandling fill:#fff3e0,stroke:#ef6c00
    classDef activityTypes fill:#f3e5f5,stroke:#7b1fa2
    classDef federation fill:#e8f5e9,stroke:#2e7d32
    classDef security fill:#fce4ec,stroke:#c2185b
    classDef caching fill:#f5f5f5,stroke:#616161
    classDef async fill:#ede7f6,stroke:#4527a0
    classDef error fill:#ffebee,stroke:#b71c1c
    classDef extensions fill:#e0f7fa,stroke:#006064

    subgraph "Client-Side Caching"
        CC1[Browser Cache]:::caching
        CC2[Service Worker]:::caching
        CC3[IndexedDB]:::caching
        CC4[Cache Strategy]:::caching
    end

    subgraph "Server-Side Caching"
        SC1[Redis Cache]:::caching
        SC2[CDN]:::caching
        SC3[HTTP Cache]:::caching
        SC4[Cache Invalidation]:::caching
    end

    subgraph "Async Processing"
        AQ1[Message Queue]:::async
        AQ2[Task Workers]:::async
        AQ3[Background Jobs]:::async
        AQ4[Event Bus]:::async
    end

    subgraph "Error Handling"
        EH1[Retry Logic]:::error
        EH2[Circuit Breaker]:::error
        EH3[Dead Letter Queue]:::error
        EH4[Error Reporting]:::error
        EH5[Exponential Backoff]:::error
    end

    subgraph "ActivityPub Extensions"
        EX1[Custom Activities]:::extensions
        EX2[Reactions]:::extensions
        EX3[Groups]:::extensions
        EX4[Lists]:::extensions
        EX5[Events]:::extensions
    end

    subgraph "Core ActivityPub"
        AP1[Object Model]:::objectModel
        AP2[Activity Types]:::activityTypes
        AP3[Federation]:::federation
        AP4[Media Handling]:::mediaHandling
    end

    %% Client Flow
    CC1 & CC2 & CC3 -->|Cache Strategy| CC4
    CC4 -->|Fresh Content| CLI[Client Interface]
    CLI -->|Request| AP1

    %% Server Flow
    AP1 -->|Process| AQ1
    AQ1 -->|Distribute| AQ2
    AQ2 -->|Execute| AQ3
    AQ3 -->|Publish| AQ4

    %% Caching Flow
    AQ4 -->|Cache| SC1
    SC1 -->|Distribute| SC2
    SC2 -->|Serve| SC3
    SC3 -->|Invalidate| SC4

    %% Error Flow
    AQ2 -->|Fail| EH1
    EH1 -->|Retry| EH5
    EH5 -->|Circuit Break| EH2
    EH2 -->|Dead Letter| EH3
    EH3 -->|Report| EH4

    %% Extensions Flow
    AP1 -->|Extend| EX1
    EX1 -->|Support| EX2 & EX3 & EX4 & EX5

    %% Federation Flow
    AP1 -->|Federate| AP3
    AP3 -->|Queue| AQ1
    AP3 -->|Cache| SC1
    AP3 -->|Handle Errors| EH1

graph TD
    classDef objectModel fill:#e3f2fd,stroke:#1565c0
    classDef clientActions fill:#e1f5fe,stroke:#01579b
    classDef mediaHandling fill:#fff3e0,stroke:#ef6c00
    classDef activityTypes fill:#f3e5f5,stroke:#7b1fa2
    classDef federation fill:#e8f5e9,stroke:#2e7d32
    classDef security fill:#fce4ec,stroke:#c2185b
    classDef streams fill:#f1f8e9,stroke:#558b2f
    classDef webSub fill:#fff8e1,stroke:#ff8f00

    subgraph "ActivityPub Object Model"
        OBJ[Activity Object]:::objectModel
        OBJ -->|properties| OBJ1[type]:::objectModel
        OBJ -->|properties| OBJ2[actor]:::objectModel
        OBJ -->|properties| OBJ3[object]:::objectModel
        OBJ -->|properties| OBJ4[published]:::objectModel
        OBJ -->|properties| OBJ5[@context]:::objectModel
    end

    subgraph "Client Interface"
        CLI1[Browse Timeline]:::clientActions
        CLI2[Search Content]:::clientActions
        CLI3[Post/Reply]:::clientActions
        CLI4[Interact]:::clientActions
        CLI5[Follow/Unfollow]:::clientActions
    end

    subgraph "Activity Types"
        AT1[Create]:::activityTypes
        AT2[Update]:::activityTypes
        AT3[Delete]:::activityTypes
        AT4[Like]:::activityTypes
        AT5[Follow]:::activityTypes
        AT6[Announce]:::activityTypes
    end

    subgraph "Security Layer"
        SEC1[HTTP Signatures]:::security
        SEC2[Public Key Crypto]:::security
        SEC3[Access Control]:::security
        SEC4[Rate Limiting]:::security
    end

    subgraph "WebSub Implementation"
        WS1[Hub Discovery]:::webSub
        WS2[Subscribe]:::webSub
        WS3[Verify Intent]:::webSub
        WS4[Deliver Updates]:::webSub
        WS5[Unsubscribe]:::webSub
    end

    subgraph "Activity Streams"
        STR1[Home Timeline]:::streams
        STR2[Public Timeline]:::streams
        STR3[Notifications]:::streams
        STR4[Content Filter]:::streams
        STR5[Personalization]:::streams
    end

    subgraph "Media Processing"
        MED1[Upload Handler]:::mediaHandling
        MED2[Process Media]:::mediaHandling
        MED3[Generate Preview]:::mediaHandling
        MED4[CDN Storage]:::mediaHandling
    end

    subgraph "Federation"
        FED1[WebFinger]:::federation
        FED2[Actor Resolution]:::federation
        FED3[Key Exchange]:::federation
        FED4[Activity Delivery]:::federation
    end

    CLI1 & CLI2 --> STR1 & STR2 & STR3
    CLI3 & CLI4 & CLI5 --> AT1 & AT2 & AT3 & AT4 & AT5 & AT6
    AT1 & AT2 & AT3 & AT4 & AT5 & AT6 --> OBJ
    
    CLI3 -->|Upload| MED1
    MED1 --> MED2 --> MED3 --> MED4
    MED4 -->|Attach| OBJ

    OBJ -->|Verify| SEC1 & SEC2
    SEC1 & SEC2 -->|Allow| SEC3
    SEC3 -->|Check| SEC4

    SEC4 -->|Approved| FED4
    FED4 -->|Discover| FED1
    FED1 -->|Resolve| FED2
    FED2 -->|Exchange| FED3

    FED4 -->|Notify| WS1
    WS1 --> WS2 --> WS3 --> WS4
    WS4 -->|Updates| STR1 & STR2 & STR3
    STR1 & STR2 & STR3 -->|Apply| STR4
    STR4 -->|Customize| STR5

graph TD
    classDef clientActions fill:#e1f5fe,stroke:#01579b
    classDef mediaHandling fill:#fff3e0,stroke:#ef6c00
    classDef activityTypes fill:#f3e5f5,stroke:#7b1fa2
    classDef federation fill:#e8f5e9,stroke:#2e7d32
    classDef errorHandling fill:#ffebee,stroke:#c62828

    subgraph "Client Actions"
        CA1[Post Content]:::clientActions
        CA2[Like/React]:::clientActions
        CA3[Follow/Unfollow]:::clientActions
        CA4[Share/Boost]:::clientActions
    end

    subgraph "Activity Types"
        AT1[Create]:::activityTypes
        AT2[Update]:::activityTypes
        AT3[Delete]:::activityTypes
        AT4[Like]:::activityTypes
        AT5[Follow]:::activityTypes
        AT6[Announce]:::activityTypes
    end

    subgraph "Media Handling"
        MH1[Upload Media]:::mediaHandling
        MH2[Process Media]:::mediaHandling
        MH3[Store Media]:::mediaHandling
        MH4[Generate Preview]:::mediaHandling
    end

    subgraph "Server A (Origin)"
        CA1 & CA2 & CA3 & CA4 -->|Trigger| AT1 & AT2 & AT3 & AT4 & AT5 & AT6
        AT1 & AT2 & AT3 & AT4 & AT5 & AT6 -->|Create| ACT[Activity Creation]
        ACT -->|Sign| OUT[Server A Outbox]
        OUT -->|Distribute| DIST[Distribution]
    end

    subgraph "Federation & Real-time"
        WS[WebSub Hub]:::federation
        DIST -->|Notify| WS
        WS -->|Push Updates| SUB[Subscribers]
        
        FED1[WebFinger]:::federation -->|Discover| FED2[Actor Resolution]
        FED2 -->|Fetch| FED3[Public Key Exchange]
    end

    subgraph "Media Federation"
        MH1 -->|Process| MH2
        MH2 -->|Store| MH3
        MH3 -->|Preview| MH4
        MH4 -->|Attach to Activity| ACT
        DIST -->|Media URLs| REM[Remote Servers]
        REM -->|Fetch Media| MH3
    end

    subgraph "Server B (Remote)"
        INB[Server B Inbox]:::federation
        DIST -->|Deliver| INB
        INB -->|Verify| FED3
        INB -->|Process| PROC[Activity Processing]
        PROC -->|Store| DB[Database]
        DB -->|Notify| CL[Local Clients]
    end

    subgraph "Error Handling"
        ERR1[Rate Limiting]:::errorHandling
        ERR2[Authentication Errors]:::errorHandling
        ERR3[Media Processing Errors]:::errorHandling
        ERR4[Federation Errors]:::errorHandling
        
        DIST --> ERR1 & ERR2
        MH2 --> ERR3
        FED2 & FED3 --> ERR4
    end

graph TD
subgraph "ActivityPub Object Model"
OBJ[Activity Object]-->|contains|OBJ1[type]
OBJ-->|contains|OBJ2[actor]
OBJ-->|contains|OBJ3[object]
OBJ-->|contains|OBJ4[@context]
end
subgraph "Server A (Origin)"
A[User Client]-->|Create Post|B[Server A API]
B-->|Create Activity|C[Activity Creation]
C-->|Validate Structure|OBJ
C-->|Sign & Store|D[Server A Outbox]
D-->|Fan out|E[Distribution]
end
subgraph "Federation & Security"
WF[WebFinger]-->|Discover|ACT[Actor Resolution]
ACT-->|Fetch|KEY[Public Key Retrieval]
KEY-->|Verify|SIG[Signature Check]
SIG-->|Authorize|AUTH[Access Control]
AUTH-->|Rate Limit|RATE[Rate Limiting]
end
subgraph "Server B (Remote)"
F[Server B Inbox]-->|Receive|SIG
AUTH-->|Process|G[Activity Processing]
G-->|Store|H[Database]
H-->|Stream Processing|STR[Activity Streams]
end
subgraph "Error Handling"
ERR[Error Detection]-->|4xx Client Error|ERR1[Invalid Request]
ERR-->|5xx Server Error|ERR2[Server Issues]
ERR-->|Federation Error|ERR3[Network/Auth Failure]
end
subgraph "Activity Streams"
STR-->|Filter|STR1[Content Filtering]
STR-->|Sort|STR2[Chronological Order]
STR-->|Paginate|STR3[Page Management]
STR-->|Notify|I[Follower Clients]
end
E-->|HTTP POST|F
E-->|Parallel Delivery|K[Other Servers]
G-->|Error Handling|ERR

License

These diagrams are provided under the Creative Commons Attribution 4.0 International License (CC BY 4.0). You are free to:

Share — copy and redistribute the material in any medium or format Adapt — remix, transform, and build upon the material for any purpose, even commercially

Under the following terms:

Attribution — You must give appropriate credit to Maciej Lesiak, provide a link to this article or domain, and indicate if changes were made. You may do so in any reasonable manner, but not in any way that suggests the licensor endorses you or your use.