CS262 Chat Application

Welcome to our chat app, a PyQt6-based client with a dark theme UI and a Python server for real-time messaging!

Our application is built with a client-server architecture, supporting multiple clients connecting to the server from different machines. We have implemented two wire protocols: JSON and our custom protocol (SAMIRA🔥), as well as a fault-tolerant replication system using gRPC for server-to-server communication.

Getting Started

Prerequisites

• Python 3.8+
• pip (Python package manager)
• make (build tool)

Quick Start

1. Clone and install:

git clone https://github.com/mirabor/cs262-chat.git
cd cs262-chat
make install && make install-dev

2. Start first server in the cluster:

make run-server MODE=grpc SERVER_ID=server1 PORT=5555

Note: when you start the first server, it will log the IP address under “Network Interface” section. Take note of your IP address so that you can reference it as a peer when you add new replica nodes.

To add replica nodes, run same command but with a list of peers' addresses (comma-separated).

make run-server MODE=grpc SERVER_ID=server2 PORT=5556 PEERS=FIRST_SERVER_IP:5555

Also take note of your second server’s IP address here.

make run-server MODE=grpc SERVER_ID=server3 PORT=5557 PEERS=FIRST_SERVER_IP:5555, SECOND_SERVER_IP:5556

Replace FIRST_SERVER_IP and SECOND_SERVER_IP with your first server’s IP address and your second server’s IP address, respectively. You can add more by following the same structure. Each sever will work on its own database (also logged).

4. Start client

make run-client MODE=grpc PORT=5555 CLIENT_ID=client1 SERVER_IP=LEADER_IP

Note

LEADER_IP will be displayed on the leader machine (most likely server1 if you used instruction above) where the server is running, along with other server details (e.g. what wire protocol is being used, port, etc.).

Features

Our application implements the below functional requirements:

• Account Management

• Create account with unique username, nickname, and password

• Log in with existing account

• Delete account

• List/search accounts with wildcard support

• Messaging

• Real-time message delivery

• Offline message storage

• Configurable unread message to be delivered at any time

• Message status tracking (number of unread messages)

• Individual and bulk message deletion

• Multi-Machine Support

• Tested server-client communication on different machines

• Server accessible from any client on the network

• Tested with two wire protocols: JSON and our custom protocol (SAMIRA🔥)

• Fault-Tolerant Replication

• Raft-inspired leader election protocol

• 2-fault tolerant server cluster

• Automatic failover with leader election

• Dynamic server addition to the replica set

• gRPC-based server-to-server communication

For more details on features, high-level design, and implementation, see our High-Level Design & Implementation Plan.

Documentation Structure

Our documentation is organized for easy navigation:

• Client Documentation

  PyQt6-based GUI application covering:

  • UI components and pages
  • Implements our User journey diagrams
  • Client code communication with server

• Server Documentation

  • API endpoints
  • Database schema
  • Server setup code

• Protocol Documentation

  • Wire protocol specifications
  • Message format details
  • Protocol Implementation (JSON vs Custom)

• Replication Documentation

  • Fault-tolerant architecture
  • Raft-inspired leader election
  • Server-to-server communication
  • Testing instructions

Note

Engineering Notebook For our other documents, especially engineering notebooks, see the notebook.md file and the Issues Page

Testing Coverage

Our test suite coverage report can be found by clicking on the badge below:

Also, you can run the test suite locally with:

make test

Project Structure

├── Makefile
├── design/
│   ├── notebook.md
│   ├── replicas-notebook.md
│   └── wire-protocol-notebook.md
├── src/
│   ├── client/
│   │   ├── components/
│   │   └── pages/
│   ├── protocol/ # Protocol definitions and handlers
│   │   ├── grpc/
│   │   │   ├── chat_pb2.py
│   │   │   ├── chat_pb2_grpc.py
│   │   │   ├── replication_pb2.py
│   │   │   └── replication_pb2_grpc.py
│   │   ├── json/
│   │   └── samira/   # (custom impl, samira)
│   ├── replication/
│   │   ├── config.py
│   │   ├── election_manager.py
│   │   ├── heartbeat_manager.py
│   │   ├── replica_node.py 
│   │   ├── replica_state.py
│   │   └── replication_manager.py
│   └── server/
└── tests/
    ├── client/
    ├── protocol/
    ├── replication/
    └── server/

Problem 1 Demo

giphy1.mp4

giphy.mp4

giphy.1.mp4

giphy.2.mp4

giphy.3.mp4

giphy.4.mp4

Development

Code Style

• Follows PEP 8 guidelines
• Auto-formatting available:

make fix-style

Tip

For other development make commands, simply run make to see the available options.