Missebo-api - Real-Time Messaging Microservices Backend

A real-time messaging backend built with microservices architecture, similar to Telegram or WhatsApp. This project demonstrates a scalable, modular system using Node.js, TypeScript, Docker, and various modern technologies.

Note: This is a portfolio/educational project designed to showcase microservices architecture, modern backend development practices, and system design skills. It is not intended for production use without additional security hardening and optimizations.

🏗️ Architecture

The system consists of 5 microservices:

1. Auth Service (Port 4001) - User authentication and JWT token management
2. User Service (Port 4002) - User profiles and presence management
3. Chat Service (Port 4003) - Real-time messaging via WebSocket
4. Notification Service (Port 4004) - Push notifications and alerts
5. API Gateway (Port 8080) - Central entry point for all requests

🛠️ Tech Stack

• Language: TypeScript
• Framework: Express.js
• Real-time: Socket.io
• Message Queue: RabbitMQ
• Databases:
  • PostgreSQL (Auth & User services) with Prisma ORM
  • MongoDB (Chat & Notification services)
  • Redis (Caching & Presence)
• Validation: Zod
• Logging: Winston
• Containerization: Docker & Docker Compose

🚀 Quick Start

Prerequisites

• Docker & Docker Compose installed
• Bun 1.0+ (for local development)

Running with Docker Compose

1. Clone the repository:

git clone https://github.com/BronzonTech-Cloud/missebo-api.git
cd missebo-api

2. Set up environment variables (REQUIRED):

# Copy the root .env.example to .env (REQUIRED for Docker Compose)
cp .env.example .env

# IMPORTANT: The .env file is REQUIRED - docker-compose.yml will not work without it
# Update the .env file with your own secrets
# For production use, change JWT_SECRET and database passwords!
# Generate a strong JWT secret: openssl rand -base64 32

# For local development, also set up service-specific .env files:
cp auth-service/.env.example auth-service/.env
cp user-service/.env.example user-service/.env
cp chat-service/.env.example chat-service/.env
cp notification-service/.env.example notification-service/.env
cp gateway/.env.example gateway/.env

Important Notes:

• The root .env file is REQUIRED - Docker Compose will fail without it
• The .env file is git-ignored and should never be committed
• All secrets must be provided via the .env file (no hardcoded defaults)
• For production, use strong, randomly generated secrets and consider using Docker secrets or a secrets management service

3. Start all services:

docker compose up -d

4. Initialize the database (run migrations):

docker compose exec auth-service bunx prisma migrate deploy
docker compose exec user-service bunx prisma migrate deploy

4. Access services:

• API Gateway: http://localhost:8080
• RabbitMQ Management: http://localhost:15672 (admin/admin)
• Auth Service: http://localhost:4001
• User Service: http://localhost:4002
• Chat Service: http://localhost:4003
• Notification Service: http://localhost:4004
• PostgreSQL: localhost:5433 (host port, container uses 5432)

Running Locally (Development)

Optional bootstrap (recommended for first run):

./bootstrap.sh

This copies .env.example files into each service and installs all dependencies. If you prefer to do things manually, follow the steps below.

1. Install dependencies for each service:

./install-deps.sh

If you prefer to run them manually:

cd auth-service && bun install
cd ../user-service && bun install
cd ../chat-service && bun install
cd ../shared/auth && bun install
cd ../notification-service && bun install
cd ../gateway && bun install

2. Start infrastructure services:

docker compose up -d postgres mongodb redis rabbitmq

3. Set up environment variables (skip if you ran ./bootstrap.sh):

# Copy .env.example to .env in each service directory
cp auth-service/.env.example auth-service/.env
cp user-service/.env.example user-service/.env
cp chat-service/.env.example chat-service/.env
cp notification-service/.env.example notification-service/.env
cp gateway/.env.example gateway/.env

# Update DATABASE_URL and other variables in each .env file if needed
# For local development, you may need to adjust:
# - DATABASE_URL (use localhost instead of service names)
# - REDIS_URL (use localhost instead of service names)
# - RABBITMQ_URL (use localhost instead of service names)
# - MONGODB_URL (use localhost instead of service names)

4. Run database migrations:

cd auth-service && bunx prisma migrate dev
cd ../user-service && bunx prisma migrate dev

5. Start each service in separate terminals:

# Terminal 1
cd auth-service && bun run dev

# Terminal 2
cd user-service && bun run dev

# Terminal 3
cd chat-service && bun run dev

# Terminal 4
cd notification-service && bun run dev

# Terminal 5
cd gateway && bun run dev

📚 API Documentation

Authentication

Register

POST /auth/register
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "securepassword123",
  "username": "johndoe",
  "displayName": "John Doe"
}

Login

POST /auth/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "securepassword123"
}

Get Current User

GET /auth/me
Authorization: Bearer <token>

Users

Get User Profile

GET /users/:id
Authorization: Bearer <token>

Update Status

PATCH /users/status
Authorization: Bearer <token>
Content-Type: application/json

{
  "status": "online" | "offline" | "away"
}

Chat

Get Messages

GET /messages/:chatId
Authorization: Bearer <token>

WebSocket Connection

Connect to: ws://localhost:4003 (or via gateway at ws://localhost:8080/chat)

