dbbasic-follows

Social Graph Management for DBBasic

A complete social graph module for DBBasic applications, providing follow relationships, friend detection, and intelligent connection suggestions.

Features

• Follow System: One-directional follow relationships
• Friend Detection: Automatic identification of mutual follows
• Smart Suggestions: Algorithm-driven follow and friend recommendations
• Admin Interface: Built-in UI for managing relationships
• Fast Lookups: TSV-based storage with indexed queries
• Simple API: Clean, intuitive Python interface

Installation

pip install dbbasic-follows

Quick Start

from dbbasic_follows import Follows

# Initialize
follows = Follows()

# Create follow relationships
follows.follow(follower_id=1, followee_id=2)
follows.follow(follower_id=2, followee_id=1)  # Now they're friends!

# Check relationships
follows.is_following(1, 2)  # True
follows.are_friends(1, 2)   # True

# Get lists
followers = follows.get_followers(user_id=2)
following = follows.get_following(user_id=1)
friends = follows.get_friends(user_id=1)

# Get suggestions
suggestions = follows.suggest_follows(user_id=1, limit=10)
friend_suggestions = follows.suggest_friends(user_id=1)

# Get stats
stats = follows.get_stats(user_id=1)
# {'followers': 100, 'following': 50, 'friends': 30}

Core Concepts

Follows

A follow is a one-directional relationship where User A follows User B. This doesn't mean B follows A back.

follows.follow(follower_id=1, followee_id=2)

Friends

A friend relationship exists when both users follow each other (mutual follow).

# User 1 follows User 2
follows.follow(1, 2)

# User 2 follows User 1 back
follows.follow(2, 1)

# Now they're friends!
follows.are_friends(1, 2)  # True

API Reference

Core Operations

follow(follower_id, followee_id)

Create a follow relationship.

follows.follow(follower_id=1, followee_id=2)
# Returns: True if created, False if already exists

unfollow(follower_id, followee_id)

Remove a follow relationship.

follows.unfollow(follower_id=1, followee_id=2)
# Returns: True if deleted, False if didn't exist

is_following(follower_id, followee_id)

Check if user A follows user B.

is_following = follows.is_following(1, 2)
# Returns: True or False

are_friends(user_id_a, user_id_b)

Check if two users are friends (mutual follows).

are_friends = follows.are_friends(1, 2)
# Returns: True or False

Querying Relationships

get_followers(user_id, limit=None)

Get list of users who follow the specified user.

followers = follows.get_followers(user_id=2, limit=50)
# Returns: [{'follower_id': 1, 'followee_id': 2, 'created_at': '...'}, ...]

get_following(user_id, limit=None)

Get list of users that the specified user follows.

following = follows.get_following(user_id=1, limit=50)
# Returns: [{'follower_id': 1, 'followee_id': 2, 'created_at': '...'}, ...]

get_friends(user_id, limit=None)

Get list of friend user IDs (mutual follows).

friends = follows.get_friends(user_id=1)
# Returns: [2, 3, 5, 8, ...]

Counts

get_follower_count(user_id)

Get count of followers.

count = follows.get_follower_count(user_id=1)
# Returns: 100

get_following_count(user_id)

Get count of users being followed.

count = follows.get_following_count(user_id=1)
# Returns: 50

get_friend_count(user_id)

Get count of friends.

count = follows.get_friend_count(user_id=1)
# Returns: 30

Suggestions

suggest_follows(user_id, limit=10)

Suggest users to follow based on social graph analysis.

Algorithm:

1. Find users followed by people you follow (2nd degree connections)
2. Rank by number of mutual connections
3. Exclude users already followed
4. Exclude self

suggestions = follows.suggest_follows(user_id=1, limit=10)
# Returns: [
#   {'user_id': 5, 'score': 3, 'mutual_connections': [2, 3, 4]},
#   {'user_id': 7, 'score': 2, 'mutual_connections': [2, 8]},
#   ...
# ]

suggest_friends(user_id, limit=10)

