Real-Time Chat API

FastAPI backend for a real-time chat application. It supports JWT authentication, 1-to-1 and group conversations, message history, and WebSocket-based live messaging backed by Redis Pub/Sub for multi-instance broadcasting.

Quick Links

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

Features

• JWT auth with refresh tokens
• 1-to-1 conversations
• Group conversations with roles (owner, admin, member)
• Group member management
• Message history pagination
• WebSocket real-time messaging
• Redis Pub/Sub for cross-instance fan-out

Tech Stack

• FastAPI, Pydantic
• SQLAlchemy (async), Alembic
• PostgreSQL, Redis
• JWT (python-jose), Passlib/Argon2
• Docker, Docker Compose, Pytest

Project Structure

• app/api - Versioned API routes
• app/api/v1/chat_one_to_one.py - 1-to-1 + conversation endpoints
• app/api/v1/chat_group.py - Group management endpoints
• app/api/v1/chat_ws.py - WebSocket endpoint
• app/api/v1/user.py - User endpoints
• app/api/v1/auth.py - Auth endpoints
• app/models - SQLAlchemy models
• app/schemas - Pydantic schemas
• app/services - Business logic
• app/core - Config, security, Redis, WebSockets
• app/db - Async database setup
• alembic - Migrations
• tests - Automated tests

Configuration

API base path is composed from .env values:

• API_PREFIX=/api
• API_V1=/v1

Default base URL becomes http://localhost:8000/api/v1.

Getting Started (Docker)

1. cp .env.example .env
2. docker-compose up -d --build
3. Open http://localhost:8000/docs

Getting Started (Local)

1. Create and fill .env (see .env.example).
2. Install deps: uv sync or pip install -r <generated requirements>
3. Run: uvicorn app.main:app --reload

Authentication

• Login uses OAuth2 password flow (username + password form fields).
• Refresh tokens are returned in the response body and also set as an HTTP-only cookie (refresh_token) scoped to /api/v1/auth/refresh.
• Protected endpoints require Authorization: Bearer <access_token>.

Endpoints

Base URL: /api/v1

Root

• GET / - Health check
• POST /sent-notification/{email} - Background notification (query: message)

Auth

• POST /api/v1/auth/register - Register user
• POST /api/v1/auth/login - Login (OAuth2 form)
• POST /api/v1/auth/refresh - Refresh access token
• GET /api/v1/auth/me - Current user (auth required)

Users

• POST /api/v1/users/ - Create user
• GET /api/v1/users/ - List users (query: skip, limit)
• GET /api/v1/users/{user_id} - Get user
• PUT /api/v1/users/{user_id} - Update user (auth required)
• DELETE /api/v1/users/{user_id} - Delete user (auth required)

1-to-1 Conversations

• GET /api/v1/chat/conversations - List my conversations (auth required)
• POST /api/v1/chat/conversations - Get or create conversation (auth required)
• GET /api/v1/chat/conversations/{conversation_id}/messages - List messages (auth required, query: skip, limit)

Groups

• POST /api/v1/chat/groups - Create group (auth required)
• GET /api/v1/chat/groups/{conversation_id} - Group detail (auth required)
• PATCH /api/v1/chat/groups/{conversation_id} - Update group (auth required)
• GET /api/v1/chat/groups/{conversation_id}/members - List members (auth required)
• POST /api/v1/chat/groups/{conversation_id}/members - Add member (auth required)
• DELETE /api/v1/chat/groups/{conversation_id}/members/{user_id} - Remove member (auth required)
• PATCH /api/v1/chat/groups/{conversation_id}/members/{user_id}/role - Update member role (auth required)

WebSocket

• WS /api/v1/chat/ws/conversations/{conversation_id}
• Auth via query string ?token=<access_token> or header Authorization: Bearer <access_token>

WebSocket Payloads

Client to server:

{"type": "message.send", "content": "hello"}

Server to client:

{"type": "message.new", "message": {"id": "...", "content": "..."}}

Status

This project is intended for learning and development.