Eve library

Aphrodite Domain - Communication Architecture

Guide

Revision 1

On this page

Migration Status: Eve → Aphrodite (Oshun Domain)

This document provides a comprehensive analysis of inter-service communication patterns, protocols, and data flows in the Eve platform for migration planning.


Table of Contents#

  1. Communication Overview
  2. REST APIs
  3. WebSocket Communication
  4. Message Queues (Kafka)
  5. Event Bus Patterns
  6. gRPC Services
  7. Redis Pub/Sub & Caching
  8. Service-to-Service Integration
  9. Data Flow Diagrams
  10. Configuration Reference

Communication Overview#

The Eve platform uses a multi-protocol communication architecture optimized for different use cases:

Protocol Use Case Services
REST Client APIs, service endpoints User, Content, Analytics, Recommendation
WebSocket Real-time bidirectional Chat, Notifications, Stream events
Kafka Event streaming, fan-out Chat, Stream, Analytics
gRPC Service-to-service RPC Stream Service
Redis Pub/Sub Socket.io horizontal scaling Chat, Notifications
EventEmitter In-process events Analytics, Goals, Subscriptions

Architecture Diagram#

text
                            CLIENTS
    ┌─────────────────────────────────────────────────────────┐
    │   Web   │  Mobile  │   VR   │   OBS   │  IoT Devices   │
    └────────────────────────┬────────────────────────────────┘
                             │
                    ┌────────┴────────┐
                    │   EDGE LAYER    │
                    │  (CDN / WAF)    │
                    └────────┬────────┘
                             │
         ┌───────────────────┼───────────────────┐
         ▼                   ▼                   ▼
    ┌─────────┐        ┌─────────┐        ┌─────────────┐
    │   API   │        │  Media  │        │  WebSocket  │
    │ Gateway │        │ Gateway │        │   Gateway   │
    │ (REST)  │        │(WebRTC) │        │ (Socket.io) │
    └────┬────┘        └────┬────┘        └──────┬──────┘
         │                  │                    │
         └──────────────────┼────────────────────┘
                            │
                   ┌────────┴────────┐
                   │  SERVICE MESH   │
                   └────────┬────────┘
                            │
    ┌───────────────────────┼───────────────────────────┐
    │                       │                           │
    ▼                       ▼                           ▼
┌────────────┐      ┌────────────┐              ┌────────────┐
│   User     │      │   Stream   │              │   Chat     │
│  Service   │◄────►│  Service   │◄────────────►│  Service   │
│  (REST)    │gRPC  │  (gRPC)    │    Kafka     │ (Socket.io)│
└─────┬──────┘      └─────┬──────┘              └─────┬──────┘
      │                   │                          │
      │    ┌──────────────┼──────────────┐           │
      │    │              │              │           │
      ▼    ▼              ▼              ▼           ▼
┌────────────┐      ┌────────────┐      ┌────────────────┐
│  Content   │      │ Analytics  │      │  Notification  │
│  Service   │      │  Service   │      │    Service     │
│  (REST)    │      │  (REST)    │      │  (Socket.io)   │
└─────┬──────┘      └─────┬──────┘      └───────┬────────┘
      │                   │                     │
      └───────────────────┼─────────────────────┘
                          │
         ┌────────────────┼────────────────┐
         │                │                │
         ▼                ▼                ▼
    ┌─────────┐     ┌───────────┐    ┌─────────┐
    │PostgreSQL│     │ClickHouse│    │ MongoDB │
    │ (Primary)│     │(Analytics)│    │ (Chat)  │
    └─────────┘     └───────────┘    └─────────┘
         │                │                │
         └────────────────┼────────────────┘
                          │
         ┌────────────────┼────────────────┐
         │                │                │
         ▼                ▼                ▼
    ┌─────────┐     ┌─────────┐      ┌─────────┐
    │  Redis  │     │  Kafka  │      │   S3    │
    │ (Cache) │     │ (Events)│      │ (Media) │
    └─────────┘     └─────────┘      └─────────┘

REST APIs#

