SocialPie 🥧

A production-grade, plugin-first chat platform with Discord/Slack-level UI polish

Modern async chat server and client built with Python 3.10+. Everything is a plugin - from user management to content moderation. Beautiful GUI, professional codebase, production-ready.

---

✨ Highlights

🎨 Premium GUI - Discord/Slack-Level Polish

Professional Interface: User sidebar with avatars Message bubbles with timestamps Online status indicators Smooth hover animations Dark theme (light coming soon)

User Profiles: Custom avatar colors & emojis Display names & status messages Privacy controls Persistent preferences Settings dialog (⚙️)

🔌 Plugin Ecosystem - 6 Official Plugins Included

Plugin	Purpose	Key Features
server-commands	Essential management	/help, /list, /whisper, /kick, /mute, /broadcast
rate-limiter	Spam prevention	Sliding window algorithm, auto-mute, warnings
profanity-filter	Content moderation	Word blacklist, regex patterns, block/replace/warn
welcome-bot	User greetings	Custom messages, /usercount
chat-logger	Message logging	JSON/CSV/text formats, /logstats
dice-roller	Fun commands	/roll, multiple dice types

🏗️ Modern Architecture - Production-Quality Codebase

• 100% type hints - Full mypy strict mode
• Async/await - Non-blocking I/O throughout
• 79.75% test coverage - 216 passing tests
• Structured logging - Beautiful logs with structlog
• Configuration system - YAML, env vars, command-line args
• Error handling - Robust port conflict resolution, graceful failures

---

🚀 Quick Start

Installation

# Clone and install
git clone https://github.com/EricsonWillians/SocialPie.git
cd SocialPie
pip install -e ".[all]"

Start Server

# Quick start
socialpie server

# Custom configuration
socialpie server --host 0.0.0.0 --port 9000

# With plugins
socialpie server --plugin-dir ./my-plugins

Port already in use? No problem - SocialPie will detect conflicts and offer to kill the process!

Start Client

# GUI client (premium interface)
socialpie client --nickname Alice

# Connect to remote server
socialpie client --host 192.168.1.100 --port 9000

Initialize Config

# Create default configuration
socialpie init

---

🎯 Core Features

Plugin System

Everything is extensible. Modify any behavior through plugins.

from socialpie.plugins import ServerPlugin, hook, command

class MyPlugin(ServerPlugin):
    @hook("before_message", priority=100)
    async def transform_message(self, message_data):
        """Modify messages before they're sent."""
        message_data["content"] = message_data["content"].upper()
        return message_data

    @command("hello", description="Say hello")
    async def hello_command(self, client, args):
        """Handle /hello command."""
        return f"Hello, {client.username}! 👋"

Plugin Features:

• 🎯 Hook system - Intercept at 10+ extension points
• ⚡ Event bus - Pub/sub messaging between plugins
• 🔑 Service registry - Share functionality between plugins
• 🛡️ Permission system - Fine-grained access control
• ⚙️ Configuration - YAML-based settings per plugin

Premium GUI Client

Modern chat interface built with Tkinter.

Features:

• 👥 User Sidebar - See who's online with avatars
• 💬 Message Bubbles - Professional chat layout
• ⚙️ Settings Dialog - Customize your profile
• 🎨 Avatar System - Color-coded initials or custom emojis
• 🔔 Status Indicators - Online/offline dots
• ⏰ Timestamps - Track conversation flow

Profile Customization:

• Display name (override username)
• Custom status message
• Avatar color (color picker)
• Avatar emoji (🚀 instead of initials)
• Notifications & sound preferences
• Privacy controls (online status, whispers)

Moderation Suite

Complete spam & abuse prevention.

Rate Limiter

• Sliding window algorithm - Precise rate limiting
• Per-user tracking - Independent limits
• Warning system - Notify before enforcement
• Auto-mute - Temporary ban on violation
• Admin exemptions - Bypass for trusted users

Commands: /ratelimit, /unmute

Profanity Filter

