Federation Architecture

Cloudillo is designed as a federated system where independent instances communicate to share content, enable collaboration, and maintain user sovereignty. Like email, any Cloudillo server can communicate with any other – users don’t need to be on the same instance.

Core Principles

  • No central authority: Each instance operates autonomously
  • User sovereignty: Users choose where their data lives
  • Explicit consent: Relationship-based sharing with cryptographic verification
  • Standard protocols: HTTP/HTTPS, WebSocket, JWT, DNS-based identity
  • Content addressing: SHA256 ensures integrity across instances

Inter-Instance Communication

Request Module

The request module provides HTTP client functionality for federation:

Request Methods:

  • get(url) - Generic HTTP GET
  • post(url, body) - Generic HTTP POST with JSON body
  • fetch_profile(id_tag) - GET /api/me from remote instance
  • fetch_action(id_tag, action_id) - GET /api/actions/:id from remote
  • post_inbox(id_tag, token) - POST /api/inbox with action token
  • fetch_file(id_tag, file_id) - GET /api/files/:id from remote

Federation Flow

When Alice (on instance A) follows Bob (on instance B):

Instance A                          Instance B
  |                                   |
  |--- GET /api/me ------------------>| (Fetch Bob's profile)
  |<-- 200 OK {profile} --------------|
  |                                   |
  |--- Create FLLW action token ---   |
  |                                   |
  |--- POST /api/inbox -------------->| (Send follow action)
  |    {token: "eyJhbGc..."}         |
  |                                   |--- Verify signature
  |                                   |--- Check permissions
  |                                   |--- Store action
  |<-- 202 Accepted ------------------|

See Also