# mauricerenck/mastodon-to-bluesky architecture

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

- Interactive diagram: https://gitdiagram.com/mauricerenck/mastodon-to-bluesky
- Repository: https://github.com/mauricerenck/mastodon-to-bluesky

## Overview

##### Main Components
- External Services:
- Mastodon API: The service polls Mastodon for new posts.
- Bluesky API: The service pushes or crossposts the retrieved content.
- Core Application:
- The Node.js process (main.js): Acts as the orchestrator. It retrieves posts, processes them (maybe using utilities in utils.js), and sends them to Bluesky.
- Utility module(s): For example, utils.js which handles helper functions or processes.
- Data/State Storage:
- Data Directory: Contains lastProcessedPostId.txt for tracking the last processed Mastodon toot.
- Configuration:
- Environment Variables: Loaded from a .env file to provide API endpoints, credentials, and intervals.
- Deployment/Containerization:
- Dockerfile and docker-compose.yml: Define how the application is containerized and deployed.

##### Relationships Between Components
- The Node.js process (main.js) acts as the central orchestrator and communicates directly with external APIs:
- Pulls data from Mastodon.
- Posts data to Bluesky.
- It uses environment configuration to manage connection details and operational intervals.
- It reads/writes state information to a local file (data/lastProcessedPostId.txt) to keep track of processed toots.
- The utilities (in utils.js) are used to support these actions, likely abstracting repeatable tasks or API calls.
- Docker configurations (Dockerfile and docker-compose.yml) allow the entire setup to be deployed consistently in various environments.

##### Architectural Patterns and Design Principles
- Single Process Service: The entire application is encapsulated into one process with clear separation of concerns (API connectivity, state management, configuration handling).
- Separation of Configuration and Code: Environment variables and configuration files ensure credentials and endpoints aren’t hardcoded.
- Containerization: Use of Docker implies a design focus on portability and reproducibility.

##### Specific Elements
- Data flow from Mastodon to the Node.js process.
- Processing within main.js (possibly invoking functions in utils.js).
- Outbound communication from the Node.js process to the Bluesky API.
- Read/Write operations to the state file.
- External entities (APIs, Docker host environment),
- Core service components (Node.js process, utility modules),
- Configuration and persistent storage (environment variables and data files).

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Deployment/Containerization"
        D1["Docker Container"]:::deployment
        DF["Dockerfile"]:::deployment
        DC["docker-compose.yml"]:::deployment
    end

    subgraph "Core Application"
        NP["Node.js Main Process"]:::core
        U["Utility Module"]:::core
        S["State File: lastProcessedPostId.txt"]:::storage
        E["Environment Config (.env)"]:::config
    end

    subgraph "External Services"
        M["Mastodon API"]:::external
        B["Bluesky API"]:::external
    end

    DF -->|"builds"| D1
    DC -->|"orchestrates"| D1

    D1 -->|"runs"| NP

    NP -->|"polls"| M
    NP -->|"posts_to"| B
    NP -->|"uses"| U
    NP -->|"updates"| S
    E -->|"configures"| NP

    click NP "https://github.com/mauricerenck/mastodon-to-bluesky/blob/main/main.js"
    click U "https://github.com/mauricerenck/mastodon-to-bluesky/blob/main/utils.js"
    click S "https://github.com/mauricerenck/mastodon-to-bluesky/blob/main/data/lastProcessedPostId.txt"
    click E "https://github.com/mauricerenck/mastodon-to-bluesky/blob/main/.env.sample"
    click DF "https://github.com/mauricerenck/mastodon-to-bluesky/tree/main/Dockerfile"
    click DC "https://github.com/mauricerenck/mastodon-to-bluesky/blob/main/docker-compose.yml"

    classDef core fill:#ADD8E6,stroke:#333,stroke-width:2px;
    classDef external fill:#90EE90,stroke:#333,stroke-width:2px;
    classDef storage fill:#FFB6C1,stroke:#333,stroke-width:2px;
    classDef config fill:#FFD700,stroke:#333,stroke-width:2px;
    classDef deployment fill:#D3D3D3,stroke:#333,stroke-width:2px;
```
