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
- Overview
- Key Features
- Tech Stack
- Core Resource Modules
- Real-Time Communication
- Background Workers & Queues
- Quickstart & Local Development
- Testing
- Security
- Production Cloud Deployment
- Support
- License & Author
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
|
- 45+ REST endpoints organized across 10 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.
- 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.
- Strict token invalidation and session cleanup on logout.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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
- Media Processing: Sharp, Multer, Cloudinary
- Testing & Tooling: Jest, Supertest, Oxlint, Swagger
- DevOps: Docker, Docker Compose, NGINX, GitHub Actions CI
| Module | Base Path | Description |
|---|---|---|
| Auth | /api/auth |
Registration, login, refresh token rotation, session 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 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.
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-cronto prune expired tokens and purge temporary files.
- 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)
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
cd server
npm install
cp .env.example .env
# Fill in your DATABASE_URL, JWT_SECRET, and REDIS_URL
# Start API server in development mode
npm run devIn a separate terminal:
cd server
npm run workerIn a third terminal:
cd web
npm install
npm run devThe web client runs on http://localhost:5173.
# 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 lintEvery push and pull request to main runs through the GitHub Actions workflow (.github/workflows/ci.yml).
- Cross-Site Cookie Protection: In production, cookies enforce
SameSite=None,Secure=true, andHttpOnly=trueso 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.0for reliable container networking.
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.
If you find this project helpful or interesting, please consider giving it a star on GitHub!
Distributed under the MIT License. See LICENSE for details.
Developed by Yugendhra (y9ndra).