feat: add federation to README.md

README.md

@@ -14,17 +14,25 @@ Like the cactus, great events bloom under any condition when managed with care.
 
 #### What is it?
 
-A mobile-first event RSVP platform that lets you create events, share unique URLs, and collect RSVPs without any registration required.
+A mobile-first event RSVP platform that lets you create events, share unique URLs, and collect RSVPs without any registration required. With built-in federation, discover and share events across a decentralized network of instances.
 
 ### ✨ Features
 
-- **🎯 Instant Event Creation** - Create events in seconds with our streamlined form. No accounts, no waiting, just pure efficiency.
-- **🔗 One-Click Sharing** - Each event gets a unique, memorable URL. Share instantly via any platform or messaging app.
-- **🔍 All-in-One Clarity** - No more scrolling through endless chats and reactions. See everyone's availability and responses neatly in one place.
-- **📅 iCal Integration** - One-tap add-to-calendar via ICS/webcal links. Works with Apple Calendar, Google Calendar, and Outlook, with automatic time zone handling.
-- **👤 No Hassle, No Sign-Ups** - Skip registrations and endless forms. Unlike other event platforms, you create and share instantly — no accounts, no barriers.
-- **🛡️ Smart Limits** - Choose between unlimited RSVPs or set a limited capacity. Perfect for any event size.
-- **✨ Effortless Simplicity** - Designed to be instantly clear and easy. No learning curve — just open, create, and go.
+**🎯 Instant Event Creation** - Create events in seconds with our streamlined form. No accounts, no waiting, just pure efficiency.
+
+**🔗 One-Click Sharing** - Each event gets a unique, memorable URL. Share instantly via any platform or messaging app.
+
+**🌐 Federation** - Connect with other Cactoide instances to discover events across the network. Share your public events and creating a decentralized event discovery network.
+
+**🔍 All-in-One Clarity** - No more scrolling through endless chats and reactions. See everyone's availability and responses neatly in one place.
+
+**📅 iCal Integration** - One-tap add-to-calendar via ICS/webcal links. Works with Apple Calendar, Google Calendar, and Outlook, with automatic time zone handling.
+
+**👤 No Hassle, No Sign-Ups** - Skip registrations and endless forms. Unlike other event platforms, you create and share instantly — no accounts, no barriers.
+
+**🛡️ Smart Limits** - Choose between unlimited RSVPs or set a limited capacity. Perfect for any event size.
+
+**✨ Effortless Simplicity** - Designed to be instantly clear and easy. No learning curve — just open, create, and go.
 
 ### Quick Start
 
@@ -55,6 +63,55 @@ Your app will be available at `http://localhost:5173`. You can use the Makefile
 
 Use the `database/seed.sql` if you want to populate your database with dummy data.
 
+### Federation
+
+Cactoide supports federation, allowing multiple instances to share and discover public events across the network. This enables users to discover events from other Cactoide instances, creating a decentralized event discovery network.
+
+<p align="center">
+  <img alt="Federation Example" src="./docs/federation_example.png" width="840">
+</p>
+
+#### How Federation Works
+
+Federation is managed through the `federation.config.js` file, which contains:
+
+- **Instance name**: The display name for your instance
+- **Instance list**: An array of federated instance URLs
+
+```javascript
+const config = {
+	name: 'Cactoide Genesis',
+	instances: [{ url: 'cactoide.org' }, { url: 'cactoide.dalev.hu' }]
+};
+```
+
+#### Opting In to Federation
+
+To enable federation on your instance, you need to:
+
+1. **Set the environment variable**: Add `FEDERATION_INSTANCE=true` to your `.env` file. This enables the federation API endpoints on your instance.
+
+2. **Configure your instance name**: Update the `name` field in your `federation.config.js` file to set your instance's display name.
+
+3. **Expose required endpoints**: Your instance will automatically expose:
+   - `/api/federation/events` - Returns all public events from your instance
+   - `/api/federation/info` - Returns your instance name and public events count
+
+#### Adding Your Instance to the Global Federation
+
+To add your instance to the global federation list (so other instances can discover your events):
+
+1. Fork the [Cactoide repository](https://github.com/polaroi8d/cactoide)
+2. Add your instance URL to the `instances` array in `federation.config.js`:
+   ```javascript
+   instances: [{ url: 'your-instance.com' }];
+   ```
+3. Open a pull request to the main repository
+
+Once merged, your instance will appear in the federation network, and other instances will be able to discover and display your public events.
+
+You can view all registered federated instances in the main repository: `federation.config.js` file.
+
 ### Options
 
 #### 1. Landing page option
@@ -90,7 +147,6 @@ It isn’t backed by a big company. Development depends on the support and gener
 
 You can support in a few ways:
 
-- Send a one-time donation via [paypal.me/zenoazurben](paypal.me/zenoazurben)
 - Reach me directly: leventeorb[@]gmail.com
 
 If you enjoy using Cactoide, or if your business depends on it, please consider sponsoring its development. Your support keeps the project alive, improves it for everyone, and helps create educational content like blog posts and videos for the whole Cactoide community.