Events:

• message - Send a message
• typing - Broadcast typing indicator
• read_receipt - Mark messages as read

Notifications

Get Notifications

GET /notifications
Authorization: Bearer <token>

🧪 Testing

Running Tests

Run tests for all services:

./test.sh

Or run tests for a single service:

cd <service-name> && bun test

Test Coverage

Current test coverage: 87.33% lines, 83.60% functions

Each service includes unit tests for:

• Auth Service: Registration, login, JWT token generation, user validation (100% coverage)
• User Service: Profile creation, status updates, presence management (100% coverage)
• Chat Service: Message sending, chat creation, read receipts (97.25% coverage)
• Notification Service: Notification creation, event handling (95.59% coverage)
• Gateway: Basic routing and proxy functionality
• Shared Auth: Authentication middleware and error handling (100% coverage)

Run tests with coverage:

bun test --coverage

Writing Tests

Tests are written using Bun's built-in test runner (Jest-compatible API). Example:

import { describe, it, expect } from 'bun:test';

describe('MyService', () => {
  it('should do something', () => {
    expect(true).toBe(true);
  });
});

Test Structure

Tests are located alongside the source code:

service-name/
  src/
    services/
      my.service.ts
      my.service.test.ts

🔧 Code Quality

Linting

Check and auto-fix linting issues across all services:

./lint-check.sh

Or for a single service:

cd <service-name>
bun run lint          # Check for linting errors
bun run lint:fix      # Auto-fix linting errors

Formatting

Format code across all services:

./format.sh

Or for a single service:

cd <service-name>
bun run format        # Format code
bun run format:check  # Check formatting without modifying files

📦 Project Structure

missebo-api/
├── docker-compose.yml
├── shared/
│   └── auth/                    # Shared authentication package
│       ├── auth.middleware.ts   # JWT authentication middleware
│       ├── types.ts             # AuthRequest interface
│       ├── AppError.ts          # Error class
│       ├── index.ts             # Exports
│       └── package.json
├── gateway/
│   ├── src/
│   ├── Dockerfile
│   └── package.json
├── auth-service/
│   ├── src/
│   │   ├── index.ts
│   │   ├── controllers/
│   │   ├── routes/
│   │   ├── middleware/          # Re-exports from shared/auth
│   │   ├── services/
│   │   └── types/
│   ├── prisma/
│   │   └── schema.prisma
│   ├── Dockerfile
│   └── package.json
├── user-service/
│   ├── src/
│   ├── Dockerfile
│   └── package.json
├── chat-service/
│   ├── src/
│   │   ├── websocket/
│   │   ├── events/
│   │   └── models/
│   ├── Dockerfile
│   └── package.json
├── notification-service/
│   ├── src/
│   ├── Dockerfile
│   └── package.json
└── README.md

🔐 Environment Variables

Each service requires a .env file. See .env.example in each service directory for required variables.

🎯 Features

• ✅ User registration and authentication (JWT)
• ✅ Real-time 1-to-1 messaging
• ✅ Group chat support
• ✅ Read receipts (sent/delivered/read)
• ✅ Typing indicators
• ✅ Online/offline presence
• ✅ Push notifications
• ✅ Message persistence
• ✅ API Gateway with routing
• ✅ Swagger documentation
• ✅ Health check endpoints
• ✅ Docker containerization
• ✅ CI/CD with GitHub Actions

🐛 Troubleshooting

1. Services not starting: Check Docker logs with docker compose logs <service-name>
2. Database connection errors: Ensure databases are healthy: docker compose ps
3. RabbitMQ connection issues: Verify RabbitMQ is running and accessible
4. Port conflicts: Check if ports are already in use and modify docker-compose.yml

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🤝 Contributing

Contributions are welcome! Please read our Contributing Guide for details on our code of conduct and the process for submitting pull requests.

⚠️ Known Limitations & Future Improvements

This is a portfolio project designed to showcase microservices architecture and development skills. The following are known limitations that would be addressed in a production environment:

Security Enhancements (Production Ready):

• Rate limiting would be implemented using express-rate-limit
• Stronger password requirements would be enforced
• CORS would be configured per environment
• Input sanitization middleware would be added

Production Optimizations:

• Connection pooling would be configured based on expected load
• Circuit breaker pattern would be implemented for resilience
• Enhanced request/response logging for observability
• Performance testing and load testing would be conducted

Architecture Improvements:

• ✅ Shared auth middleware extracted to common package (shared/auth)
• WebSocket proxy would be implemented in the gateway
• Integration test suite would be added
• API documentation would be generated (OpenAPI/Swagger)

🎯 Project Purpose

This project is part of my portfolio to demonstrate:

• Microservices architecture design and implementation
• Real-time communication systems (WebSocket)
• Message queue integration (RabbitMQ)
• Multi-database strategies (PostgreSQL, MongoDB, Redis)
• Docker containerization and orchestration
• TypeScript and modern Node.js development
• API Gateway patterns
• Test-driven development

Technologies Showcased:

• TypeScript, Express.js, Socket.io
• Prisma ORM, Mongoose
• RabbitMQ, Redis
• Docker, Docker Compose
• Bun runtime
• JWT authentication
• Microservices patterns