Communities

Overview

The Communities app enables users to create and join interest-based groups on Jend-Z, fostering focused discussions and content sharing around specific topics. Communities are organized by categories and support rich media, hashtag integration, and membership management. This system helps users discover like-minded individuals and engage in meaningful conversations within their areas of interest.

Data Models

Community Model

The central Community model represents user groups organized around specific interests or topics.

Core Fields

• id (UUID): Unique identifier
• name (CharField): Community display name (unique, max 255 characters)
• description (TextField): Community description and purpose (optional)
• owner (ForeignKey): Community creator and administrator (CustomUser)
• is_verified (BooleanField): Official verification status
• created_at (DateTimeField): Community creation timestamp
• updated_at (DateTimeField): Last modification timestamp

Categorization

• category (ForeignKey): Community category for organization

Content & Media

• hashtags (ManyToManyField): Associated hashtags (auto-extracted from description)
• avatar (ImageField): Community profile image
• banner (ImageField): Community cover/header image

Analytics

• members_count (PositiveIntegerField): Total member count
• posts_count (PositiveIntegerField): Total posts in community

Automatic Behaviors

• Hashtag Extraction: Automatically extracts hashtags from description
• Member Count Updates: Real-time member count maintenance

CommunityCategory Model

Organizes communities into specific topic areas.

Fields

• id (UUID): Unique identifier
• name (CharField): Category name (unique, max 100 characters)
• group (ForeignKey): Parent category group (optional)
• description (TextField): Category description (optional)

Constraints

• Unique Together: Name and group combination must be unique
• Ordering: Sorted by group name, then category name

CommunityCategoryGroup Model

Higher-level grouping for organizing related categories.

Fields

• id (UUID): Unique identifier
• name (CharField): Group name (unique, max 255 characters)

Example Structure:

Technology (Group)
├── Software Development (Category)
├── Mobile Apps (Category)
└── Artificial Intelligence (Category)

Entertainment (Group)
├── Movies & TV (Category)
├── Music (Category)
└── Gaming (Category)

CommunityMembership Model

Tracks user participation in communities.

Fields

• id (UUID): Unique identifier
• user (ForeignKey): Community member (CustomUser)
• community (ForeignKey): Joined community
• joined_at (DateTimeField): Membership start timestamp

Constraints

• Unique Together: Each user can only join a community once

API Endpoints

Community Management

1. List Communities

Endpoint: GET /api/communities/communities/

Description: Retrieve communities with filtering and search capabilities.

Query Parameters:

• category (UUID): Filter by category ID
• search (string): Search in community name and description
• page (integer): Page number for pagination

Response:

{
  "count": 45,
  "next": "http://api.example.com/api/communities/communities/?page=2",
  "previous": null,
  "results": [
    {
      "id": "community-uuid",
      "name": "Lagos Tech Hub",
      "description": "A community for tech enthusiasts in Lagos. Share ideas, collaborate on projects, and network with fellow developers. #technology #lagos #coding",
      "category": {
        "id": "category-uuid",
        "name": "Software Development",
        "description": "Communities focused on software development and programming"
      },
      "avatar": "https://example.com/media/communities/avatars/tech-hub.jpg",
      "banner": "https://example.com/media/communities/banners/tech-banner.jpg",
      "hashtags": ["technology", "lagos", "coding"],
      "is_verified": false,
      "owner": "techleader",
      "members_count": 1250,
      "posts_count": 342,
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-20T14:22:00Z"
    },
    {
      "id": "community-uuid-2",
      "name": "Abuja Food Lovers",
      "description": "Discover the best local restaurants, street food, and traditional dishes in Nigeria's capital city. #food #abuja #restaurants",
      "category": {
        "id": "category-uuid-2",
        "name": "Food & Dining",
        "description": "Communities about food, restaurants, and culinary experiences"
      },
      "avatar": "https://example.com/media/communities/avatars/food-lovers.jpg",
      "banner": "https://example.com/media/communities/banners/food-banner.jpg",
      "hashtags": ["food", "abuja", "restaurants"],
      "is_verified": true,
      "owner": "foodie_abuja",
      "members_count": 875,
      "posts_count": 156,
      "created_at": "2024-01-10T08:15:00Z",
      "updated_at": "2024-01-19T16:45:00Z"
    }
  ]
}

2. Create Community

Endpoint: POST /api/communities/communities/

Authentication: Bearer token required

Content-Type: multipart/form-data (for image uploads)

Request Body:

{
  "name": "Nollywood Enthusiasts",
  "description": "A community for fans of Nigerian cinema. Discuss latest movies, share reviews, and connect with fellow Nollywood lovers. #nollywood #movies #entertainment",
  "category": "category-uuid",
  "avatar": "avatar_image_file",
  "banner": "banner_image_file"
}

Required Fields:

• name: Community name (must be unique)
• category: UUID of existing category

Success Response:

