🌸 Iris Messenger

A full-stack, real-time messaging platform built with a Node.js microservices backend and a React frontend.

Inspired by Telegram — supports direct messages, groups, channels, file sharing, and role-based administration.

📋 Table of Contents

Overview
Architecture
Tech Stack
Features
Project Structure
Getting Started
API Documentation
Authentication Flow
Roles & Permissions
Contributing

🔍 Overview

Iris Messenger is a microservices-based real-time messaging application that mirrors the core experience of Telegram. It is built from scratch with a focus on clean architecture, security, and scalability.

Real-time communication is powered by Socket.io, inter-service communication uses RabbitMQ for token validation and user data exchange, and file uploads are handled internally via gRPC.

🏗 Architecture

┌─────────────────────────────────────────────────────────────┐
│                        React Client                         │
│              Vite · TypeScript · TailwindCSS                │
│              React Query · Socket.io-client                  │
└────────┬──────────────┬──────────────┬──────────────────────┘
         │ HTTPS        │ HTTPS        │ HTTPS / WSS
         ▼              ▼              ▼
┌────────────┐  ┌────────────┐  ┌────────────┐
│  IAM :3001 │  │ Core :3003 │  │ Media:3002 │
│  (Auth &   │  │(Messaging, │  │  (Files,   │
│   Users)   │  │ Groups,    │  │  GridFS)   │
│            │  │ Channels,  │  │            │
│ PostgreSQL │  │  Socket.io)│  │  MongoDB   │
│ + Sequelize│  │  MongoDB   │  │  GridFS    │
└────────────┘  └────────────┘  └────────────┘
      │                │                │
      └────────────────┴────────────────┘
                       │
              ┌────────────────┐
              │   RabbitMQ     │
              │ Token Validation│
              │  User Data      │
              └────────────────┘
                       │
              ┌────────────────┐
              │  gRPC :8087    │
              │  File Uploads  │
              │ (IAM → Media)  │
              │ (Core → Media) │
              └────────────────┘

Service Responsibilities

Service	Port	Database	Responsibility
IAM	3001	PostgreSQL	Authentication (OTP), user/admin/superAdmin management
Core	3003	MongoDB	Messaging, groups, channels, directs, contacts, Socket.io
Media	3002	MongoDB (GridFS)	File upload/download via REST and gRPC
Gateway	3000	—	Reverse proxy (WIP)

🛠 Tech Stack

Backend

Layer	Technology
Runtime	Node.js 18+ (ES Modules)
Framework	Express.js
Auth DB	PostgreSQL + Sequelize ORM
Messaging DB	MongoDB + Mongoose
File Storage	MongoDB GridFS
Message Broker	RabbitMQ (amqplib)
File Transfer (internal)	gRPC
Real-time	Socket.io
Auth	JWT (httpOnly cookies)
Password Hashing	bcrypt
Validation	Joi
Logging	Winston + Morgan

Frontend

Layer	Technology
Framework	React 18 + Vite
Language	TypeScript 5.6
Styling	TailwindCSS 3 + DaisyUI 4 (32 themes)
State / Data	React Query (TanStack Query v5)
Forms	React Hook Form
Routing	React Router DOM v7
Real-time	Socket.io-client

✨ Features

Messaging

💬 Direct Messages — one-to-one private conversations
👥 Groups — multi-user chats with member roles (owner, admin, member)
📢 Channels — broadcast-only channels (only owner can send)
📎 File Attachments — image upload via gRPC to Media service
⚡ Real-time — Socket.io for instant message delivery

User

🔐 OTP Authentication — email-based verification, no passwords for users
👤 Profile Management — name, bio, username, phone, profile picture
🔍 User Search — search by email
👥 Contacts — add/remove contacts
🚫 Block/Unblock — block other users from messaging you
🎨 32 Themes — full DaisyUI theme support, persisted to localStorage

Administration

🛡 Admin Panel — manage users (view, ban/unban), groups, channels
👑 SuperAdmin Panel — create/manage admins
🔑 Role-based Access — user, admin, superAdmin roles enforced on both frontend and backend

📁 Project Structure

