Swarm/docs/FOLLOWING_USERS_GUIDE.md

Follow Feature - User Guide

Quick Start: How to Follow Fediverse Users

Method 1: Via Search (Recommended)

1. Go to the search bar in Solar Network
2. Type the user's full address: @username@domain.com
   • Example: @alice@mastodon.social
   • Example: @bob@pleroma.site
3. Click on their profile in search results
4. Click the "Follow" button
5. Wait for acceptance (usually immediate)
6. ✅ Done! Their posts will now appear in your timeline

Method 2: Via Profile URL

1. If you know their profile URL, visit it directly:
   • Example: https://mastodon.social/@alice
2. Look for the "Follow" button on their profile
3. Click it to follow
4. ✅ You're now following them!

What Happens When You Follow Someone

The Technical Flow

You click "Follow"
        ↓
Solar Network creates Follow Activity
        ↓
Follow Activity is signed with your private key
        ↓
Solar Network sends Follow to their instance's inbox
        ↓
Their instance verifies your signature
        ↓
Their instance processes the Follow
        ↓
Their instance sends Accept Activity back
        ↓
Solar Network receives and processes Accept
        ↓
Relationship is stored in database
        ↓
Their public posts federate to Solar Network

What You'll See

• ✅ "Following..." (while waiting for acceptance)
• ✅ "Following" ✓ (when accepted)
• ✅ Their posts in your home timeline
• ✅ Their likes, replies, boosts on your posts

Different Types of Accounts

Regular Users

• Full ActivityPub support
• Follows work both ways
• Content federates normally
• Example: @alice@mastodon.social

Locked Accounts

• User must manually approve followers
• You'll see "Pending" after clicking follow
• User receives notification to approve/deny
• Example: @private@pleroma.site

Bot/Service Accounts

• Automated content accounts
• Often auto-accept follows
• Example: @newsbot@botsin.space

Organizational Accounts

• Group or team accounts
• Example: @team@company.social

Managing Your Follows

View Who You're Following

Go to: Following page or GET /api/activitypub/following

You'll see:

• Username
• Display name
• Profile picture
• When you followed them
• Their instance (e.g., "Mastodon")

Unfollowing Someone

Method 1: Via UI

1. Go to their profile
2. Click "Following" button (shows as active)
3. Click to unfollow

Method 2: Via API

curl -X POST http://solar.local:5000/api/activitypub/unfollow \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "targetActorUri": "https://mastodon.social/users/alice"
  }'

Response:

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

View Your Followers

Go to: Followers page or GET /api/activitypub/followers

You'll see:

• Users following you
• Their instance
• When they started following
• Whether they're local or from another instance

Searching Fediverse Users

How Search Works

1. Type in search bar: @username@domain.com
2. Solar Network queries their instance:
   • Fetches their actor profile
   • Checks if they're discoverable
3. Shows results:
   • Profile picture
   • Display name
   • Bio
   • Instance name

Supported Search Formats

Format	Example	Works?
Full handle	@alice@mastodon.social	✅ Yes
Username only	alice	⚠️ May search local users first
Full URL	https://mastodon.social/@alice	✅ Yes

Privacy Considerations

Public Posts

• What: Posts visible to everyone
• Federation: ✅ Federates to all followers
• Timeline: Visible in public federated timelines
• Example: General updates, thoughts, content you want to share

Private Posts

• What: Posts only visible to followers
• Federation: ✅ Federates to followers (including remote)
• Timeline: Only visible to your followers
• Example: Personal updates, questions

Unlisted Posts

• What: Posts not in public timelines
• Federation: ✅ Federates but marked unlisted
• Timeline: Only followers see it
• Example: Limited audience content

Followers-Only Posts

• What: Posts only to followers, no federated boost
• Federation: ⚠️ May not federate fully
• Timeline: Only your followers
• Example: Very sensitive content

Following Etiquette

Best Practices

1. Check before following:

   • Read their bio and recent posts
   • Make sure they're who you think they are
   • Check if their content aligns with your interests

2. Start with interactions:

   • Like a few posts first
   • Reply thoughtfully
   • Share interesting content
   • Then follow if you want to see more

3. Respect instance culture:

   • Each instance has its own norms
   • Read their community guidelines
   • Be mindful of local rules

