Relay

Overview

Relay is a full-stack real-time messaging application built for distributed engineering teams. It delivers messages globally in under 200ms via Socket.io WebSockets, with a security-first auth system, presence awareness, and typing indicators, all wrapped in a dark-mode retro-futuristic UI.

The application is structured as a Turborepo monorepo with a Next.js frontend, Express backend, and a shared TypeScript package for socket event constants and common types.

<200ms

Message delivery

1 week

Build timeline

Monorepo workspaces

MongoDB collections

Key Features

Dual-token JWT auth

3-day access tokens plus rotating httpOnly refresh cookies (7 days). Email + password signup with nodemailer-based email verification, and Google OAuth 2.0 with CSRF protection via a state cookie.

Token family revocation

Refresh tokens are hashed with SHA-256 before storage, so the raw value never persists. Replay detection invalidates the entire login chain, not just the reused token.

Real-time messaging

Instant delivery via Socket.io with a JWT-authenticated handshake. Delivery status runs sent, delivered, read with a double-tick UI, plus message edit and soft delete.

Paginated history

Cursor-based message history loading 30 messages per page, deduplicated across the socket and HTTP layers.

Presence & typing

Online, Away, and Offline status driven by the socket connect/disconnect lifecycle. Typing indicators debounce at 3 seconds and are broadcast only, never written to the database.

Conversation state

Per-participant unread counts, mute, and archive tracked in participantMeta[] on each conversation.

Retro-futuristic UI

Dark mode only: amber accent (#F5A623), CRT scanline overlays, an animated starfield, and ambient glow blobs.

No UI library

Every component is custom-built with inline styles, no external component library anywhere in the client.

Architecture

Relay is organized as a Turborepo monorepo with three workspaces:

@relay/client: Next.js 16 (App Router), React 19, Tailwind CSS 4
@relay/server: Express 5, Socket.io, Mongoose 9, Passport.js
@relay/shared: Common TypeScript types and SOCKET_EVENTS constants

Real-Time Event Flow

client connect   → JWT auth middleware → isOnline = true, socketId saved
message:send     → save to MongoDB → emit message:new to conversation room
typing:start/stop → broadcast to room (not persisted)
disconnect       → isOnline = false, lastSeen = now, broadcast presence:update
message:read     → update readBy[], broadcast message:status to sender

Auth Token Flow

1
Sign in
Email + password or Google OAuth issues a 3-day access token and a rotating httpOnly refresh cookie (7 days).
2
Client-side session
The access token lives in localStorage or sessionStorage. On app mount, AuthProvider restores it to axios headers and calls /session to validate.
3
Rotation and revocation
Each refresh rotates the token; only the SHA-256 hash is stored. A replayed refresh token revokes the whole token family.

OAuth token via URL fragment

Google OAuth redirects to /homepage#accessToken=.... The fragment approach avoids CORS issues with cross-origin cookie delivery to a SPA.

Socket state without persistence

Presence and typing are pure socket lifecycle state: broadcast to the conversation room with zero database writes.

Data Model

Four MongoDB collections: users, tokens, conversations, messages.

tokens stores only the SHA-256 hash of refresh tokens: the raw value never touches the DB
conversations.participantMeta[] tracks unread count, muted, and archived state per user
messages post-save hook updates conversation.lastMessage, lastMessageAt, and increments unread counts for other participants

Outcome

Relay demonstrates a production-grade real-time communication system, combining secure dual-token auth, socket-driven state, and a fully connected data layer across a Turborepo monorepo. Every feature from auth to typing indicators is wired to a real backend with no mock data remaining.