# ansh/bluesky-pds architecture

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

- Interactive diagram: https://gitdiagram.com/ansh/bluesky-pds
- Repository: https://github.com/ansh/bluesky-pds

## Overview

##### Project Type and Purpose
- This project is a self-hostable server solution for the Bluesky Personal Data Server. It is built to run as a Dockerized Node.js application that federates with the Bluesky social network.
- The README focuses on deployment and self-hosting instructions for setting up a Node-based server (from the service/ directory) behind a reverse proxy (Caddy) and includes automation for container updates (Watchtower).

##### File Structure Analysis
- Top-Level Directories/Files:
- .github/ contains CI/CD workflows (e.g., build-and-push-ghcr.yaml) which indicate automated container image builds.
- Dockerfile exists, suggesting that the project can be containerized/built.
- A compose.yaml file provides the orchestration configuration for multiple containers.
- The installer.sh and SANDBOX.md files guide users in setting up and deploying the service.
- The service/ directory contains the primary Node.js application code (index.js and package.json).
- Architectural Clues:
- The project is modular in that it separates the application logic (service) from the container orchestration and reverse proxy (Caddy configuration in the compose file).
- The use of Docker Compose implies container-based segmentation and separation of concerns.

##### Key Components
a. Core Components:
- PDS Server Container: Runs the Node.js application (located in the service/ directory). It listens on port 3000 and is the core engine handling API requests and business logic.
- Caddy Container: Acts as the HTTP reverse proxy that handles TLS termination, enforces security (via on-demand TLS), and routes all HTTP/HTTPS traffic to the PDS server.
- Watchtower Container: Monitors the running containers for any updates and automatically refreshes them to keep your deployment secure.
- Docker Host: The underlying server where Docker and Docker Compose orchestrate these containers. This node is also responsible for managing environment variables (like PDS_HOSTNAME, database location, blobstore path, etc.) and mounting necessary volumes (SQLite DB, blob storage).

b. Relationships and Data Flow:
- Incoming web traffic arrives at the public endpoints (ports 80 and 443) on the Docker host.
- Requests first hit the Caddy container, which terminates TLS and forwards secure HTTP requests to the PDS server container over the internal network (port 3000).
- The PDS server reads/writes to its SQLite database (/pds/pds.sqlite) and blob storage (/pds/blocks) mounted from the host, and possibly interacts with external Bluesky federation endpoints.
- The Watchtower container runs in parallel monitoring update signals from Docker Hub, automatically updating the containers as needed.

c. Architectural Patterns & Design Principles:
- Container-based deployment using Docker Compose: Clear segregation of application (backend), proxy (Caddy), and monitoring (Watchtower) into independent, manageable services.
- Reverse proxy architecture: Use of Caddy enables TLS termination and load distribution.
- Self-hosted deployment: The design leverages local file system mounted volumes for persistence (database, blobstore).

d. Technologies and Frameworks:
- Node.js (service directory) powering the backend.
- Caddy web server for secure reverse proxy and TLS management.
- Docker and Docker Compose for container orchestration.
- Additional tooling like Watchtower for container auto-update.
- Environment variables for configuration and security (secure JWT tokens, admin passwords, key generation specifics).

## Diagram (Mermaid)

```mermaid
graph TD
    %% External Traffic
    Internet["Internet (Ports 80/443)"]:::edge

    %% Docker Host & Orchestration Subgraph
    subgraph "Docker Host & Orchestration"
        %% Containers Subgraph
        subgraph "Containers"
            Caddy["Caddy Reverse Proxy"]:::proxy
            PDS["PDS Node.js Server (port 3000)"]:::backend
            Watchtower["Watchtower Auto-Update"]:::monitor
        end
        %% Persistent Storage Subgraph
        subgraph "Persistent Storage"
            SQLite["SQLite DB (/pds/pds.sqlite)"]:::db
            Blob["Blob Storage (/pds/blocks)"]:::db
        end
    end

    %% Deployment & Automation Subgraph
    subgraph "Deployment & Automation"
        CICD["CI/CD Automation"]:::automation
        Depl["Deployment Scripts"]:::automation
        DockerOrch["Docker Host & Orchestration Config"]:::orchestration
    end

    %% Data Flow
    Internet -->|"HTTP/HTTPS"| Caddy
    Caddy -->|"Forward"| PDS
    PDS -->|"ReadWrite"| SQLite
    PDS -->|"ReadWrite"| Blob

    %% Watchtower Monitoring (dashed lines)
    Watchtower -.->|"Monitors"| Caddy
    Watchtower -.->|"Monitors"| PDS

    %% Deployment & Automation Flow
    CICD -->|"Triggers"| DockerOrch
    Depl -->|"Deploys"| DockerOrch
    DockerOrch -->|"Manages"| Caddy
    DockerOrch -->|"Manages"| PDS
    DockerOrch -->|"Manages"| Watchtower

    %% Click Events for Component Mapping
    click PDS "https://github.com/ansh/bluesky-pds/blob/main/service/index.js"
    click PDS "https://github.com/ansh/bluesky-pds/blob/main/service/package.json"
    click Caddy "https://github.com/ansh/bluesky-pds/blob/main/compose.yaml"
    click Watchtower "https://github.com/ansh/bluesky-pds/blob/main/compose.yaml"
    click Depl "https://github.com/ansh/bluesky-pds/blob/main/installer.sh"
    click CICD "https://github.com/ansh/bluesky-pds/blob/main/.github/workflows/build-and-push-ghcr.yaml"
    click DockerOrch "https://github.com/ansh/bluesky-pds/tree/main/Dockerfile"
    click DockerOrch "https://github.com/ansh/bluesky-pds/blob/main/compose.yaml"

    %% Styles
    classDef backend fill:#B3E5FC,stroke:#0277BD,stroke-width:2px;
    classDef proxy fill:#C8E6C9,stroke:#2E7D32,stroke-width:2px;
    classDef monitor fill:#FFECB3,stroke:#FFA000,stroke-width:2px;
    classDef db fill:#F8BBD0,stroke:#AD1457,stroke-width:2px;
    classDef orchestration fill:#E1BEE7,stroke:#6A1B9A,stroke-width:2px;
    classDef automation fill:#D7CCC8,stroke:#5D4037,stroke-width:2px;
    classDef edge fill:#FFE0B2,stroke:#F57C00,stroke-width:2px;
```