Iris_Messenger/
│
├── Services/
│   ├── IAM/                        # Identity & Access Management
│   │   ├── src/
│   │   │   ├── application/        # Business logic (controllers)
│   │   │   ├── domain/             # Sequelize models
│   │   │   ├── infrastructure/     # DB queries
│   │   │   ├── presentation/       # Express routes
│   │   │   ├── contracts/          # Joi validation schemas
│   │   │   ├── config/
│   │   │   │   └── secret/.env     # ← environment variables
│   │   │   └── DB/                 # PostgreSQL connection
│   │   ├── index.js                # Entry point
│   │   └── .env.example
│   │
│   ├── Core/                       # Messaging Service
│   │   ├── src/
│   │   │   ├── Application/        # Business logic
│   │   │   ├── Domain/             # Mongoose models
│   │   │   ├── Infrastructure/     # DB queries
│   │   │   ├── Presentation/       # Routes + Socket.io
│   │   │   ├── contracts/          # Joi validation
│   │   │   ├── config/
│   │   │   │   └── secret/.env     # ← environment variables
│   │   │   └── DB/                 # MongoDB connection
│   │   └── .env.example
│   │
│   ├── Media/                      # File Storage Service
│   │   ├── Application/            # upload/download logic + gRPC server
│   │   ├── Presentation/           # REST routes
│   │   ├── DB/                     # MongoDB + GridFS
│   │   ├── config/
│   │   │   └── secret/.env         # ← environment variables
│   │   ├── index.js                # Entry point
│   │   └── .env.example
│   │
│   ├── gateWay/                    # Reverse Proxy (WIP)
│   ├── cert.pem                    # SSL certificate (self-signed, dev only)
│   └── key.pem                     # SSL private key  (NEVER commit to prod)
│
└── Client/                         # React Frontend
    ├── src/
    │   ├── admin/                  # Admin & SuperAdmin panels + login
    │   ├── user/
    │   │   ├── login/              # OTP login flow (3 stages)
    │   │   └── mainPage/           # Main chat UI
    │   │       ├── chat/           # DirectPage, GroupPage, ChannelPage
    │   │       ├── chatList/       # Sidebar chat list
    │   │       └── menu/           # Settings, Contacts, Add Group/Channel
    │   ├── hooks/                  # React Query data fetching hooks
    │   ├── layouts/                # Auth guards (UserHomeLayout, etc.)
    │   ├── contexts/               # UserContext
    │   ├── interfaces/             # TypeScript interfaces
    │   └── consts/                 # API base URLs
    ├── tailwind.config.js
    └── package.json

🚀 Getting Started

Prerequisites

Make sure the following are installed and running:

Requirement	Install Guide
Node.js v18+	nodejs.org
PostgreSQL 14+	postgresql.org
MongoDB 6+	mongodb.com
RabbitMQ 3.12+	rabbitmq.com

Installation

Clone the repository and install dependencies for all services:

git clone https://github.com/your-username/Iris_Messenger.git
cd Iris_Messenger

# IAM Service
cd Services/IAM && npm install

# Core Service
cd ../Core && npm install

# Media Service
cd ../Media && npm install

# Frontend
cd ../../Client && npm install

Configuration

Each service needs a .env file. Starter files have been created at:

Service	Path
IAM	`Services/IAM/src/config/secret/.env`
Core	`Services/Core/src/config/secret/.env`
Media	`Services/Media/config/secret/.env`

Minimum required changes:

# 1. Set your PostgreSQL password in IAM .env
DB_PASSWORD=your_postgres_password

# 2. Set a strong JWT secret — MUST be identical in all 3 services
JWTSecret=a_very_long_random_string_at_least_32_characters

# 3. Set your frontend origin in all 3 services
ALLOWED_ORIGINS=http://localhost:5173

📝 See each service's .env.example for all available options.

Running the App

1. Start Infrastructure

# PostgreSQL — usually runs as a system service
# Verify it's running:
pg_isready

# MongoDB
mongod --dbpath "C:/data/db"       # Windows
# mongod --dbpath /data/db         # Linux/Mac

# RabbitMQ
rabbitmq-server                    # or start via Windows Services
# Management UI: http://localhost:15672  (user: guest, pass: guest)

2. Start Backend Services

Open 3 separate terminals:

# Terminal 1 — IAM (port 3001)
cd Services/IAM
npm start

# Terminal 2 — Core (port 3003)
cd Services/Core
npm start

# Terminal 3 — Media (port 3002)
cd Services/Media
npm start

Expected output for each service:

IAM service listening on port 3001
Database connected successfully.
RabbitMQ token validation listener ready.
RabbitMQ user data listener ready.

3. Start Frontend

# Terminal 4
cd Client
npm run dev

Open http://localhost:5173 in your browser.

