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.

Key Features

Auth & Security

• Email + password signup with nodemailer-based email verification
• Google OAuth 2.0 with CSRF protection via state cookie
• JWT dual-token system — 3 days access tokens + rotating httpOnly refresh cookies (7 days)
• Token family revocation — replay detection invalidates the entire login chain
• SHA-256 hashing of refresh tokens before storage — raw tokens never persisted

Real-Time Messaging

• Instant message delivery via Socket.io with JWT-authenticated handshake
• Message delivery status: sent → delivered → read (double-tick UI)
• Paginated message history (cursor-based, 30 messages per load)
• Edit and soft-delete messages

Presence & Typing

• Online / Away / Offline status driven by socket connect/disconnect lifecycle
• Typing indicators with 3-second debounce — no DB writes, broadcast only
• Unread count per participant, mute and archive per conversation

Design

• Dark mode only — retro-futuristic arcade aesthetic
• Amber accent (#F5A623), CRT scanline overlays, animated starfield, ambient glow blobs
• No external UI library — all components custom-built with inline styles

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

Access token lives in localStorage or sessionStorage. On app mount, AuthProvider restores the token to axios headers and calls /session to validate.

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

Data Model

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

• tokens stores only the SHA-256 hash of refresh tokens — 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.