uChat — Integration Guide

Overview

The uchat subgraph is the platform's end-to-end encrypted (E2EE) messenger — enabling private, real-time conversations between Visitors, Malet Owners, and fellow shoppers directly within the Mallnline ecosystem. Built as a Rust-native microservice (Axum + Async-GraphQL), it mirrors the auth service architecture and participates in the Apollo Federation gateway as the platform's 16th subgraph.

The server acts as a "dumb relay" — it stores and forwards E2EE ciphertext but is mathematically incapable of reading message content. All cryptographic operations are deferred to the client's WASM layer (Phase 3).

Architecture at a Glance

Core Concepts

Conversations

A Conversation represents a messaging thread. It may be tied to a specific Malet or exist independently for social interactions. Four types exist:

Note: SOCIAL conversations do not require a maletId — they can originate from the Lobby, a shared interest, or a review thread.

Meeting at the Mall — Social Commerce

The SOCIAL conversation type enables the social layer of Mallnline. Just as people meet, chat, and share recommendations at a physical mall, Visitors can connect with each other through uChat. This powers several discovery mechanisms:

All social features are opt-in and privacy-first:

• Visitors must enable "Allow messages from other Visitors" in their privacy settings
• Rate-limited conversation requests prevent spam
• Block/report mechanics are enforced at the platform level
• Support Proxy aliases (already built) protect real identity until explicitly shared

E2EE by Design

The encrypted_body field on every Message contains opaque ciphertext. The server persists it but has zero knowledge of its contents. Only the sender and recipient WASM clients (powered by matrix-rust-sdk compiled to WebAssembly) hold the decryption keys.

Dual-Relay Architecture

Messages are delivered through two parallel relay paths for maximum reliability:

Benchmark: Run npx tsx scripts/bench-uchat-latency.ts to measure E2E latency across all delivery paths. On localhost, WS delivery averages 42ms end-to-end (faster than WhatsApp, Telegram, Slack, Discord, iMessage, and Messenger on their production networks).

When a message is sent via the sendMessage mutation:

1. The E2EE ciphertext is persisted to PostgreSQL
2. Redis relay: The message is PUBLISHed to both uchat:conv:{id} (per-conversation subscribers) and uchat:user:{participantId} for each participant except the sender (global WS subscribers)
3. Matrix relay: The message is forwarded to Conduit via PUT /rooms/{roomId}/send/m.room.encrypted — the returned matrix_event_id is persisted on the message entity

If the Matrix homeserver is unavailable, the Redis relay continues to function independently. Messages forwarded to Matrix are also relayed back to Redis via the AS Transaction handler, ensuring no messages are lost.

Matrix Application Service Bridge

The uchat subgraph acts as a privileged Matrix Application Service using the Ruma crate. With the Conduit homeserver deployed, it provides:

Identity Provisioning

When a Visitor or Malet Owner joins a conversation, the bridge automatically:

1. Provisions a Matrix user: @uchat_{userId}:localhost via POST /_matrix/client/v3/register
2. Stores the Matrix identity: The matrix_user_id field on the Participant entity
3. Handles duplicates gracefully: If the user already exists (M_USER_IN_USE), the existing identity is reused

Room Management

When a conversation is created:

1. Creates an encrypted room: POST /_matrix/client/v3/createRoom with Megolm encryption (m.megolm.v1.aes-sha2) enabled
2. Invites participants: Each provisioned Matrix user is invited to the room
3. Auto-joins participants: The AS masquerades as each user (?user_id=) to accept the invitation
4. Stores the room mapping: The matrix_room_id is persisted on the Conversation entity

Event Forwarding

Encrypted message events are sent to Conduit using AS masquerading — the AS sends the event as the sender's provisioned Matrix user, preserving correct attribution in the Matrix timeline.

Transaction Handler (Inbound Events)

Conduit pushes events to uChat via the Application Service Transaction API:

PUT /_matrix/app/v1/transactions/{txnId}
Authorization: Bearer <hs_token>

The handler:

• Authenticates using the hs_token from the AS registration
• Deduplicates via Redis SET NX with 24h TTL (backed by uchat_matrix_txn_log table)
• Relays m.room.encrypted and m.room.message events to Redis pub/sub for WebSocket delivery
• Maps Matrix room IDs back to conversation IDs for correct channel routing

Health Check

# Check Matrix bridge health
curl http://localhost:3017/matrix/health

Returns:

{
	"status": "healthy",
	"matrix_enabled": true,
	"homeserver": "http://localhost:8448",
	"supported_versions": ["r0.5.0", "r0.6.0", "v1.1", "...", "v1.12"]
}

GraphQL API

Queries

Fetch a Conversation

query GetConversation($id: ID!) {
	conversation(id: $id) {
		id
		maletId
		convType
		matrixRoomId
		createdAt
		updatedAt
		participants {
			id
			userId
			matrixUserId
			role
			joinedAt
		}
	}
}

List My Conversations (Cursor-Paginated)

query MyConversations($first: Int, $after: String) {
	myConversations(first: $first, after: $after) {
		edges {
			cursor
			node {
				id
				maletId
				convType
				updatedAt
			}
		}
		pageInfo {
			hasNextPage
			endCursor
		}
	}
}