⚠️ Self-Signed Certificate Setup (Important!)

The backend services run on HTTPS with self-signed certificates. Browsers will block API requests until you manually accept each certificate.

Visit each URL once and click "Advanced → Accept Risk":

Service	URL
IAM	https://localhost:3001
Core	https://localhost:3003
Media	https://localhost:3002

After accepting all three, the frontend will work correctly.

First-Time Database Setup

Create a SuperAdmin

The SuperAdmin account must be seeded directly. Connect to PostgreSQL and insert a bcrypt-hashed password:

-- Connect to your database
\c Iris

-- Generate a bcrypt hash for your password first (e.g., using Node.js):
-- node -e "require('bcrypt').hash('yourpassword', 10).then(console.log)"

INSERT INTO "SuperAdmins" (email, password, "createdAt", "updatedAt")
VALUES (
  'superadmin@iris.com',
  '$2b$10$yourGeneratedHashHere',
  NOW(),
  NOW()
);

Create an Admin

Log in at http://localhost:5173/superAdmin/logIn
Navigate to the Add Admin tab
Fill in the admin details

Register as a User

Open http://localhost:5173
Enter your email → receive a 6-digit OTP code
Enter the code → complete your profile

📖 API Documentation

After starting the Core service, the combined Swagger UI is available at:

https://localhost:3003/swagger

This includes documentation for both IAM and Core service endpoints.

🔐 Authentication Flow

User enters email
       │
       ▼
POST /users/createOTP  ──► Email sent with 6-digit code
       │
       ▼
POST /users/checkOTP
       │
       ├─ Existing user ──► JWT issued → httpOnly cookie → Navigate to app
       │
       └─ New user ──► "incompleteUser" JWT → Sign-up form
                              │
                              ▼
                       POST /users/signUp
                              │
                              ▼
                       JWT issued → httpOnly cookie → Navigate to app

Tokens are stored in httpOnly cookies (not localStorage) — protected against XSS
Tokens expire after 30 days
Admin/SuperAdmin use email + password (bcrypt-hashed)

👥 Roles & Permissions

Action	User	Admin	SuperAdmin
Send messages	✅	✅	✅
Create groups/channels	✅	✅	✅
View all users	❌	✅	✅
Ban/unban users	❌	✅	✅
View all groups/channels	❌	✅	✅
Create admins	❌	❌	✅
Manage admins	❌	❌	✅

🤝 Contributing

Fork the repository
Create a feature branch: git checkout -b feature/your-feature
Commit your changes: git commit -m "feat: add your feature"
Push to the branch: git push origin feature/your-feature
Open a Pull Request

Please make sure:

.env files are never committed
*.pem files are never committed (already in .gitignore)
JWTSecret is always set via environment variable, never hardcoded

Made with ❤️ using Node.js, React, and MongoDB

Name		Name	Last commit message	Last commit date
Latest commit History 133 Commits
.vscode		.vscode
Client		Client
Services		Services
.gitignore		.gitignore
README.md		README.md

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

🌸 Iris Messenger

📋 Table of Contents

🔍 Overview

🏗 Architecture

Service Responsibilities

🛠 Tech Stack

Backend

Frontend

✨ Features

Messaging

User

Administration

📁 Project Structure

🚀 Getting Started

Prerequisites

Installation

Configuration

Running the App

1. Start Infrastructure

2. Start Backend Services

3. Start Frontend

⚠️ Self-Signed Certificate Setup (Important!)

First-Time Database Setup

Create a SuperAdmin

Create an Admin

Register as a User

📖 API Documentation

🔐 Authentication Flow

👥 Roles & Permissions

🤝 Contributing

About

Releases

Packages

Used by

Contributors

Languages

Folders and files

Latest commit

History

Repository files navigation

🌸 Iris Messenger

📋 Table of Contents

🔍 Overview

🏗 Architecture

Service Responsibilities

🛠 Tech Stack

Backend

Frontend

✨ Features

Messaging

User

Administration

📁 Project Structure

🚀 Getting Started

Prerequisites

Installation

Configuration

Running the App

1. Start Infrastructure

2. Start Backend Services

3. Start Frontend

⚠️ Self-Signed Certificate Setup (Important!)

First-Time Database Setup

Create a SuperAdmin

Create an Admin

Register as a User

📖 API Documentation

🔐 Authentication Flow

👥 Roles & Permissions

🤝 Contributing

About

Resources

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages