Social & Groups Service

Overview

Provides chat, guild, and social networking features across games. Enables players to form groups and communicate in real time.

Responsibilities

• Deliver real-time chat and presence notifications
• Manage guild creation, membership, and roles
• Maintain friend lists and cross-game social graphs
• Feed chat logs to the Logging & Admin Service for moderation

Architecture / Design Notes

• Uses WebSocket channels for chat delivery.
• Stores guild and friend relationships in PostgreSQL.
• Integrates with the Logging & Admin Service for moderation events.
• Messages are briefly cached in Redis streams to smooth bursts of activity and enable delivery retries.
• Guild creation and membership changes participate in Saga workflows so other services remain consistent. See Transaction Strategies.
• Chat history and guild data are stored with a tenantId so conversations are isolated per game. Redis stream keys also include this prefix. See Multi-Tenancy.
• APIs require authenticated JWTs from the Account Service and all inter-service communication is encrypted via mutual TLS, following the Security Architecture.
• Utilizes the Shared Libraries for DTO definitions, logging interceptors, and Micrometer metrics.

Key Features

• Global and guild chat rooms.
• Private messaging and presence indicators.
• Guild creation and membership management.
• Friend lists scoped both to individual games and to overall accounts.
• Cross-game presence lets players know when friends are online in any hosted game.
• In-game social chat plus account-to-account direct messaging.

Data Model

• chat_message table persists guild and private messages.
• guild and guild_member tables store group ownership and membership roles.
• friend_link table tracks account or character friendships and blocks.

Chat Pipeline

• Messages are published to Redis streams and fanned out to WebSocket channels through the Spring Cloud Gateway.
• Guild and direct messages share a common persistence model for history.

gRPC/REST APIs

• SendMessage – publishes a chat message to an in-game channel or player.
• SendAccountMessage – delivers a direct message between account holders.
• CreateGuild – establishes a new guild with an owner account.
• AddFriend – adds a friend relationship at the game or account level.

Dependencies

• Internal:
  • Account Service for user identities.
  • Logging & Admin Service consumes chat logs for moderation.
• External: PostgreSQL for social data.

See Gateway Architecture, Deployment Environments, and Protocol Bridging for details on shared infrastructure components.

Operational Notes

• Runs as a Kubernetes Deployment. WebSocket chat traffic scales horizontally with multiple replicas.
• The service publishes metrics scraped by Prometheus and forwards logs through Fluent Bit to Elasticsearch with trace IDs from OpenTelemetry.
• Health is monitored via /actuator/health; see Deployment Environments for differences between local Docker Compose and production.

Proto Files

The social APIs are defined in ../../../../protos/social-groups/v1. Regenerate the service stubs with ./gradlew generateProto whenever the proto files change.

📚 Related Documentation

• System Architecture Overview

• Multi-Tenancy

• Service Responsibility Matrix

• User Journeys – Social Interaction

• Redis Architecture

• gRPC API Style & Versioning Guidelines

• Shared Libraries Overview

• Database Migrations

• Backup & Disaster Recovery

• Logging & Monitoring

• Authentication & Authorization

• Security Architecture

• Testing Strategy

• CI/CD Pipeline

• System Architecture Diagram

• System Context Diagram

Future Enhancements

• Rich moderation tools for chat.
• Optional voice chat integration.