4. Don't spam:

   • Don't mass-follow users
   • Don't send unwanted DMs
   • Don't repeatedly like old posts

5. Use appropriate post visibility:

   • Public for general content
   • Unlisted for updates to followers
   • Private for sensitive topics

Red Flags to Watch

1. Suspicious accounts:

   • Newly created with generic content
   • Only posting promotional links
   • Unusual following patterns

2. Instances with poor moderation:

   • Lots of spam in public timelines
   • Harassment goes unaddressed
   • You may want to block the instance

3. Content warnings not respected:

   • Users posting unmarked sensitive content
   • You can report/block these users

Troubleshooting

"Follow button doesn't work"

Possible causes:

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

What to do:

1. Verify the username/domain is correct
2. Try searching for them again
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 (locked account)
2. Follow is still pending
3. Error in federation

What to do:

1. Check if their account is locked
2. Wait a few minutes for acceptance
3. Check your ActivityPub logs
4. Try following again

"Can't find a user via search"

Possible causes:

1. Username/domain is wrong
2. User's instance is blocking your instance
3. User's profile is not discoverable

What to do:

1. Double-check the spelling
2. Try their full URL: https://instance.com/@username
3. Check if they're from a blocked instance
4. Contact them directly for their handle

API Reference

Follow a Remote User

Endpoint: POST /api/activitypub/follow

Request:

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

Success Response:

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

Get Your Following

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

Response:

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

Get Your Followers

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

Response:

{
  "users": [
    {
      "actorUri": "https://pleroma.site/users/bob",
      "username": "bob",
      "displayName": "Bob Jones",
      "bio": "Federated user following me",
      "avatarUrl": "https://...",
      "followedAt": "2024-01-10T14:20:00Z",
      "isLocal": false,
      "instanceDomain": "pleroma.site"
    }
  ]
}

Search Users

Endpoint: GET /api/activitypub/search?query=@alice@domain.com&limit=20

Response:

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

Real Examples

Example 1: Following a Mastodon User

What you do:

1. Search for @alice@mastodon.social
2. Click on Alice's profile
3. Click "Follow" button
4. Wait 1-2 seconds
5. ✅ Alice appears in your "Following" list
6. ✅ Alice's public posts appear in your timeline

What happens technically:

• Solar Network sends Follow to Alice's Mastodon instance
• Alice's Mastodon auto-accepts (unless locked)
• Mastodon sends Accept back to Solar Network
• Relationship stored in both databases
• Alice's future posts federate to Solar Network

Example 2: Following a Locked Account

What you do:

1. Search for @private@pleroma.site
2. Click "Follow" button
3. ✅ See "Following..." (pending)
4. Wait for user to approve

What happens technically:

• Solar Network sends Follow to private@pleroma.site
• Private user receives notification
• Private user manually approves the request
• Private user's instance sends Accept
• ✅ Now following!

Example 3: Following a Bot Account

What you do:

1. Search for @news@botsin.space
2. Click "Follow" button
3. ✅ Immediately following (bots auto-accept)

What happens technically:

• Follow is auto-accepted
• News posts appear in your timeline
• Regular updates from the bot

Key Differences from Traditional Social Media

Aspect	Traditional Social	ActivityPub
Central server	❌ No	✅ Yes (per instance)
Multiple platforms	❌ No	✅ Yes (Mastodon, Pleroma, etc.)
Data ownership	❌ On their servers	✅ On your server
Blocking	❌ One platform	✅ Per instance
Migration	❌ Difficult	✅ Use your own domain
Federation	❌ No	✅ Built-in

Getting Help

If you have issues following users:

1. Check the main guide: See HOW_TO_FOLLOW_FEDIVERSE_USERS.md
2. Check your logs: Look for ActivityPub errors
3. Test the API: Use curl to test follow endpoints directly
4. Verify the user: Make sure the user exists on their instance

Summary

Following fediverse users in Solar Network:

1. Simple: Just search and click "Follow"
2. Works both ways: You can follow them, they can follow you
3. Works across instances: Mastodon, Pleroma, Lemmy, etc.
4. Federated content: Their posts appear in your timeline
5. Full interactions: Like, reply, boost their posts

It works just like following on any other social platform, but with the added benefit of being able to follow users on completely different services! 🌍