Swarm/docs/HOW_TO_FOLLOW_FEDIVERSE_USERS.md

How to Follow (Subscribe to) Fediverse Users in Solar Network

Overview

In ActivityPub terminology, "subscribing" to a user is called "following". This guide explains how users in Solar Network can follow users from other federated services (Mastodon, Pleroma, etc.).

User Guide: How to Follow Fediverse Users

Method 1: Via Search (Recommended)

1. Search for the user:

   • Type their full address in the search bar: @username@domain.com
   • Example: @alice@mastodon.social
   • Example: @bob@pleroma.site

2. View their profile:

   • Click on the search result
   • You'll see their profile, bio, and recent posts

3. Click "Follow" button:

   • Solar Network sends a Follow activity to their instance
   • The remote instance will send back an Accept
   • The user now appears in your "Following" list

Method 2: Via Profile URL

1. Visit their profile directly:

   • If you know their profile URL, visit it directly
   • Example: https://mastodon.social/@alice

2. Look for "Follow" button:

   • Click it to follow

3. Confirm the follow:

   • Solar Network will send the follow request
   • Wait for acceptance (usually immediate)

What Happens Behind the Scenes

The Follow Flow

User clicks "Follow"
        ↓
Solar Network creates Follow Activity
        ↓
Solar Network signs with publisher's private key
        ↓
Solar Network sends to remote user's inbox
        ↓
Remote instance verifies signature
        ↓
Remote instance processes the Follow
        ↓
Remote instance sends Accept Activity back
        ↓
Solar Network receives and processes Accept
        ↓
Relationship is established!

Timeline Integration

Once you're following a user:

• ✅ Their public posts appear in your "Home" timeline
• ✅ Their posts are federated to your followers
• ✅ Their likes, replies, and boosts are visible
• ✅ You can interact with their content

Following Different Types of Accounts

Individual Users

• What: Regular users like you
• Example: @alice@mastodon.social
• Works: ✅ Full support

Organizational/Bot Accounts

• What: Groups, bots, or organizations
• Example: @official@newsbot.site
• Works: ✅ Full support

Locked Accounts

• What: Users who manually approve followers
• Example: @private@pleroma.site
• Works: ✅ Follow request sent, waits for approval

Managing Your Follows

View Who You're Following

API Endpoint: GET /api/activitypub/following

Response Example:

{
  "users": [
    {
      "actorUri": "https://mastodon.social/users/alice",
      "username": "alice",
      "displayName": "Alice Smith",
      "bio": "I love tech and coffee! ☕",
      "avatarUrl": "https://cdn.mastodon.social/avatars/...",
      "followedAt": "2024-01-15T10:30:00Z",
      "isLocal": false,
      "instanceDomain": "mastodon.social"
    }
  ]
}

Unfollowing Someone

API Endpoint: POST /api/activitypub/unfollow

Request Body:

{
  "targetActorUri": "https://mastodon.social/users/alice"
}

Response:

{
  "success": true,
  "message": "Unfollowed successfully"
}

Searching Fediverse Users

API Endpoint: GET /api/activitypub/search?query=@username@domain.com

Response Example:

{
  "users": [
    {
      "actorUri": "https://mastodon.social/users/alice",
      "username": "alice",
      "displayName": "Alice Smith",
      "bio": "Software developer | Mastodon user",
      "avatarUrl": "https://cdn.mastodon.social/avatars/...",
      "isLocal": false,
      "instanceDomain": "mastodon.social"
    }
  ]
}

Follow States

State	Meaning	What User Sees
Pending	Follow request sent, waiting for response	"Following..." (loading)
Accepted	Remote user accepted	"Following" ✓
Rejected	Remote user declined	"Follow" button available again
Failed	Error occurred	"Error following" message

Privacy & Visibility

Public Posts

• ✅ Federate to your followers automatically
• ✅ Appear in remote instances' timelines
• ✅ Can be boosted/liked by remote users

Private Posts

• ❌ Do not federate
• ❌ Only visible to your local followers
• ❌ Not sent to remote instances

Unlisted Posts

• ⚠️ Federate but not in public timelines
• ⚠️ Only visible to followers

Best Practices for Users

When Following Someone

1. Check their profile first:

   • Make sure they're who you think they are
   • Read their bio to understand their content

2. Start with a few interactions:

   • Like a few posts
   • Reply to something interesting
   • Don't overwhelm their timeline

3. Respect their instance's rules:

   • Each instance has its own guidelines
   • Read community rules before interacting

4. Report spam/harassment:

   • Use instance blocking features
   • Report to instance admins

Following Across Instances

1. Use their full address:

   • @username@instance.com
   • This helps identify which instance they're on

2. Be aware of instance culture:

   • Each instance has its own norms
   • Some are more technical, others more casual

3. Check if they're from your instance:

   • Local users show isLocal: true
   • Usually faster interaction

Troubleshooting

"Follow button doesn't work"

Possible Causes:

1. User doesn't exist
2. Instance is down
3. Network issue

Solutions:

1. Verify the user's address is correct
2. Check if the instance is accessible
3. Check your internet connection
4. Try again in a few minutes

"User doesn't appear in Following list"

Possible Causes:

1. Follow was rejected
2. Still waiting for acceptance (locked accounts)
3. Error in federation

Solutions:

1. Check the follow status via API
2. Try following again
3. Check if their account is locked
4. Contact support if issue persists

"Can't find a user"

Possible Causes:

1. Wrong username or domain
2. User doesn't exist
3. Instance blocking your instance

Solutions:

1. Double-check the address
2. Try searching from a different instance
3. Contact the user directly for their handle

API Reference

Follow a Remote User

Endpoint: POST /api/activitypub/follow

Request:

{
  "targetActorUri": "https://mastodon.social/users/alice"
}

Response: 200 OK

{
  "success": true,
  "message": "Follow request sent. Waiting for acceptance.",
  "targetActorUri": "https://mastodon.social/users/alice"
}

Get Following List

Endpoint: GET /api/activitypub/following?limit=50

Response: 200 OK

{
  "users": [
    {
      "actorUri": "https://mastodon.social/users/alice",
      "username": "alice",
      "displayName": "Alice Smith",
      "bio": "...",
      "avatarUrl": "...",
      "followedAt": "2024-01-15T10:30:00Z",
      "isLocal": false,
      "instanceDomain": "mastodon.social"
    }
  ]
}

Get Followers List

Endpoint: GET /api/activitypub/followers?limit=50

Response: 200 OK

{
  "users": [
    {
      "actorUri": "https://mastodon.social/users/alice",
      "username": "alice",
      "displayName": "Alice Smith",
      "bio": "...",
      "avatarUrl": "...",
      "isLocal": false,
      "instanceDomain": "mastodon.social"
    }
  ]
}

Search Users

Endpoint: GET /api/activitypub/search?query=alice&limit=20

Response: 200 OK

{
  "users": [
    {
      "actorUri": "https://mastodon.social/users/alice",
      "username": "alice",
      "displayName": "Alice Smith",
      "bio": "...",
      "avatarUrl": "...",
      "isLocal": false,
      "instanceDomain": "mastodon.social"
    }
  ]
}

What's Different About ActivityPub Following?

Unlike traditional social media:

Feature	Traditional Social	ActivityPub
Central server	✅ Yes	❌ No - federated
All users on same platform	✅ Yes	❌ No - multiple platforms
Blocked instances	❌ No	✅ Yes - instance blocking
Following across platforms	❌ No	✅ Yes - works with Mastodon, Pleroma, etc.
Your data stays on your server	❌ Maybe	✅ Yes - you control your data

User Experience Considerations

Making It Easy

1. Auto-discovery:

   • When users search for @username, suggest @username@domain.com
   • Offer to search the fediverse

2. Clear UI feedback:

   • Show "Follow request sent..."
   • Show "They accepted!" notification
   • Show "Follow request rejected" message

3. Helpful tooltips:

   • Explain what ActivityPub is
   • Show which instance a user is from
   • Explain locked accounts

4. Profile badges:

   • Show instance icon/logo
   • Show if user is from same instance
   • Show if user is verified

Examples

Following a Mastodon User

User searches: @alice@mastodon.social

What happens:

1. Solar Network fetches Alice's actor profile
2. Solar Network stores Alice in fediverse_actors
3. Solar Network sends Follow to Alice's inbox
4. Alice's instance accepts
5. Solar Network stores relationship in fediverse_relationships
6. Alice's posts now appear in user's timeline

Following a Local User

User searches: @bob

What happens:

1. Solar Network finds Bob's publisher
2. Relationship created locally (no federation needed)
3. Bob's posts appear in user's timeline immediately
4. Same as traditional social media following

Summary

Following fediverse users in Solar Network:

1. Search by @username@domain.com - Works for any ActivityPub instance
2. Click "Follow" - Sends federated follow request
3. Wait for acceptance - Remote user can approve or auto-accept
4. See their posts in your timeline - Content federates to you
5. Interact normally - Like, reply, boost, etc.

All of this is handled automatically by the ActivityPub implementation!