Fetch Message History

query ConversationMessages($conversationId: ID!, $first: Int, $after: String) {
	conversationMessages(conversationId: $conversationId, first: $first, after: $after) {
		edges {
			cursor
			node {
				id
				senderId
				encryptedBody
				msgType
				matrixEventId
				createdAt
				editedAt
				editHistory
				fileUrl
				fileName
				fileSize
				fileMime
				reactions {
					id
					emoji
					senderId
				}
			}
		}
		pageInfo {
			hasNextPage
			endCursor
		}
	}
}

Mutations

Create a Conversation

mutation CreateConversation($input: CreateConversationInput!) {
	createConversation(input: $input) {
		id
		maletId
		matrixRoomId
		convType
		participants {
			userId
			matrixUserId
			role
		}
	}
}

When Matrix is enabled, this mutation also:

• Provisions Matrix users for all participants
• Creates an E2EE-enabled Matrix room
• Invites and auto-joins all participants

Input Example (Malet DM):

{
	"input": {
		"maletId": "malet-uuid",
		"convType": "DIRECT",
		"participantIds": ["visitor-user-id", "owner-user-id"]
	}
}

Input Example (Social — Visitor-to-Visitor):

{
	"input": {
		"maletId": null,
		"convType": "SOCIAL",
		"participantIds": ["other-visitor-id"]
	}
}

DM Deduplication: For DIRECT conversations, if a thread between the same two participants already exists, the existing conversation is returned instead of creating a duplicate.

Send a Message (E2EE Ciphertext)

mutation SendMessage($input: SendMessageInput!) {
	sendMessage(input: $input) {
		id
		conversationId
		senderId
		encryptedBody
		msgType
		matrixEventId
		createdAt
		fileUrl
		fileName
		fileSize
		fileMime
		replyToMessageId
	}
}

The encryptedBody is the E2EE ciphertext produced by the client's WASM crypto layer. The server stores it verbatim and forwards it to both Redis and Matrix.

For FILE messages, the encryptedBody contains a Megolm-encrypted JSON envelope with the AES-256-GCM key + IV needed to decrypt the file blob at fileUrl. The file metadata fields (fileUrl, fileName, fileSize, fileMime) are stored in plaintext for display in file cards — they do not contain sensitive content. The encrypted file blob is stored separately in S3 via the media service. See the Crypto service for the encryption protocol.

Reply to a Message

To send a reply, include the optional replyToMessageId field in the input:

{
	"input": {
		"conversationId": "conv-uuid",
		"encryptedBody": "<ciphertext>",
		"replyToMessageId": "parent-message-uuid"
	}
}

The parent message is resolved via the repliedToMessage field on the returned Message object. If the parent message has been deleted, repliedToMessage.encryptedBody returns "This message was deleted" and msgType is masked to SYSTEM. If the parent message ID is invalid or the referenced row no longer exists (via ON DELETE SET NULL), repliedToMessage resolves to null.

The clientEventId field provides idempotency — if the same clientEventId is sent twice, the server returns the existing message instead of creating a duplicate.

The matrixEventId is populated after the event is successfully forwarded to the Conduit homeserver.

Issue WebSocket Token

mutation IssueWsToken {
	issueWsToken {
		token
		expiresIn
	}
}

Returns a short-lived JWT (5 minutes) used to authenticate WebSocket connections.

Mark a Conversation as Read

mutation MarkAsRead($conversationId: ID!, $messageId: ID!) {
	markAsRead(conversationId: $conversationId, messageId: $messageId)
}

Updates last_read_message_id and last_read_at on the caller's participant record. Broadcasts a read_receipt event via Redis pub/sub to all other participants' WebSocket channels.

Delete a Message

mutation DeleteMessage($messageId: ID!, $conversationId: ID!) {
	deleteMessage(messageId: $messageId, conversationId: $conversationId)
}

Soft-deletes a message (sender-only). Sets deleted_at and deleted_by on the message row. Broadcasts a message_deleted event via Redis pub/sub. Subsequent queries return "[deleted]" as the encrypted_body and msg_type: "System".

Edit a Message

mutation EditMessage($messageId: ID!, $conversationId: ID!, $newBody: String!) {
	editMessage(messageId: $messageId, conversationId: $conversationId, newBody: $newBody) {
		id
		encryptedBody
		editedAt
		editHistory
	}
}

Updates the encrypted_body to newBody, sets edited_at to NOW(), and appends the old body to the edit_history JSONB array. Sender-only. Broadcasts a message_edited event via Redis pub/sub.

Add a Reaction

mutation AddReaction($messageId: ID!, $emoji: String!) {
	addReaction(messageId: $messageId, emoji: $emoji) {
		id
		messageId
		senderId
		emoji
	}
}

Adds or replaces the caller's reaction on a message. One reaction per user per message — if the user already has a different emoji on this message, it is replaced atomically via ON CONFLICT (message_id, sender_id) DO UPDATE. If the same emoji is sent again, the reaction is toggled off (deleted). Broadcasts reaction_added or reaction_removed events to both uchat:conv:{id} and uchat:user:{pid} channels for real-time delivery to per-conversation and global WS clients.

