Users can follow other users to stay updated on their activity. The follow system powers follower/following counts, profile hover cards, and post notifications.
How It Works
Following is a one-way relationship stored in the hub_user_follows table. A self-follow constraint prevents users from following themselves.
Action
Method
Description
Follow
POST /api/hub/follows
Creates a follow relationship
Unfollow
DELETE /api/hub/follows
Removes the follow relationship
Check status
GET /api/hub/follows
Returns whether the current user follows a target user
All mutation endpoints require authentication via session cookies.
Optimistic UI
The useFollow hook provides an optimistic toggle experience:
The follow/unfollow button updates immediately on click
The API request fires in the background
On failure, the UI rolls back to the previous state
User Stats
The GET /api/hub/follows endpoint (via getUserStats) returns aggregate counts:
Stat
Description
followers
Number of users following this user
following
Number of users this user follows
posts
Number of visible posts by this user
These stats are displayed in the ProfileWidget hover card that appears when hovering over a username in feeds, comments, and the leaderboard.
Followers & Following Lists
Paginated endpoints for listing a user's followers and the users they follow:
GET /api/hub/followers?userId=...&limit=20&offset=0
GET /api/hub/following?userId=...&limit=20&offset=0
Both return profile data (username, slug, avatar, bio) and a hasMore flag for pagination.
Notifications
The follow system triggers two types of notifications via database triggers:
new_follower — When user A follows user B, user B receives a notification linking to user A's profile
follower_post — When a user publishes a new visible post, all followers are notified with the post title and a direct link
Users who have muted a space are excluded from follower_post notifications for posts in that space.
