🔒 Ratchet Messenger

A secure, end-to-end encrypted messaging application built with React and FastAPI, implementing the Double Ratchet protocol for perfect forward secrecy.

🌟 Features

• End-to-End Encryption: Double Ratchet protocol implementation
• Real-time Messaging: WebSocket-based instant messaging
• Perfect Forward Secrecy: Cryptographic keys rotate automatically
• Modern UI: Beautiful glass morphism design with smooth animations
• Typing Indicators: Real-time typing status
• File Sharing: Secure file attachments
• Message Reactions: Emoji reactions to messages
• Contact Management: Search and manage contacts

🏗️ Architecture

Frontend (React + Vite)

• React 18 with functional components and hooks
• Vite for fast development and building
• Framer Motion for smooth animations
• Tailwind CSS for styling
• WebSocket for real-time communication
• React Query for data fetching and caching

Backend (FastAPI + Python)

• FastAPI for high-performance API
• WebSocket support for real-time messaging
• Double Ratchet cryptographic protocol
• Local file storage for messages and keys
• Pydantic for data validation

🚀 Quick Start

Prerequisites

• Node.js 18+
• Python 3.8+
• Git

Frontend Setup

# Navigate to frontend directory
cd frontend

# Install dependencies
npm install

# Start development server
npm run dev

The frontend will be available at http://localhost:5173

Backend Setup

# Navigate to backend directory
cd backend

# Create virtual environment
python -m venv .venv

# Activate virtual environment
# On Windows:
.venv\Scripts\activate
# On macOS/Linux:
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Start the server
uvicorn app.main:app --reload --host 127.0.0.1 --port 8000

The backend API will be available at http://localhost:8000

📁 Project Structure

ratchet-messenger/
├── frontend/                 # React frontend application
│   ├── src/
│   │   ├── components/      # React components
│   │   ├── hooks/          # Custom React hooks
│   │   ├── lib/            # API and WebSocket clients
│   │   ├── styles/         # CSS styles
│   │   └── data/           # Sample data
│   └── package.json
├── backend/                 # FastAPI backend application
│   ├── app/
│   │   ├── routes/         # API route handlers
│   │   ├── services/       # Business logic services
│   │   ├── models/         # Data models
│   │   └── schemas/        # Pydantic schemas
│   └── requirements.txt
├── data/                   # Application data storage
├── storage/                # File storage
└── scripts/                # Utility scripts

🔐 Security Features

• Double Ratchet Protocol: Automatic key rotation
• Perfect Forward Secrecy: Past messages remain secure even if keys are compromised
• Identity Key Verification: Cryptographic identity verification
• End-to-End Encryption: Messages encrypted client-side
• Secure Key Storage: Local key management with proper permissions

🛠️ Development

Frontend Development

• Hot reload with Vite
• ESLint for code quality
• Tailwind CSS for styling
• Framer Motion for animations

Backend Development

• FastAPI auto-reload
• Pydantic validation
• Local JSON storage
• WebSocket real-time updates

📝 API Endpoints

Users

• POST /api/users/register - Register new user
• GET /api/contacts - Get contact list

Sessions

• POST /api/sessions/initiate - Initiate Double Ratchet session
• GET /api/sessions/{userId}/{peerId} - Get session state

Messages

• POST /api/messages/send - Send encrypted message
• GET /api/messages - Retrieve messages
• POST /api/messages/pollAck - Acknowledge message delivery

WebSocket

• WS /ws - Real-time messaging and typing indicators

🎨 UI Features

• Glass Morphism Design: Modern translucent UI elements
• Smooth Animations: Framer Motion powered transitions
• Responsive Layout: Works on desktop and mobile
• Dark Theme: Easy on the eyes
• Interactive Elements: Hover effects and micro-interactions

🔧 Configuration

Environment Variables

Create a .env file in the backend directory:

API_HOST=127.0.0.1
API_PORT=8000

📦 Dependencies

Frontend

• React 18
• Vite
• Framer Motion
• Tailwind CSS
• React Query
• Axios

Backend

• FastAPI
• Uvicorn
• DoubleRatchet
• PyNaCl
• Cryptography

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

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

🙏 Acknowledgments

• Double Ratchet protocol by Trevor Perrin and Moxie Marlinspike
• Signal Protocol Foundation
• React and FastAPI communities

---

Built with ❤️ for secure communication