Remove a Reaction

mutation RemoveReaction($messageId: ID!, $emoji: String!) {
	removeReaction(messageId: $messageId, emoji: $emoji)
}

Deletes the caller's reaction. Broadcasts a reaction_removed event to both WS channels.

WebSocket Real-Time Relay

The WebSocket endpoint runs on port 3018 and provides real-time message delivery via Redis pub/sub.

Connection Modes

Two subscription modes are supported:

Note: Global mode is recommended. The sendMessage mutation fans out to each participant's uchat:user:{id} channel, so a single WS connection receives messages from all conversations. The sender is excluded from the fan-out query to prevent echo.

Connection Flow

1. Obtain a token: Call the issueWsToken mutation to get a 5-minute JWT.
2. Connect: Open a WebSocket to ws://localhost:3018/ws?token=<jwt> (global mode) or ws://localhost:3018/ws?token=<jwt>&conversation_id=<uuid> (per-conversation mode).
3. Receive: Incoming messages from other participants are pushed as JSON text frames.
4. Heartbeat: Send "ping" text frames to refresh your presence TTL (30 seconds).

Sender Echo Prevention

• Per-conversation mode: The WS relay filters messages where sender_id matches the connected user, preventing echo.
• Global mode: No filtering is needed — the mutation's fan-out query (WHERE user_id != sender) already excludes the sender from the publish list.

Message Frame Format

Messages received over WebSocket are JSON payloads. Messages may originate from either Redis (direct relay) or Matrix (AS transaction relay):

{
	"type": "new_message",
	"id": "message-uuid",
	"conversation_id": "conv-uuid",
	"sender_id": "user-id",
	"encrypted_body": "<E2EE ciphertext>",
	"msg_type": "Text",
	"created_at": "2026-04-06T12:00:00Z",
	"file_url": null,
	"file_name": null,
	"file_size": null,
	"file_mime": null,
	"reply_to_message_id": null
}

Messages relayed from Matrix include a "source": "matrix" field and the Matrix event_id.

Event Types

In addition to new message payloads, the WebSocket relay delivers several event types via the type field:

Presence Tracking

User presence is stored in Redis with a 30-second TTL:

• uchat:presence:{userId} → "online"
• Refreshed on each "ping" heartbeat
• Removed on WebSocket disconnect

Database Schema

The uchat subgraph uses a dedicated PostgreSQL database (ngwenya_uchat) for full microservice isolation.

Migrations

Conduit Matrix Homeserver

The platform deploys Conduit — a lightweight, memory-safe Matrix homeserver written in Rust — as the sovereign relay backend.

Configuration

Application Service Registration

The uchat AS registration (uchat-appservice.yaml) is auto-discovered by Conduit on startup:

Environment Variables

Note: Setting MATRIX_HOMESERVER_URL to an empty string falls back to standalone mode (Redis-only relay). All Matrix bridge calls gracefully no-op.

File Reference

Phased Roadmap

Testing

Unit Tests

cd apps/uchat && cargo test

Runs 14 unit tests + 23 integration tests covering:

• Matrix bridge standalone fallback (provision, create, invite, join, send, health)
• Server name extraction (HTTP + HTTPS)
• AS transaction body deserialization
• Platform user ID extraction from Matrix sender IDs
• Conversation lifecycle (create, DM dedup, list)
• Message delivery (send, pagination, WebSocket relay)
• Read receipts (markAsRead, last_read tracking)
• Message deletion (soft-delete, content substitution, sender-only guard)

Manual Verification

# Health check
curl http://localhost:3017/health

# Matrix bridge health
curl http://localhost:3017/matrix/health

# Federation introspection
curl -s -X POST http://localhost:3017/graphql \
  -H 'Content-Type: application/json' \
  -d '{"query":"{_service{sdl}}"}'

# Conduit versions (direct)
curl http://localhost:8448/_matrix/client/versions

# WebSocket test (after obtaining a token via issueWsToken)
websocat ws://localhost:3018/ws?token=<jwt>&conversation_id=<uuid>

Related

• Auth & Identity — Identity management service that provides x-user-id context for uChat GraphQL queries

• Crypto — Encryption Microservice — AES-256-GCM file encryption for E2EE file attachments

• Corporate Identity (SAML & SCIM) — Enterprise SSO and provisioning that creates the Organization members who participate in uChat conversations

• Community Features — Community discussions and issues that can spawn uChat conversations

• Media Infrastructure — Presigned S3 upload URLs for encrypted file blobs

• Privacy & Security APIs — Cookie consent, data export, and session management

• Link Previews — Server-side OG scraping architecture, caching, and rate limiting for rich URL previews

• User Guide: uChat Messenger — Visitor-facing guide to encrypted messaging

• uChat Online Presence — Redis TTL keys and heartbeat logic.

• uChat Voice Messages Architecture — Technical implementation of E2EE voice messaging.

• uChat Message Search (E2EE) — Hybrid privacy-preserving search architecture.