{
  "id": "new-community-uuid",
  "name": "Nollywood Enthusiasts",
  "description": "A community for fans of Nigerian cinema. Discuss latest movies, share reviews, and connect with fellow Nollywood lovers. #nollywood #movies #entertainment",
  "category": "category-uuid",
  "hashtags": ["nollywood", "movies", "entertainment"],
  "avatar": "https://example.com/media/communities/avatars/nollywood.jpg",
  "banner": "https://example.com/media/communities/banners/nollywood-banner.jpg"
}

3. Get Community Details

Endpoint: GET /api/communities/communities/{community_id}/

Response: Same format as create community response, with full community information.

4. Update Community

Endpoint: PUT /api/communities/communities/{community_id}/ or PATCH /api/communities/communities/{community_id}/

Authentication: Bearer token required (must be community owner)

Note: The is_verified field cannot be updated through this endpoint.

5. Delete Community

Endpoint: DELETE /api/communities/communities/{community_id}/

Authentication: Bearer token required (must be community owner)

Community Membership

1. Join Community

Endpoint: POST /api/communities/communities/{community_id}/join/

Authentication: Bearer token required

Description: Add current user to community membership.

Success Response:

{
  "message": "Joined Lagos Tech Hub."
}

Already Member Response:

{
  "message": "Already a member."
}

Side Effects:

• Creates CommunityMembership record
• Updates community's members_count

2. Leave Community

Endpoint: POST /api/communities/communities/{community_id}/leave/

Authentication: Bearer token required

Description: Remove current user from community membership.

Success Response:

{
  "message": "Left Lagos Tech Hub."
}

Not Member Response:

{
  "message": "Not a member of this community."
}

Side Effects:

• Deletes CommunityMembership record
• Updates community's members_count

3. Check Membership Status

Endpoint: GET /api/communities/communities/{community_id}/is_member/

Authentication: Bearer token required

Description: Check if current user is a member of the community.

Response:

{
  "is_member": true
}

4. Get User's Communities

Endpoint: GET /api/communities/memberships/my_communities/

Authentication: Bearer token required

Description: Retrieve all communities the current user has joined.

Response:

[
  {
    "id": "membership-uuid",
    "user": "current_user",
    "community": {
      "id": "community-uuid",
      "name": "Lagos Tech Hub",
      "description": "A community for tech enthusiasts in Lagos...",
      "category": {
        "id": "category-uuid",
        "name": "Software Development",
        "description": "Communities focused on software development"
      },
      "avatar": "https://example.com/media/communities/avatars/tech-hub.jpg",
      "banner": "https://example.com/media/communities/banners/tech-banner.jpg",
      "hashtags": ["technology", "lagos", "coding"],
      "is_verified": false,
      "owner": "techleader",
      "members_count": 1250,
      "posts_count": 342,
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-20T14:22:00Z"
    },
    "joined_at": "2024-01-16T09:30:00Z"
  }
]

Community Categories

1. List Categories

Endpoint: GET /api/communities/categories/

Description: Retrieve all available community categories.

Response:

{
  "count": 25,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "category-uuid",
      "name": "Software Development",
      "description": "Communities focused on software development and programming"
    },
    {
      "id": "category-uuid-2",
      "name": "Food & Dining",
      "description": "Communities about food, restaurants, and culinary experiences"
    },
    {
      "id": "category-uuid-3",
      "name": "Entertainment",
      "description": "Movies, music, gaming, and other entertainment topics"
    }
  ]
}

2. Get Category Details

Endpoint: GET /api/communities/categories/{category_id}/

Response: Individual category information with same format as list item.

Category Groups

1. List Category Groups

Endpoint: GET /api/communities/category-groups/

Description: Retrieve category groups with their associated categories.

Response:

{
  "count": 8,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "group-uuid",
      "name": "Technology",
      "categories": [
        {
          "id": "category-uuid-1",
          "name": "Software Development",
          "description": "Communities focused on software development and programming"
        },
        {
          "id": "category-uuid-2",
          "name": "Mobile Apps",
          "description": "Mobile application development and design"
        },
        {
          "id": "category-uuid-3",
          "name": "Artificial Intelligence",
          "description": "AI, machine learning, and automation discussions"
        }
      ]
    },
    {
      "id": "group-uuid-2",
      "name": "Lifestyle",
      "categories": [
        {
          "id": "category-uuid-4",
          "name": "Food & Dining",
          "description": "Communities about food, restaurants, and culinary experiences"
        },
        {
          "id": "category-uuid-5",
          "name": "Travel & Tourism",
          "description": "Travel destinations, tips, and experiences"
        }
      ]
    }
  ]
}

2. Get Category Group Details

Endpoint: GET /api/communities/category-groups/{group_id}/

Response: Individual group information with associated categories.

Membership Management

1. List Memberships

Endpoint: GET /api/communities/memberships/

Authentication: Bearer token required

Description: Retrieve membership records (admin functionality).

Response:

