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

A shared request client handles all federated HTTP calls. It exposes generic get/post methods that take an id_tag and a path, resolve the target host as https://cl-o.{id_tag}, and attach a federation bearer token when the call needs authentication (see ProxyToken Authentication). Public variants (get_public, post_public, get_noauth) skip the token for endpoints that are open to any instance, such as the profile/key endpoint GET /api/me.

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..."}         |
  |                                   |--- Queue for async verification
  |<-- 201 Created -------------------|
  |                                   |--- Verify signature, check perms, store

See Also