# immers-space/activitypub-express architecture

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

- Interactive diagram: https://gitdiagram.com/immers-space/activitypub-express
- Repository: https://github.com/immers-space/activitypub-express

## Overview

##### Project Type and Purpose
This is an open-source middleware library that implements the ActivityPub decentralized social networking protocol for Express.js applications. The project provides a modular implementation with interchangeable storage interfaces.

##### Main Components

a. Core Components:
- ActivityPub Express Middleware (Central Component)
- Storage Interface Layer
- Network Layer (net/)
- Publication Layer (pub/)
- Vocabulary Definitions (vocab/)

b. External Components:
- Express.js Application
- MongoDB (default storage)
- Remote ActivityPub Servers
- Client Applications

**[Client Layer]**
- ↕️
**[Express.js Application]**
- ↕️
**[ActivityPub Express Middleware]**
- Network Layer
- Activity Handlers
- Collection Handlers
- Security
- Validators

- Publication Layer
- Activity Processing
- Actor Management
- Federation
- NodeInfo

- Storage Interface
- MongoDB Adapter

- Vocabulary Definitions

**[External Federation]**

##### Key Interactions to Highlight

a. Internal Flows:
- Request handling path from Express.js through the middleware
- Activity processing flow
- Storage operations
- Security validation chain

b. External Flows:
- Federation communication paths
- Client-to-server interactions
- Server-to-server interactions

##### Implementation Details to Note

- Main routes (/inbox, /outbox, /actor, etc.)
- Where custom handlers can be attached
- Points where the storage interface can be swapped
- Integration points with external authentication

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph Client["Client Layer"]
        WebClient["Web Clients"]
        RemoteAP["Remote ActivityPub Servers"]
    end

    subgraph Express["Express.js Layer"]
        ExpressApp["Express.js Application"]
    end

    subgraph APEXCore["ActivityPub Express Core"]
        MainMiddleware["APEX Middleware"]:::core
        click MainMiddleware "https://github.com/immers-space/activitypub-express/blob/master/index.js"
    end

    subgraph Network["Network Layer"]
        direction TB
        ActivityHandlers["Activity Handlers"]:::network
        CollectionHandlers["Collection Handlers"]:::network
        Security["Security"]:::security
        Validators["Validators"]:::network
        WellKnown["Well-Known Services"]:::network

        click ActivityHandlers "https://github.com/immers-space/activitypub-express/blob/master/net/activity.js"
        click CollectionHandlers "https://github.com/immers-space/activitypub-express/blob/master/net/collection.js"
        click Security "https://github.com/immers-space/activitypub-express/blob/master/net/security.js"
        click Validators "https://github.com/immers-space/activitypub-express/blob/master/net/validators.js"
        click WellKnown "https://github.com/immers-space/activitypub-express/blob/master/net/well-known.js"
    end

    subgraph Publication["Publication Layer"]
        direction TB
        ActivityProcessing["Activity Processing"]:::pub
        ActorManagement["Actor Management"]:::pub
        Federation["Federation"]:::pub
        NodeInfo["NodeInfo"]:::pub
        ObjectManagement["Object Management"]:::pub
        Collections["Collections"]:::pub

        click ActivityProcessing "https://github.com/immers-space/activitypub-express/blob/master/pub/activity.js"
        click ActorManagement "https://github.com/immers-space/activitypub-express/blob/master/pub/actor.js"
        click Federation "https://github.com/immers-space/activitypub-express/blob/master/pub/federation.js"
        click NodeInfo "https://github.com/immers-space/activitypub-express/blob/master/pub/nodeinfo.js"
        click ObjectManagement "https://github.com/immers-space/activitypub-express/blob/master/pub/object.js"
        click Collections "https://github.com/immers-space/activitypub-express/blob/master/pub/collection.js"
    end

    subgraph Storage["Storage Layer"]
        StorageInterface["Storage Interface"]:::storage
        MongoAdapter["MongoDB Adapter"]:::storage

        click StorageInterface "https://github.com/immers-space/activitypub-express/blob/master/store/interface.js"
    end

    subgraph Vocabulary["Vocabulary Definitions"]
        ActivityStreams["ActivityStreams"]:::vocab
        SecurityVocab["Security Vocabulary"]:::vocab

        click ActivityStreams "https://github.com/immers-space/activitypub-express/blob/master/vocab/as.json"
        click SecurityVocab "https://github.com/immers-space/activitypub-express/blob/master/vocab/security.json"
    end

    subgraph Utils["Utilities"]
        Constants["Constants"]:::util
        Utilities["Utilities"]:::util

        click Constants "https://github.com/immers-space/activitypub-express/blob/master/pub/consts.js"
        click Utilities "https://github.com/immers-space/activitypub-express/blob/master/pub/utils.js"
    end

    %% Connections
    WebClient & RemoteAP --> ExpressApp
    ExpressApp --> MainMiddleware
    MainMiddleware --> Network
    MainMiddleware --> Publication
    Network <--> Publication
    Publication --> Storage
    Network & Publication --> Vocabulary
    Network & Publication --> Utils

    %% Styles
    classDef core fill:#2d7dd2,color:white
    classDef network fill:#97cc04,color:black
    classDef pub fill:#f45d01,color:white
    classDef security fill:#7209b7,color:white
    classDef storage fill:#3a86ff,color:white
    classDef vocab fill:#8338ec,color:white
    classDef util fill:#ff006e,color:white

    %% Legend
    subgraph Legend
        CoreL["Core Component"]:::core
        NetworkL["Network Component"]:::network
        PubL["Publication Component"]:::pub
        SecurityL["Security Component"]:::security
        StorageL["Storage Component"]:::storage
        VocabL["Vocabulary Component"]:::vocab
        UtilL["Utility Component"]:::util
    end
```