Service Endpoints#

User Service (Port 3000)#

Route Method Description
/healthz GET Health check
/register POST User registration
/login POST Authentication
/refresh-token POST Token refresh
/profile GET/PUT User profile
/creator GET/PUT Creator profile
/settings GET/PUT User settings
/follow POST/DELETE Social graph
/fan-club GET/POST Fan clubs

Content Service (Port 7001)#

Route Method Description
/healthz GET Health check
/content-store/* CRUD Content management
/media/upload POST Media upload
/photosets/* CRUD Photo set management
/vod/* CRUD VOD management

Analytics Service (Port 7000)#

Route Method Description
/healthz GET Health check
/api/ingestion/* POST Event ingestion
/api/creator-dashboard/* GET Creator metrics

Recommendation Service (Port 7004)#

Route Method Description
/healthz GET Health check
/api/personalized-home GET Personalized feed
/api/for-you GET For you recommendations
/api/similar-creators GET Similar creators
/api/because-you-watched GET Contextual recs
/api/trending GET Trending content

HTTP Client Patterns#

typescript
// Location: eve/apps/web/lib/api-client.ts

interface ApiClientConfig {
  baseUrl: string;
  authTokenProvider?: () => Promise<string | null>;
}

class ApiClient {
  async request<T>(endpoint: string, options?: RequestInit): Promise<T>;
  async get<T>(endpoint: string, options?: RequestInit): Promise<T>;
  async post<T>(
    endpoint: string,
    body: unknown,
    options?: RequestInit
  ): Promise<T>;
  async put<T>(
    endpoint: string,
    body: unknown,
    options?: RequestInit
  ): Promise<T>;
  async delete<T>(endpoint: string, options?: RequestInit): Promise<T>;
}

WebSocket Communication#

Socket.io Architecture#

The Eve platform uses Socket.io with Redis adapter for horizontal scaling across multiple server instances.

Configuration#

typescript
// Location: eve/apps/chat-service/src/redis.ts

import { createAdapter } from '@socket.io/redis-adapter';
import { createClient } from 'redis';

const pubClient = createClient({ url: process.env.REDIS_URL });
const subClient = pubClient.duplicate();

io.adapter(createAdapter(pubClient, subClient));

Chat Service Events#

Location: eve/apps/chat-service/src/socket/

Connection Management#

Event (Client) Event (Server) Description
connection - User connects with auth
disconnect - User disconnects

Room Management#

Event (Client) Event (Server) Description
room:join room:joined Join chat room
room:leave room:left Leave chat room

Chat Messages#

Event (Client) Event (Server) Description
message:send message:sent Send message
- message:broadcast Broadcast to room

Message Payload:

typescript
interface ChatMessagePayload {
  roomId: string;
  message: string;
  userId: string;
  socketId: string;
  timestamp: Date;
  type: 'text' | 'tip' | 'system';
}

Message Features:

  • Rate limiting
  • Slow mode support
  • Subscriber/follower access control
  • Message persistence (MongoDB)

Typing Indicators#

Event (Client) Event (Server) Description
typing:start typing:indicator Start typing
typing:stop typing:indicator Stop typing

Message Recovery#

Event (Client) Event (Server) Description
recovery:request recovery:messages Recover missed messages

Stream Integration#

Event (Client) Event (Server) Description
stream:join - Join stream chat
stream:leave - Leave stream chat

Emoji Reactions#

Event (Client) Event (Server) Description
emoji:send emoji:broadcast Send emoji reaction

Commands#

Event (Client) Event (Server) Description
command:execute command:response Execute command

Direct Messaging Events#

Location: eve/apps/chat-service/src/dm-handlers.ts

Event (Client) Event (Server) Description
dm:create-conversation dm:conversation-created Create DM conversation
dm:send dm:message-sent Send DM
- dm:message-received DM received (target user)
dm:get-messages dm:messages Get message history
dm:get-conversations dm:conversations Get conversations list
dm:mark-read dm:marked-read Mark as read
dm:get-unread dm:unread Get unread count
dm:delete-message dm:message-deleted Delete message
dm:block dm:conversation-blocked Block user
dm:unblock dm:conversation-unblocked Unblock user
dm:send-mass dm:mass-dm-created Mass DM (async)
dm:get-mass-dm-status dm:mass-dm-status Mass DM status

Cross-Socket Broadcasting:

typescript
// Broadcast to target user across all their connected sockets
io.to(`user:${otherUserId}`).emit('dm:message-received', message);

Notification Service Events#

Location: eve/apps/notification-service/src/notification-handlers.ts

Room Pattern: user:${userId}:notifications

Event (Client) Event (Server) Description
notification:get notification:list Get notifications
notification:get-unread notification:unread-list Get unread
notification:get-stats notification:stats Get stats
notification:mark-read notification:marked-read Mark as read
notification:mark-all-read notification:all-marked-read Mark all read
notification:dismiss notification:dismissed Dismiss notification
notification:delete notification:deleted Delete notification
notification:get-preferences notification:preferences Get preferences
notification:update-preferences notification:preferences-updated Update preferences
notification:subscribe - Subscribe to channel
notification:unsubscribe - Unsubscribe

Server-side Broadcasting:

typescript
// Push notification to user
function pushNotificationToUser(
  io: Server,
  userId: string,
  notification: Notification
): void;

// Push stats to user
function pushStatsToUser(
  io: Server,
  userId: string,
  stats: NotificationStats
): void;

// Broadcast read status
function broadcastNotificationRead(
  io: Server,
  userId: string,
  notificationId: string
): void;

Stream Service Events#

Location: eve/apps/stream-service/src/public-show-integration.ts

Goal Events#

Event Direction Description
goal:completed Server → Client Goal completed
goal:expired Server → Client Goal expired
goal:progress Server → Client Goal progress update

Event Flow:

text
Goal Service (EventEmitter)
    │
    ▼
Public Show Integration
    │
    ▼
Socket.io broadcast to stream:${streamId}
    │
    ▼
Connected viewers receive goal updates

Message Queues (Kafka)#

Kafka Configuration#

Chat Service#

Location: eve/apps/chat-service/src/kafka.ts

typescript
const kafka = new Kafka({
  clientId: 'chat-service',
  brokers: process.env.KAFKA_BROKERS?.split(',') ?? ['localhost:9092'],
});

const producer = kafka.producer();
const consumer = kafka.consumer({ groupId: 'chat-service-group' });

Stream Service#

Location: eve/apps/stream-service/src/kafka.ts

typescript
const kafka = new Kafka({
  clientId: 'stream-service',
  brokers: process.env.KAFKA_BROKERS?.split(',') ?? ['localhost:9092'],
});

const producer = kafka.producer();

Topics & Events#

Topic Producer Consumer Description
chat.messages Chat Service Analytics, Moderation Chat message events
stream.events Stream Service Analytics, Notification Stream lifecycle events
payment.events Payment Service Analytics, Notification Payment/tip events
user.events User Service Analytics User activity events

Event Envelope Pattern#

typescript
interface KafkaEvent<T> {
  id: string;
  type: string;
  timestamp: Date;
  source: string;
  payload: T;
}

Event Bus Patterns#

EventEmitter Integration#

The Eve platform uses Node.js EventEmitter for in-process event distribution.

Analytics Pipeline#

Location: eve/apps/analytics-service/src/index.ts

typescript
const eventBus = new EventEmitter();
const pipeline = createAnalyticsPipeline(clickhouse, eventBus);

// Event subscription
eventBus.on('analytics.events.flushed', (count: number) => {
  logger.info(`Flushed ${count} events to ClickHouse`);
});

Stream Goal System#

Location: eve/apps/stream-service/src/public-show-integration.ts

typescript
// Goal service emits events
goalService.on('goal.completed', async (goal: Goal) => {
  // Broadcast to stream room
  io.to(`stream:${goal.streamId}`).emit('goal:completed', goal);

  // Trigger toy vibration
  await vibrationHandler.onGoalComplete(goal);
});

goalService.on('goal.progress', (goal: Goal, progress: number) => {
  io.to(`stream:${goal.streamId}`).emit('goal:progress', { goal, progress });
});

goalService.on('goal.expired', (goal: Goal) => {
  io.to(`stream:${goal.streamId}`).emit('goal:expired', goal);
});

Subscription Events#

Location: eve/apps/user-service/src/subscription/service.ts

typescript
class SubscriptionService {
  constructor(
    private readonly eventBus: EventEmitter
    // ...other deps
  ) {}

  async createTier(tier: TierData): Promise<Tier> {
    const created = await this.repository.createTier(tier);
    this.eventBus.emit('subscription.tier.created', created);
    return created;
  }
}

gRPC Services#

Stream Service gRPC Server#

Location: eve/apps/stream-service/src/grpc/server.ts

typescript
import { Server, ServerCredentials } from '@grpc/grpc-js';

const host = process.env.STREAM_SERVICE_HOST ?? '0.0.0.0';
const port = process.env.STREAM_SERVICE_PORT ?? 50051;

const server = new Server();
server.bindAsync(
  `${host}:${port}`,
  ServerCredentials.createInsecure(),
  (err, port) => {
    if (err) throw err;
    server.start();
  }
);

Protocol Buffer Definitions#

Location: eve/packages/proto/proto/

Stream Service (stream.proto)#

protobuf
syntax = "proto3";
package eve.stream.v1;

import "google/protobuf/timestamp.proto";

enum StreamStatus {
  STREAM_STATUS_UNSPECIFIED = 0;
  STREAM_STATUS_SCHEDULED = 1;
  STREAM_STATUS_LIVE = 2;
  STREAM_STATUS_COMPLETED = 3;
  STREAM_STATUS_CANCELLED = 4;
}

message Stream {
  string id = 1;
  string creator_id = 2;
  string title = 3;
  string description = 4;
  StreamStatus status = 5;
  google.protobuf.Timestamp scheduled_start = 6;
  google.protobuf.Timestamp started_at = 7;
  google.protobuf.Timestamp ended_at = 8;
  string thumbnail_url = 9;
}

User Service (user.proto)#

protobuf
syntax = "proto3";
package eve.user.v1;

import "google/protobuf/timestamp.proto";

message User {
  string id = 1;
  string email = 2;
  string username = 3;
  string display_name = 4;
  string avatar_url = 5;
  bool verified = 6;
  google.protobuf.Timestamp created_at = 7;
}

Chat Service (chat.proto)#

protobuf
syntax = "proto3";
package eve.chat.v1;

import "google/protobuf/timestamp.proto";

enum MessageType {
  MESSAGE_TYPE_TEXT = 0;
  MESSAGE_TYPE_SYSTEM = 1;
  MESSAGE_TYPE_TIP = 2;
}

message ChatMessage {
  string id = 1;
  string room_id = 2;
  string sender_id = 3;
  string content = 4;
  MessageType type = 5;
  google.protobuf.Timestamp created_at = 6;
}

Events (events.proto)#

protobuf
syntax = "proto3";
package eve.events.v1;

import "google/protobuf/timestamp.proto";

message StreamStarted {
  string stream_id = 1;
  google.protobuf.Timestamp started_at = 2;
}

message PaymentReceived {
  string payment_id = 1;
  string user_id = 2;
  double amount = 3;
  google.protobuf.Timestamp received_at = 4;
}

message ChatMessageCreated {
  string message_id = 1;
  string room_id = 2;
  string sender_id = 3;
  google.protobuf.Timestamp created_at = 4;
}

message EventEnvelope {
  string id = 1;
  string type = 2;
  google.protobuf.Timestamp occurred_at = 3;
  oneof payload {
    StreamStarted stream_started = 10;
    PaymentReceived payment_received = 11;
    ChatMessageCreated chat_message_created = 12;
  }
}

Redis Pub/Sub & Caching#

Socket.io Redis Adapter#

Location: eve/apps/chat-service/src/redis.ts

typescript
import { createAdapter } from '@socket.io/redis-adapter';
import { createClient } from 'redis';

export async function setupRedisAdapter(io: Server): Promise<void> {
  const url = process.env.REDIS_URL ?? 'redis://localhost:6379';

  const pubClient = createClient({ url });
  const subClient = pubClient.duplicate();

  await Promise.all([pubClient.connect(), subClient.connect()]);

  io.adapter(createAdapter(pubClient, subClient));
}

Redis Client Configuration#

Location: eve/apps/stream-service/src/redis.ts

typescript
import Redis from 'ioredis';

const redis = new Redis(process.env.REDIS_URL ?? 'redis://localhost:6379');

export async function connectRedis(): Promise<void> {
  await redis.ping();
  logger.info('Redis connected');
}

Caching Patterns#

Service Use Case Key Pattern
User Service Session cache session:${sessionId}
Stream Service Goal state goal:${goalId}
Chat Service Rate limiting ratelimit:${userId}:${roomId}
Recommendation Feature cache features:${userId}

Service-to-Service Integration#

Direct Service Calls#

Fan Club → Subscription Service#

Location: eve/apps/user-service/src/fanclub-service.ts

typescript
class FanClubService {
  constructor(
    private readonly subscriptionService: SubscriptionService
    // ...other deps
  ) {}

  async getPostAccess(userId: string, creatorId: string): Promise<boolean> {
    const tiers = await this.subscriptionService.getCreatorTiers(creatorId);
    const subscription = await this.subscriptionService.getCreatorSubscriptions(
      creatorId,
      userId
    );
    return this.subscriptionService.checkSubscriptionAccess(
      subscription,
      tiers
    );
  }
}

Chat → Moderation Integration#

Location: eve/apps/chat-service/src/moderation-integration.ts

typescript
class ModerationMiddleware {
  constructor(private readonly moderationService: ModerationService) {}

  async checkMessage(
    userId: string,
    roomId: string,
    message: string
  ): Promise<'allowed' | 'shadow-banned' | 'blocked'> {
    const isBanned = await this.moderationService.isBanned(userId, roomId);
    if (isBanned) return 'blocked';

    // Additional filtering logic...
    return 'allowed';
  }
}

// Socket integration
socket.data.moderationService = moderationService;

Data Flow Diagrams#

Real-Time Chat Flow#

text
┌──────────┐     ┌──────────────┐     ┌─────────────┐
│  Client  │────►│ Socket.io GW │────►│ Chat Service│
│ (Web/App)│     │   (Port 5000)│     │             │
└──────────┘     └──────────────┘     └──────┬──────┘
                                             │
                      ┌──────────────────────┼──────────────────────┐
                      │                      │                      │
                      ▼                      ▼                      ▼
               ┌───────────┐          ┌───────────┐          ┌───────────┐
               │  MongoDB  │          │   Redis   │          │   Kafka   │
               │ (Persist) │          │ (Adapter) │          │ (Fan-out) │
               └───────────┘          └─────┬─────┘          └───────────┘
                                            │
                                            ▼
                                    ┌───────────────┐
                                    │ Other Server  │
                                    │  Instances    │
                                    └───────┬───────┘
                                            │
                                            ▼
                                    ┌───────────────┐
                                    │ Target Client │
                                    └───────────────┘

Streaming Flow#

text
┌──────────┐     ┌──────────────┐     ┌──────────────┐
│ Creator  │────►│  Media GW    │────►│ Stream Svc   │
│ Encoder  │     │  (WebRTC)    │     │   (gRPC)     │
└──────────┘     └──────────────┘     └──────┬───────┘
                                             │
                      ┌──────────────────────┼──────────────────────┐
                      │                      │                      │
                      ▼                      ▼                      ▼
               ┌───────────┐          ┌───────────┐          ┌───────────┐
               │PostgreSQL │          │   Redis   │          │   Kafka   │
               │ (Metadata)│          │  (State)  │          │ (Events)  │
               └───────────┘          └───────────┘          └─────┬─────┘
                                                                   │
                                            ┌──────────────────────┘
                                            │
                                            ▼
                                    ┌───────────────┐
                                    │ Chat Service  │
                                    │  (Socket.io)  │
                                    └───────┬───────┘
                                            │
                                            ▼
                                    ┌───────────────┐
                                    │   Viewers     │
                                    └───────────────┘

Notification Flow#

text
┌──────────────┐     ┌──────────────┐     ┌──────────────────┐
│   Services   │────►│  Notification│────►│    MongoDB       │
│ (Any Event)  │     │   Service    │     │  (Persistence)   │
└──────────────┘     └──────┬───────┘     └──────────────────┘
                            │
                            ▼
                    ┌───────────────┐
                    │   Socket.io   │
                    │ Room Broadcast│
                    └───────┬───────┘
                            │
                            ▼
                 user:${userId}:notifications
                            │
                            ▼
                    ┌───────────────┐
                    │ Connected     │
                    │ Client(s)     │
                    └───────────────┘

Analytics Pipeline#

text
┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│   Services   │────►│  Analytics   │────►│ EventEmitter │
│ (REST POST)  │     │   Ingestion  │     │  Pipeline    │
└──────────────┘     └──────────────┘     └──────┬───────┘
                                                 │
                                                 ▼
                                         ┌───────────────┐
                                         │  ClickHouse   │
                                         │ (Batch Write) │
                                         └───────────────┘

Configuration Reference#

Environment Variables#

bash
# Chat Service
CHAT_SERVICE_HOST=0.0.0.0
CHAT_SERVICE_PORT=5000
MONGODB_URI=mongodb://localhost:27017/eve
REDIS_URL=redis://localhost:6379
KAFKA_BROKERS=localhost:9092

# Stream Service
STREAM_SERVICE_HOST=0.0.0.0
STREAM_SERVICE_PORT=50051  # gRPC
STREAM_SERVICE_HEALTH_PORT=3001  # HTTP health

# User Service
USER_SERVICE_HOST=0.0.0.0
USER_SERVICE_PORT=3000

# Content Service
CONTENT_SERVICE_HOST=0.0.0.0
CONTENT_SERVICE_PORT=7001

# Analytics Service
ANALYTICS_SERVICE_HOST=0.0.0.0
ANALYTICS_SERVICE_PORT=7000

# Notification Service
NOTIFICATION_SERVICE_HOST=0.0.0.0
NOTIFICATION_SERVICE_PORT=7003

# Recommendation Service
RECOMMENDATION_SERVICE_HOST=0.0.0.0
RECOMMENDATION_SERVICE_PORT=7004

# Infrastructure
REDIS_URL=redis://localhost:6379
KAFKA_BROKERS=localhost:9092
MONGODB_URI=mongodb://localhost:27017/eve
DATABASE_URL=postgresql://user:pass@localhost:5432/eve
CLICKHOUSE_URL=http://localhost:8123

Service Port Summary#

Service Protocol Port Health Port
User Service REST 3000 3000
Payment Service REST 4000 4000
Chat Service Socket.io 5000 5000
Analytics Service REST 7000 7000
Content Service REST 7001 7001
Moderation Service REST 7002 7002
Notification Service Socket.io 7003 7003
Recommendation Service REST 7004 7004
Stream Service gRPC 50051 3001

Migration Considerations#

Protocol Mapping to Oshun#

Eve Protocol Oshun Equivalent Notes
Socket.io Socket.io Maintain Redis adapter pattern
Kafka @oshun/event-bus Consider migration path
gRPC gRPC Maintain for high-throughput
REST REST Standardize on Fastify
Redis @oshun/redis Use shared client

Communication Standardization#

  1. Event Envelope: Standardize on Oshun event envelope format
  2. Socket.io Namespaces: Prefix with aphrodite: namespace
  3. Kafka Topics: Prefix with aphrodite. topic namespace
  4. gRPC Package: Rename to aphrodite.* packages

Document History#

Date Version Author Changes
2026-01-16 1.0.0 Claude Initial communication architecture