Sotrix

Production-ready, full-stack real-time social networking and direct messaging platform.

Built with TypeScript, Node.js, Express, React 19, MongoDB Atlas, Redis Cloud, BullMQ, and Socket.IO.

Live Portfolio Showcase & Recruiter Demo:

• Web Client: https://sotrix.yugendhra.me
• 1-Click Demo Account: Click "✦ Explore as Demo User" on the login page (or use demo@sotrix.dev / demo123456).
• Swagger API Documentation: https://sotrix.onrender.com/api-docs

---

Table of Contents

• Overview
• Key Features
• Tech Stack
• Core Resource Modules
• Real-Time Communication
• Background Workers & Queues
• Quickstart & Local Development
  • Option A: Docker Compose
  • Option B: Manual Setup
• Testing
• Security
• Production Cloud Deployment
• Contributing
• Support
• License & Author

---

Overview

Sotrix is a full-stack social web platform engineered for real-time messaging, asynchronous media processing, and high-throughput content feeds.

The application is structured into clearly separated layers: an Express REST and WebSocket gateway, background worker processes managed by BullMQ and Redis, MongoDB Atlas for persistence, and a React 19 single-page application built on Vite and TanStack Query.

Application Showcase (Click to toggle)

Home Feed & Real-Time Composer	Discover & Trending Explorer
Direct Messaging & Typing Indicators	Interactive Profile & Activity Stream

---

Key Features

REST API Surface

• 50+ REST endpoints (49 unique REST operations, 53 registered route handlers) organized across 11 domain modules (Auth, Users, Posts, Feed, Explore, Comments, Likes, Conversations, Notifications, Media Pipeline, Health & Metrics).
• Interactive OpenAPI 3.0 schema inspection via Swagger UI at /api-docs.

Authentication & Sessions

• Dual-token setup: short-lived 15-minute access tokens with 7-day rotating refresh tokens stored in HttpOnly, secure cookies.
• Cryptographic password hashing using bcrypt with 10 salt rounds.
• Email Verification & OTP Delivery: Transactional 6-digit email OTP delivery via Resend, brute-force throttling, resend cooldowns, and secure in-session email modification.
• Strict token invalidation and session cleanup on logout.

Real-Time Messaging & Presence

• One-on-one private chat rooms backed by MongoDB conversation history.
• Real-time peer typing indicators and online/offline status broadcast over Socket.IO.
• Instant in-app push alerts for likes, comments, and new followers.

Media Pipeline

• Asynchronous image processing via BullMQ and Redis queues.
• Image transformation using Sharp: EXIF metadata stripping, WebP compression, and automated thumbnail creation.
• Cloudinary integration for scalable cloud asset storage and delivery.

Feeds & Caching

• Chronological timeline feed of followed creators alongside an explore discovery feed.
• Cursor-based pagination on posts and comments to avoid slow offset queries at scale.
• Redis cache-aside implementation with TTL invalidation for user profiles and frequent queries.
• Compound MongoDB text indexes for handle and post search.

Frontend Architecture

• Built with React 19, Vite, and React Router v7.
• TanStack Query v5 manages server state, optimistic updates, and background cache synchronization.
• Zustand handles global client authentication state.
• Custom responsive dark-mode styling with CSS variables.

Security

• Runtime payload validation using Zod schemas across body, query, and params.
• Tiered rate limiting with express-rate-limit to protect auth routes from brute-force attempts.
• Helmet security headers and configurable CORS multi-origin filtering.

---

Tech Stack

• Backend: Node.js 22 LTS, Express.js, TypeScript, Zod
• Frontend: React 19, Vite, TanStack Query v5, Zustand, React Router v7
• Database & Cache: MongoDB Atlas (Mongoose), Redis Cloud (ioredis)
• Queues & Real-Time: BullMQ, Socket.IO
• Email Delivery: Resend (Transactional OTP & Verification emails)
• Media Processing: Sharp, Multer, Cloudinary
• Testing & Tooling: Jest, Supertest, Oxlint, Swagger
• DevOps: Docker, Docker Compose, NGINX, GitHub Actions CI

---

Core Resource Modules

