Circles Feature Documentation

Overview

Circles are custom friend groups that allow users to create targeted sharing communities. They provide a middle ground between public posts and direct friends - more private than public, more flexible than friends-only sharing. Users can discover new friends through public circles while maintaining privacy for their content.

Key Features

• Create Custom Circles: Users can create circles with custom names, descriptions, colors, and icons
• Circle Discovery: Public circles allow users to find new friends and communities
• Targeted Sharing: Share posts and fishing log entries to specific circles
• Member Management: Add/remove members, join/leave circles
• Privacy Control: Circles can be private (invite-only) or public (discoverable)

Use Cases

1. Fishing Buddies Circle: Create a circle for your regular fishing partners
2. Family Circle: Share fishing trips with family members
3. Local Anglers Circle: Public circle for finding local fishing enthusiasts
4. Tournament Team Circle: Private circle for tournament team members
5. Species-Specific Circle: Circle for anglers interested in specific fish species

Entity Structure

Circle

• Id (Guid) - Unique identifier
• OwnerUserId (Guid) - User who created the circle
• Name (string) - Circle name (e.g., "Fishing Buddies", "Family")
• Description (string, optional) - Circle purpose/description
• Color (string, optional) - Hex color for UI (e.g., "#FF5733")
• Icon (string, optional) - Icon name/emoji (e.g., "🎣", "family")
• IsPublic (bool) - Allow others to discover and join
• CreatedAt, UpdatedAt - Timestamps
• Members (ICollection<CircleMember>) - Circle members

CircleMember

• Id (int) - Unique identifier
• CircleId (Guid) - The circle
• UserId (Guid) - The member user
• AddedAt (DateTime) - When user was added to circle

API Endpoints

Circle Management

Base URL: /api/circle

• GET /api/circle - Get all circles owned by current user
• GET /api/circle/memberships - Get circles user is a member of (but doesn't own)
• GET /api/circle/{id} - Get a specific circle (must be owner or member)
• POST /api/circle - Create a new circle
• PUT /api/circle/{id} - Update a circle (owner only)
• DELETE /api/circle/{id} - Delete a circle (owner only)

Member Management

• POST /api/circle/{id}/members - Add a member to circle (owner only)
• DELETE /api/circle/{id}/members/{userId} - Remove member (owner or self)
• POST /api/circle/{id}/join - Join a public circle
• POST /api/circle/{id}/leave - Leave a circle (member removing themselves)

Discovery

• GET /api/circle/discover - Discover public circles (paginated, searchable)

Integration with Posts and Logs

Posts

Posts can be shared to circles using PostVisibility.Circle:

POST /api/social/posts
{
  "content": "Caught a huge bass today!",
  "visibility": "Circle",
  "sharedWithCircleId": "circle-guid-here"
}

Validation:

• SharedWithCircleId is required when Visibility is Circle
• User must be owner or member of the circle
• Circle must exist

Fishing Log Entries

Log entries can be shared to circles using LogVisibility.Circle:

POST /api/fishinglog/entries
{
  "caughtAt": "2025-12-01T10:00:00Z",
  "latitude": 45.123,
  "longitude": -93.456,
  "visibility": "Circle",
  "sharedWithCircleId": "circle-guid-here"
}

Validation:

• SharedWithCircleId is required when Visibility is Circle
• User must be owner or member of the circle
• Circle must exist

Visibility Logic

Post Visibility

• Public: Visible to all authenticated users
• Private: Visible only to the post owner
• Friends: Visible to mutual friends
• Circle: Visible only to members of the specified circle

Log Entry Visibility

• Public: Visible to all authenticated users (respects privacy settings)
• Private: Visible only to the entry owner
• Friends: Visible to mutual friends
• Circle: Visible only to members of the specified circle

Authorization

• View Circle: Owner or member can view circle details
• Create Circle: Any authenticated user
• Update Circle: Owner only
• Delete Circle: Owner only (cannot delete if circle is in use)
• Add Member: Owner only
• Remove Member: Owner or member removing themselves
• Join Circle: Any authenticated user (if circle is public)
• Leave Circle: Member removing themselves

Security Considerations

• Users cannot see circles they're not members of (returns 404)
• Circle owners cannot be removed from their own circles
• Circles in use (posts/logs shared with them) cannot be deleted
• Circle membership is validated before sharing content
• Public circles are discoverable but joining still requires authentication

Frontend Integration

Creating a Circle

const createCircle = async (name: string, description?: string) => {
  const response = await apiClient.post('/api/circle', {
    name,
    description,
    color: '#007AFF',
    icon: '🎣',
    isPublic: false
  });
  return response.data;
};

Sharing to a Circle

const sharePostToCircle = async (content: string, circleId: string) => {
  const response = await apiClient.post('/api/social/posts', {
    content,
    visibility: 'Circle',
    sharedWithCircleId: circleId
  });
  return response.data;
};

Discovering Circles

const discoverCircles = async (search?: string) => {
  const response = await apiClient.get('/api/circle/discover', {
    params: { search, page: 1, pageSize: 20 }
  });
  return response.data;
};

Differences from Friends and Clubs

Circles vs Friends

• Friends: One-to-one mutual relationships
• Circles: One-to-many groups created by users
• Use Case: Circles for group sharing, Friends for individual connections

Circles vs Clubs

• Clubs: Formal organizations with structure, events, membership management
• Circles: Informal friend groups for targeted sharing
• Use Case: Clubs for organized groups, Circles for casual friend groups

Future Enhancements

• Circle invitations (invite users to join)
• Circle roles (Admin, Member)
• Circle activity feed
• Circle statistics (member count, post count)
• Circle templates (pre-configured circles)
• Circle notifications (new posts in circles)
• Circle search/filtering improvements