Federation Architecture

Cloudillo is designed as a federated system where independent instances communicate to share content, enable collaboration, and maintain user sovereignty. This architecture ensures users can self-host while remaining connected to the broader network.

Why Federation?

The email analogy: You don’t need a Gmail account to email someone on Gmail—any email server can talk to any other. Cloudillo works the same way for social interactions and collaboration.

What federation enables:

  • Alice hosts her own server → She controls her data, privacy settings, and uptime
  • Bob uses a community server → He gets the convenience of managed hosting
  • Alice and Bob collaborate → Their servers communicate directly, no middleman

Comparison with centralized platforms:

Aspect Centralized (Twitter, Slack) Federated (Cloudillo, Email)
Data location Company servers Your chosen server
Account survival Company decides You control
Privacy policy Take it or leave it Server-by-server
Feature changes Company decides Choose your instance
Network effects All users on one platform All users, many servers

Why not fully peer-to-peer? Pure P2P requires both parties online simultaneously. Federation gives you the benefits of decentralization while allowing offline message delivery, persistent hosting, and simpler client applications.

Core Principles

Decentralization

  • No central authority: No single server controls the network
  • User sovereignty: Users choose where their data lives
  • Instance independence: Each instance operates autonomously

Privacy-First

  • Explicit consent: Users control what they share
  • Relationship-based: Only share with connected/following users
  • End-to-end verification: Cryptographic signatures prove authenticity
  • No data harvesting: Federation for communication, not surveillance

Interoperability

  • Standard protocols: HTTP/HTTPS, WebSocket, JWT
  • Content addressing: SHA256 ensures integrity across instances
  • Action tokens: Portable, verifiable activity records
  • DNS-based identity: Discoverable profiles via domain names

Inter-Instance Communication

Request Module

The request module provides HTTP client functionality for federation:

Request Structure:

  • client: HTTP client (reqwest) for making requests
  • timeout: Request timeout duration
  • retry_policy: Configuration for automatic retries

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/action/:id from remote
  • post_inbox(id_tag, token) - POST /api/inbox with action token
  • fetch_file(id_tag, file_id) - GET /api/file/: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