Suggest potential friends (users who follow you but you don't follow back).

suggestions = follows.suggest_friends(user_id=1, limit=10)
# Returns: [
#   {'user_id': 10, 'score': 5, 'follows_you': True},
#   {'user_id': 12, 'score': 3, 'follows_you': True},
#   ...
# ]

Statistics

get_stats(user_id)

Get comprehensive social graph statistics for a user.

stats = follows.get_stats(user_id=1)
# Returns: {
#   'followers': 100,
#   'following': 50,
#   'friends': 30
# }

Data Storage

The module uses dbbasic-tsv for storage, creating a follows.tsv file in your data directory.

Schema

follower_id    followee_id    created_at              status
1              2              2024-01-15T10:30:00     active
2              1              2024-01-15T10:31:00     active

Indexes

The module automatically creates indexes on:

• follower_id - Fast lookups of "who does user X follow?"
• followee_id - Fast lookups of "who follows user Y?"

Admin Interface

When integrated with dbbasic-admin, the module provides a web UI for managing follow relationships.

Access at: http://localhost:8000/admin/follows

Features:

• View all follow relationships
• See follower → following connections
• Delete relationships
• Status indicators

Integration Example

Basic App

from dbbasic_web import App
from dbbasic_follows import Follows

app = App()
follows = Follows()

@app.route('/api/follow/<int:user_id>')
def follow_user(request, user_id):
    current_user_id = request.user.id
    follows.follow(current_user_id, user_id)
    return {'success': True}

@app.route('/api/unfollow/<int:user_id>')
def unfollow_user(request, user_id):
    current_user_id = request.user.id
    follows.unfollow(current_user_id, user_id)
    return {'success': True}

@app.route('/api/followers')
def my_followers(request):
    current_user_id = request.user.id
    followers = follows.get_followers(current_user_id)
    return {'followers': followers}

@app.route('/api/suggestions')
def get_suggestions(request):
    current_user_id = request.user.id
    suggestions = follows.suggest_follows(current_user_id, limit=10)
    return {'suggestions': suggestions}

With dbbasic-accounts

from dbbasic_accounts import Accounts
from dbbasic_follows import Follows

accounts = Accounts()
follows = Follows()

# Create users
user1 = accounts.create(username="alice", password="secret")
user2 = accounts.create(username="bob", password="secret")

# Create social graph
follows.follow(user1['id'], user2['id'])

# Get user's social stats
stats = follows.get_stats(user1['id'])
print(f"Alice is following {stats['following']} users")

Use Cases

Social Network

Build social following systems with automatic friend detection.

Content Platform

Enable users to follow creators and get personalized feeds.

Community Site

Connect users with similar interests through mutual follows.

Recommendation Engine

Use the social graph to recommend content, products, or connections.

Future Enhancements

The module is designed to support future features:

• Content Recommendations: Use the social graph to recommend posts, products, or content based on who users follow
• Influence Scores: Calculate user influence based on follower count and engagement
• Communities: Detect clusters of highly connected users
• Activity Feeds: Generate personalized feeds based on follows
• Privacy Controls: Block users, private accounts, follow requests

These features can be built in separate modules that leverage dbbasic-follows as the core social graph.

Performance

• Fast Lookups: Indexed queries on follower/followee IDs
• Efficient Storage: TSV format is compact and human-readable
• Scalable: Suitable for small to medium apps (< 100k users)
• No Database: No PostgreSQL, MySQL, or MongoDB required

Requirements

• Python >= 3.10
• dbbasic-web >= 0.1.10
• dbbasic-tsv >= 1.0.0
• dbbasic-admin >= 0.1.1 (optional, for admin UI)
• dbbasic-accounts >= 0.1.0 (for user management)

License

MIT License - feel free to use in any project.

Contributing

Contributions welcome! Please submit issues and pull requests on GitHub.

Links

• Documentation: https://github.com/askrobots/dbbasic-follows
• DBBasic: https://dbbasic.com
• Issues: https://github.com/askrobots/dbbasic-follows/issues

Example Apps

See the examples/ directory for complete working applications:

• Social network demo
• Content platform with follows
• Friend suggestion system

---

Built with ❤️ using DBBasic - radically simple Python web framework