MK Chats

A secure, real-time chat application built with FastAPI, Socket.IO, WebRTC, Redis, and PostgreSQL.

About

MK Chats is a modern real-time chat application built with FastAPI.

It provides secure authentication, real-time messaging, End-to-End Encryption (E2EE), file and image sharing, presence indicators, typing indicators, message replies, read receipts, contact management, blocking, and audio/video calling using WebRTC.

The application uses Socket.IO for real-time communication and Redis for presence and message/event coordination.

✨ Features

🔐 Authentication & Security

User registration and login
Cookie-based authentication
Bearer token authentication support
Password change
Email-based password reset
Content Security Policy (CSP) middleware
Privacy Policy and Terms & Conditions pages

💬 Real-Time Messaging

Real-time one-to-one messaging
Socket.IO-powered communication
Typing indicators
Online/offline presence
Read receipts
Message editing
Message deletion
Message replies
Unread message counts
Message history
Clear chat functionality
Background cleanup of cleared messages

🔒 End-to-End Encryption

End-to-End Encryption (E2EE) for text messages
Encrypted file and image transfers
Client-side cryptographic key handling
DEK/KEK-based encryption architecture
Encryption keys stored securely on the server

📎 Files & Media

Image messages
File messages
Encrypted file transfers
Reply to messages containing files/images

📞 Audio & Video Calls

Audio calling
Video calling
WebRTC peer-to-peer connections
Socket.IO-based WebRTC signaling
Upgrade audio calls to video
Call history
Call session management

👥 Contacts

Contact list
Contact search
Latest message preview
Unread message counts
Block contacts
Unblock contacts

🛠️ Tech Stack

Technology	Purpose
Python	Programming language
FastAPI	Backend web framework
SQLAlchemy	ORM / database interaction
Alembic	Database migrations
PostgreSQL	Primary database
Redis	Presence and real-time coordination
Socket.IO	Real-time communication
Jinja2	Server-side HTML rendering
WebRTC	Peer-to-peer audio/video calls
Pytest	Automated testing

📁 Project Structure

chat-app/
│
├── app/
│   ├── routers.py             # Root API router
│   ├── api_user.py            # Authentication and profile logic
│   ├── api_contact.py         # Contacts and blocking logic
│   ├── api_message.py         # Messaging and chat logic
│   ├── api_call.py            # Call history logic
│   ├── main.py                # FastAPI application setup
│   ├── models.py              # SQLAlchemy models
│   ├── schemas.py             # Pydantic schemas
│   ├── web_page.py            # Web page routes
│   ├── socket_events.py       # Socket.IO event handlers
│   │
│   ├── core/
│   │   └── ...                # Database, authentication and core utilities
│   │
│   ├── services/
│   │   └── ...                # Background tasks and services
│   │
│   ├── static/
│   │   └── ...                # CSS, JavaScript, images and branding
│   │
│   └── templates/
│       └── ...                # Jinja2 templates
│
├── alembic/
│   └── ...                    # Database migrations
│
├── test/
│   └── ...                    # Automated tests
│
├── requirements.txt
└── README.md

📋 Prerequisites

Before running the application, make sure you have:

Python 3.11+
PostgreSQL
Redis
SMTP credentials for password reset emails

🚀 Installation

1. Clone the repository

git clone https://github.com/MayurMathavadiya/chat-app.git
cd chat-app

2. Create a virtual environment

python -m venv .venv

Activate it:

Linux / macOS

source .venv/bin/activate

Windows

.venv\Scripts\activate

3. Install dependencies

pip install -r requirements.txt

⚙️ Environment Variables

Create a .env file in the project root:

SQLALCHEMY_DATABASE_URL=postgresql://username:password@localhost:5432/mk_chats

REDIS_URL=redis://localhost:6379/0

SECRET_KEY=your-secret-key
ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=10080

SMTP_SERVER=smtp.gmail.com
SMTP_PORT=587
SMTP_USERNAME=your-email@example.com
SMTP_PASSWORD=your-email-password-or-app-password
SMTP_FROM_EMAIL=your-email@example.com

Important: Never commit your .env file, passwords, API keys, SMTP credentials, or other secrets to GitHub.

🗄️ Database Setup

Make sure PostgreSQL is running and your database exists.

Then run the Alembic migrations:

alembic upgrade head

🔴 Start Redis

Make sure Redis is running:

redis-server

Or, if Redis is already installed as a system service:

sudo systemctl start redis

▶️ Run the Application

Start the FastAPI development server:

uvicorn app.main:app --reload

The application will be available at:

http://127.0.0.1:8000

🌐 Web Routes

Route	Description
`/`	Chat application
`/login`	Login page
`/register`	Registration page
`/forgot-password`	Password reset request
`/reset-password`	Password reset
`/privacy`	Privacy Policy
`/terms`	Terms & Conditions

🔌 REST API

Authentication & Profile

POST   /api/register
POST   /api/login
POST   /api/logout
POST   /api/forgot-password
POST   /api/reset-password

GET    /api/profile
PATCH  /api/profile
POST   /api/profile/password

Contacts

GET    /api/contacts
POST   /api/contacts/block
POST   /api/contacts/unblock

Messages

GET    /api/messages/{contact_id}
POST   /api/messages/clear/{contact_id}

Calls