Module	Base Path	Description
Auth	/api/auth	Registration, login, token refresh, email verification, password change & recovery (/change-password, /forgot-password, /reset-password), profile, and logout
Users	/api/users	Profile retrieval, user search, profile updates, and follow/unfollow toggle
Posts	/api/posts	Post publishing (with multipart upload), user posts, search, updates, deletion
Feed & Explore	/api/feed, /api/explore	Following feed, discovery feed, and creator recommendations
Comments	/api/posts/:id/comments	Threaded comments creation, pagination, updates, and deletion
Likes	/api/posts/:id/like	Post like toggle
Conversations	/api/conversations	Private 1-on-1 chat initialization, inbox listing, and paginated message history
Notifications	/api/notifications	User notification lists, unread counters, and mark-as-read endpoints
Media / Upload	/api/upload, /api/media	Image upload and asynchronous processing pipeline
Observability	/health, /metrics, /api-docs	Container health checks, Prometheus metrics, and Swagger UI

---

Real-Time Communication

Real-time functionality is powered by Socket.IO with handshake JWT verification:

• Direct Chat: Users connect to private conversation rooms to exchange instant messages with persistent database storage.
• Typing Status: Lightweight broadcast signals update peers when someone is typing.
• Online Presence: Socket connection and disconnection lifecycle events update online/offline indicators in real time.
• In-App Notifications: Likes, comments, and follows trigger immediate push alerts without requiring page reloads or polling.

---

Background Workers & Queues

Resource-intensive and non-blocking tasks run through Redis-backed BullMQ queues:

• Media Queue: Handles background image resizing, progressive WebP conversion, thumbnail generation via Sharp, and Cloudinary upload.
• Notification Queue: Handles notification creation and real-time delivery fan-out without adding latency to the main HTTP request.
• Maintenance Queue: Runs scheduled cron jobs via node-cron to prune expired tokens and purge temporary files.

---

Quickstart & Local Development

Prerequisites

• Node.js 20.x or 22.x LTS
• npm or yarn / pnpm
• Docker & Docker Compose (optional, for containerized run)
• Running Redis instance (local or free cloud Redis Cloud via ioredis)
• MongoDB database (local or free MongoDB Atlas)

---

Option A: Docker Compose (Recommended)

Start the entire stack with a single command:

# 1. Clone the repository
git clone https://github.com/y9ndra/sotrix.git
cd sotrix

# 2. Configure server environment variables
cp server/.env.example server/.env
# Edit server/.env with your DATABASE_URL, JWT_SECRET, and Cloudinary keys

# 3. Build and launch all services
docker compose up --build

• Frontend Client: http://localhost:3000
• Backend API: http://localhost:5000
• Swagger Docs: http://localhost:5000/api-docs

---

Option B: Manual Setup

1. Backend Server

cd server
npm install
cp .env.example .env
# Fill in your DATABASE_URL, JWT_SECRET, REDIS_URL, and RESEND_API_KEY

# Optional: Replicate production cloud database to local MongoDB
npm run sync:prod

# Start API server in development mode
npm run dev

2. Background Worker (Optional locally)

In a separate terminal:

cd server
npm run worker

3. Frontend Client

In a third terminal:

cd web
npm install
npm run dev

The web client runs on http://localhost:5173.

---

Testing

# Run all server tests (Jest with in-memory MongoDB)
cd server
npm test

# Run isolated unit tests
npm run test:unit

# Run integration tests
npm run test:integration

# Compile TypeScript
npm run build

# Run frontend Oxlint linter
cd ../web
npm run lint

Every push and pull request to main runs through the GitHub Actions workflow (.github/workflows/ci.yml).

---

Security

• Cross-Site Cookie Protection: In production, cookies enforce SameSite=None, Secure=true, and HttpOnly=true so cross-origin authentication works safely between separated domains.
• Input Sanitization: Request bodies, route parameters, and query arguments are parsed and validated with Zod before reaching business logic.
• Brute-Force Rate Limiting: Global rate limits paired with stricter limits on /api/auth/* routes.
• Container Host Binding: Production containers explicitly bind to 0.0.0.0 for reliable container networking.

---

Production Cloud Deployment

Sotrix is ready for zero-cost cloud deployment across free-tier providers:

• Frontend: Hosted on Vercel with automatic SPA rewrites (vercel.json).
• Backend API: Hosted on Render as a Dockerized web service (server/Dockerfile).
• Database: MongoDB Atlas M0 shared cluster.
• Redis & Queues: Redis Cloud via ioredis.
• Media CDN: Cloudinary free tier.
• Email Service: Resend for transactional OTP and account verification delivery.

---

Contributing

Contributions, issues, and feature requests are welcome! Please review our Contributing Guidelines and Code of Conduct before submitting pull requests.

---

Support

If you find this project helpful or interesting, please consider giving it a star on GitHub!

---

License & Author

Distributed under the MIT License. See LICENSE for details.

Developed by Yugendhra (y9ndra).