• Word blacklist - Customizable forbidden words
• Whitelist - Exceptions for false positives
• Regex patterns - Advanced filtering (emails, URLs, etc.)
• Multiple actions:
  • Block - Stop message entirely
  • Replace - Censor with asterisks
  • Warn - Allow with warning

Commands: /filtertest, /filterstats, /addword, /removeword

Server Commands

Essential management tools.

Command	Description	Permission
/help [command]	Show available commands	-
/list	Show online users	-
/me <action>	Action message (Alice waves)	-
/whisper <user> <msg>	Private message	users.whisper
/kick <user> [reason]	Remove user	users.kick
/mute <user> <seconds>	Temporary mute	users.mute
/broadcast <message>	Server announcement	server.broadcast

---

🔧 Plugin Development

Creating a Plugin

1. Plugin Structure:

my_plugin/
├── plugin.py        # Plugin class
├── plugin.yaml      # Manifest & config
├── README.md        # Documentation
└── __init__.py      # Package init

2. Plugin Class:

from socialpie.plugins import ServerPlugin, hook, command, event_listener

class MyPlugin(ServerPlugin):
    async def on_load(self):
        """Called when plugin loads."""
        self.logger.info("plugin_loaded")
        
    @hook("before_message", priority=100)
    async def filter_spam(self, message_data):
        """Hook into message processing."""
        if "spam" in message_data["content"].lower():
            return None  # Block message
        return message_data
    
    @command("status", description="Show server status")
    async def status_command(self, client, args):
        """Add a chat command."""
        return f"Server is running! Users online: {len(self.server.clients)}"
    
    @event_listener("user_joined")
    async def on_join(self, event):
        """React to events."""
        username = event.data["username"]
        await self.server.broadcast_message(f"Welcome {username}!")

3. Plugin Manifest (plugin.yaml):

manifest:
  name: my-plugin
  version: 1.0.0
  author: Your Name
  description: Does amazing things
  type: server
  entry_point: plugin:MyPlugin
  permissions:
    - messages.modify

config:
  enabled: true
  custom_setting: value

Available Decorators

@hook("hook_name", priority=10)         # Intercept at extension points
@command("cmd", aliases=["c"])          # Add chat commands  
@event_listener("event_type")           # Subscribe to events
@service("service_name")                 # Provide service to other plugins
@require_permission("users.ban")         # Permission check
@throttle(max_calls=3, period=60)        # Rate limiting
@deprecated(since="1.0", removed="2.0")  # Mark as deprecated

Extension Points (Hooks)

Server Hooks:

• server_start, server_stop, server_ready
• connection_open, connection_close
• before_message ⭐ (can modify or block)
• after_message ⭐
• broadcast_message
• command_executed, command_error

Priority System:

• Higher priority runs first (100 > 90 > 10)
• Rate limiter: priority 100
• Profanity filter: priority 90

Events

Built-in Events:

• server_start, server_stop, server_ready
• user_connected, user_disconnected
• user_joined, user_left
• message_sent, message_received
• plugin_loaded, plugin_enabled, plugin_disabled

Custom Events:

# Emit
await self.event_bus.emit("custom_event", data={"key": "value"})

# Listen
@event_listener("custom_event")
async def handle_custom(self, event):
    print(event.data)

---

📚 Documentation

Official Plugins

Each plugin includes comprehensive documentation:

• server-commands - README
• rate-limiter - README
• profanity-filter - README
• welcome-bot - README
• chat-logger - README

Architecture Guides

• MODERNIZATION_PLAN.md - Complete modernization strategy
• PLUGIN_DEVELOPMENT_GUIDE.md - Plugin development tutorial
• PLUGIN_ARCHITECTURE.md - Technical deep dive

---

🛠️ Development

Setup

# Install dev dependencies
pip install -e ".[dev]"

# Type checking
mypy src/socialpie

# Linting
ruff check src/socialpie

# Formatting
black src/socialpie
isort src/socialpie

# Testing
pytest
pytest --cov=socialpie --cov-report=html

Project Structure

SocialPie/
├── src/socialpie/
│   ├── core/              # Core functionality
│   │   ├── config.py      # Configuration system
│   │   ├── protocol.py    # Message protocol
│   │   └── profile.py     # User profiles ⭐ NEW
│   ├── server/            # Server implementation
│   │   └── server.py      # Async TCP server
│   ├── client/            # Client implementation
│   │   ├── client.py      # Async client
│   │   └── ui/
│   │       ├── gui.py     # Premium GUI ⭐ NEW
│   │       └── settings_dialog.py  # Settings UI ⭐ NEW
│   ├── plugins/           # Plugin system
│   │   ├── manager.py     # Plugin lifecycle
│   │   ├── base.py        # Base classes
│   │   └── decorators.py  # @hook, @command, etc.
│   ├── utils/
│   │   └── network.py     # Port conflict handling ⭐ NEW
│   └── cli.py             # CLI interface
├── plugins/official/      # Official plugins
│   ├── server_commands/   # ⭐ NEW
│   ├── rate_limiter/      # ⭐ NEW
│   ├── profanity_filter/  # ⭐ NEW
│   ├── welcome_bot/
│   ├── chat_logger/
│   └── dice_roller/
├── tests/                 # Test suite (216 tests, 79.75% coverage)
└── pyproject.toml         # Build configuration

Code Quality Metrics

Total Lines:      ~4,500 (plugins + core)
Test Coverage:    79.75% (216 tests passing)
Type Coverage:    100% (strict mypy)
Code Style:       black + ruff
Python Version:   3.10+

---

🎓 Use Cases

• Learning - Study modern Python async architecture
• LAN Chat - Team communication without internet
• Bot Platform - Build chatbots with the plugin API
• Prototyping - Rapidly prototype chat features
• Experimentation - Test plugin architectures, async patterns
• Education - Teach software architecture and design patterns

---

🤝 Contributing

Contributions welcome! Here's how:

1. Create Plugins - Share your awesome plugins
2. Report Bugs - Open issues with details
3. Improve Docs - Help others understand
4. Write Tests - Increase coverage (target: 90%)
5. Submit PRs - Fix issues or add features

Plugin Ideas:

• Message encryption (E2E)
• File sharing
• Voice chat integration
• Database persistence
• User authentication
• Bot framework
• Statistics dashboard

---

🌟 Features Roadmap

Completed ✅

• ✅ Plugin-first architecture
• ✅ Premium GUI with user profiles
• ✅ Moderation suite (rate limiting + profanity filter)
• ✅ 6 production plugins
• ✅ 79.75% test coverage
• ✅ Port conflict resolution
• ✅ Comprehensive documentation

In Progress 🚧

• 🚧 TUI (Terminal UI) client
• 🚧 Authentication system
• 🚧 Chat rooms/channels

Planned 📋

• 📋 Message persistence (database)
• 📋 End-to-end encryption
• 📋 File transfer
• 📋 Voice chat
• 📋 Plugin marketplace
• 📋 Docker deployment

---

📜 License

GNU General Public License v3.0 or later (GPL-3.0-or-later)

This project is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation.

See LICENSE for details.

---

🙏 Credits

Original Project (2015): Ericson Willians (Rederick Deathwill)

Modernization (2026): Complete rewrite with:

• Plugin-first architecture
• Modern async Python
• Production-grade UI
• Comprehensive testing
• Professional documentation

---

📊 Project Stats

Metric	Value
Lines of Code	~4,500
Test Coverage	79.75%
Tests	216 passing
Plugins	6 official
Python Version	3.10+
Type Coverage	100% (strict)
Code Style	black + ruff

---

🔗 Links

• Repository: https://github.com/EricsonWillians/SocialPie
• Issues: https://github.com/EricsonWillians/SocialPie/issues
• Original (2015): Completely modernized from a 10-year-old project

---

Made with ❤️ using modern Python and a plugin-first philosophy

⭐ Star this repo if you find it useful!