{
  "count": 150,
  "next": "http://api.example.com/api/communities/memberships/?page=2",
  "previous": null,
  "results": [
    {
      "id": "membership-uuid",
      "user": "username1",
      "community": {
        "id": "community-uuid",
        "name": "Lagos Tech Hub",
        "description": "A community for tech enthusiasts...",
        "category": {
          "id": "category-uuid",
          "name": "Software Development",
          "description": "Communities focused on software development"
        },
        "members_count": 1250,
        "posts_count": 342
      },
      "joined_at": "2024-01-16T09:30:00Z"
    }
  ]
}

Search & Filtering

Community Discovery

Text Search

Usage: GET /api/communities/communities/?search=tech

Search Fields:

• Community name
• Community description

Examples:

GET /api/communities/communities/?search=lagos
GET /api/communities/communities/?search=food
GET /api/communities/communities/?search=nollywood

Category Filtering

Usage: GET /api/communities/communities/?category=category-uuid

Use Cases:

• Browse communities in specific categories
• Discover communities by interest area
• Filter results for targeted browsing

Combined Filtering

GET /api/communities/communities/?category=tech-category-uuid&search=mobile

Hashtag Integration

Automatic Hashtag Extraction

Communities automatically extract and link hashtags from their descriptions:

Extraction Process

1. Content Analysis: Scans community description for hashtag patterns
2. Hashtag Creation: Creates hashtag records if they don't exist
3. Association: Links community to extracted hashtags
4. Updates: Re-processes hashtags when description changes

Usage Examples

# Community description with hashtags
description = "Join Lagos tech enthusiasts! #technology #lagos #startups #innovation"

# Automatically extracts: ["technology", "lagos", "startups", "innovation"]
# Creates hashtag records and associates with community

Benefits

• Discoverability: Communities findable via hashtag searches
• Cross-Platform: Hashtags work across posts and communities
• Trend Tracking: Popular hashtags indicate trending topics
• Content Organization: Automatic categorization of content

Media Management

Community Images

Avatar Images

• Purpose: Community profile/logo image
• Storage: communities/avatars/ directory
• Usage: Displayed in community lists and headers
• Recommended: Square aspect ratio for consistent display

Banner Images

• Purpose: Community cover/header image
• Storage: communities/banners/ directory
• Usage: Featured prominently on community pages
• Recommended: Wide aspect ratio for header display

Upload Process

1. Multipart Upload: Images uploaded via multipart/form-data
2. Automatic Processing: Images processed and stored
3. URL Generation: Full URLs provided in API responses
4. Format Support: JPEG, PNG, GIF, WebP

Community Ownership & Permissions

Owner Privileges

• Full Control: Update community details, description, media
• Membership Management: Access to member lists and analytics
• Content Moderation: Ability to moderate community posts
• Settings Management: Configure community rules and settings

Permission System

• Public Viewing: Anyone can view community information
• Authenticated Joining: Must be logged in to join communities
• Owner Actions: Only owners can modify community settings
• Read-Only Access: Non-owners have read-only access to community data

Verification System

• Manual Process: Verification controlled by platform administrators
• Trust Indicator: Verified badge indicates official/trusted communities
• Enhanced Features: Verified communities may have additional privileges

Analytics & Metrics

Member Analytics

• Real-time Counts: Member count updated on join/leave actions
• Growth Tracking: Monitor community growth over time
• Engagement Metrics: Track member activity and participation

Content Analytics

• Post Counts: Track total posts within communities
• Activity Levels: Monitor posting frequency and engagement
• Popular Content: Identify trending posts and discussions

Usage Patterns

• Member Retention: Track how long users stay in communities
• Cross-Community: Analyze users' community participation patterns
• Category Performance: Monitor which categories attract most users

Integration with Other Apps

Posts Integration

• Community Posts: Posts can be associated with communities
• Member-Only Content: Posts visible only to community members
• Community Feeds: Dedicated feeds for community content

Hashtags Integration

• Automatic Linking: Community hashtags connect to broader hashtag system
• Cross-Discovery: Users can discover communities via hashtag searches
• Trend Analysis: Community hashtags contribute to platform trends

User Profiles Integration

• Community Display: User profiles show joined communities
• Activity Tracking: Community participation displayed in user activity
• Social Proof: Community memberships indicate user interests

Error Handling

Common Error Responses

Community Name Conflict:

{
  "name": ["Community with this name already exists."]
}

Category Not Found:

{
  "category": ["Invalid pk \"invalid-uuid\" - object does not exist."]
}

Permission Denied:

{
  "detail": "You do not have permission to perform this action."
}

Already Member:

{
  "message": "Already a member."
}

Not a Member:

{
  "message": "Not a member of this community."
}

HTTP Status Codes

• 200 OK: Successful operation
• 201 Created: Community created successfully
• 400 Bad Request: Validation errors or invalid operation
• 401 Unauthorized: Authentication required
• 403 Forbidden: Permission denied
• 404 Not Found: Community or resource not found
• 500 Internal Server Error: Server error