GET    /api/calls/history
POST   /api/calls
PATCH  /api/calls/{call_id}

⚡ Socket.IO

MK Chats uses Socket.IO for real-time communication between clients and the server.

Messaging Events

Event	Description
`send`	Send a message
`edit`	Edit an existing message
`delete`	Delete a message
`typing`	Broadcast typing status
`mark_read`	Mark messages as read
`presence`	Broadcast online/offline status

The send event supports features such as:

reply_to_id
file_data

📞 WebRTC Signaling

Audio and video calls use WebRTC for peer-to-peer media communication.

Socket.IO is used for signaling.

Signaling Events

webrtc_offer
webrtc_answer
webrtc_ice_candidate

webrtc_upgrade_request
webrtc_upgrade_response

webrtc_end

The actual audio/video media connection is established using WebRTC peer connections.

🔐 Authentication

Authentication can be performed using an access_token cookie or an HTTP Authorization header.

Example:

Authorization: Bearer <access_token>

The application supports long-lived access tokens using the configured:

ACCESS_TOKEN_EXPIRE_MINUTES=10080

🔒 End-to-End Encryption

MK Chats is designed around an End-to-End Encryption architecture.

Cryptographic keys are derived and handled on the client, while encrypted key material can be stored by the server.

The goal is to prevent the server from directly accessing the plaintext contents of encrypted messages and files.

Security Note: E2EE security depends on the complete client-side cryptographic implementation, key management, authentication, and deployment configuration. Review the implementation carefully before using this project for sensitive or production communication.

🧪 Testing

Run the test suite with:

pytest

For more detailed output:

pytest -v

🏗️ Architecture

At a high level, MK Chats works like this:

                    ┌──────────────────┐
                    │      Browser     │
                    │                  │
                    │  Jinja2 + JS     │
                    │  WebRTC Client   │
                    └────────┬─────────┘
                             │
                    HTTP / Socket.IO
                             │
                             ▼
                    ┌──────────────────┐
                    │     FastAPI      │
                    │                  │
                    │ REST API         │
                    │ Authentication   │
                    │ Socket.IO        │
                    │ WebRTC Signaling │
                    └───────┬──────────┘
                            │
              ┌─────────────┼─────────────┐
              │             │             │
              ▼             ▼             ▼
        ┌──────────┐  ┌──────────┐  ┌──────────┐
        │PostgreSQL│  │  Redis   │  │  SMTP    │
        │          │  │          │  │          │
        │  Data    │  │ Presence │  │  Email   │
        │  Storage │  │  Events  │  │  Reset   │
        └──────────┘  └──────────┘  └──────────┘

For audio/video calls:

       User A                         User B
          │                              │
          │        Socket.IO             │
          │◄────── Signaling ───────────►│
          │                              │
          │                              │
          └──────── WebRTC ──────────────┘
                Peer-to-Peer Media

📌 Development Notes

Socket.IO uses Redis for real-time coordination and presence.
WebRTC handles peer-to-peer audio/video communication.
Jinja2 is used for server-rendered pages.
PostgreSQL stores application data.
Alembic manages database schema migrations.
Background services handle cleanup-related tasks.
CSP middleware provides additional browser-side security.
Authentication supports both cookies and Bearer tokens.

⚠️ Production Considerations

Before deploying MK Chats to production:

Use a strong randomly generated SECRET_KEY.
Never expose .env or credentials.
Use HTTPS.
Configure secure cookies.
Use a production PostgreSQL instance.
Use a secured Redis instance.
Configure a proper SMTP provider.
Review WebRTC/STUN/TURN configuration.
Review the E2EE implementation and key-management model.
Run the application behind a production ASGI server/reverse proxy.
Configure appropriate CORS and CSP policies.

📄 License

Add your preferred open-source license to the repository, such as MIT, before publishing the project for reuse.

👨‍💻 Author

Mayur Mathavadiya

GitHub: https://github.com/MayurMathavadiya

Built with ❤️ using FastAPI, Python, Socket.IO, WebRTC, Redis and PostgreSQL.

Name		Name	Last commit message	Last commit date
alembic		alembic
app		app
test		test
.env.example		.env.example
.gitignore		.gitignore
README.md		README.md
alembic.ini		alembic.ini
pytest.ini		pytest.ini
requirements.txt		requirements.txt
tailwind.config.js		tailwind.config.js

Latest commit

History

Folders and files

Repository files navigation

MK Chats

About

✨ Features

🔐 Authentication & Security

💬 Real-Time Messaging

🔒 End-to-End Encryption

📎 Files & Media

📞 Audio & Video Calls

👥 Contacts

🛠️ Tech Stack

📁 Project Structure

📋 Prerequisites

🚀 Installation

1. Clone the repository

2. Create a virtual environment

3. Install dependencies

⚙️ Environment Variables

🗄️ Database Setup

🔴 Start Redis

▶️ Run the Application

🌐 Web Routes

🔌 REST API

Authentication & Profile

Contacts

Messages

Calls

⚡ Socket.IO

Messaging Events

📞 WebRTC Signaling

Signaling Events

🔐 Authentication

🔒 End-to-End Encryption

🧪 Testing

🏗️ Architecture

📌 Development Notes

⚠️ Production Considerations

📄 License

👨‍💻 Author

Star History

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages