ChatFlow (FastAPI + Next.js)

Full-stack real-time chat with a FastAPI backend and a Next.js UI. Supports WebSocket messaging, PostgreSQL persistence, Redis pub/sub, JWT auth, presence, typing indicators, read receipts, reactions, and an AI assistant DM.

Architecture

flowchart LR
  Web[Next.js Web App] -->|HTTP + WS| API[FastAPI App]
  API --> DB[(PostgreSQL)]
  API --> R[(Redis Pub/Sub)]
  API --> M[Metrics /health /ready /metrics]

Loading

Repo Layout

• app/ FastAPI backend (API + WebSocket)
• next-js-chat-app/ Next.js frontend

Quick Start (Docker)

docker compose up --build

Backend will be available at http://localhost:8000.

Run Locally (Backend)

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

export DATABASE_URL=postgresql://postgres:postgres@localhost:5432/chatdb
export REDIS_URL=redis://localhost:6379/0
export JWT_SECRET_KEY=change-me

uvicorn app.main:app --reload

Run Locally (Frontend)

cd next-js-chat-app
pnpm install
pnpm dev

Set the API base if you are not using the default backend URL:

export NEXT_PUBLIC_API_BASE_URL=http://localhost:8000

Frontend will be available at http://localhost:3000.

Tests

Make sure Postgres and Redis are running (docker-compose is easiest):

docker compose up -d db redis
pytest

The tests expect DATABASE_URL to point to a reachable Postgres instance.

WebSocket Usage (JS Example)

const token = "YOUR_JWT";
const ws = new WebSocket(`ws://localhost:8000/ws/chat?token=${token}`);

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log(data);
};

ws.onopen = () => {
  ws.send(JSON.stringify({ type: "join_room", room_id: "ROOM_UUID" }));
  ws.send(JSON.stringify({
    type: "send_message",
    room_id: "ROOM_UUID",
    content: "Hello from WebSocket!"
  }));
};

Sample Flow (HTTP + WS)

1. Register and login:

curl -X POST http://localhost:8000/auth/register \
  -H "Content-Type: application/json" \
  -d '{"username":"alice","email":"alice@example.com","password":"Password123!"}'

2. Create a direct room:

curl -X POST http://localhost:8000/api/rooms \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"room_type":"direct","member_ids":["OTHER_USER_UUID"]}'

3. Connect via WebSocket:

ws://localhost:8000/ws/chat?token=<TOKEN>

4. Join room and send message:

{ "type": "join_room", "room_id": "ROOM_UUID" }
{ "type": "send_message", "room_id": "ROOM_UUID", "content": "Hi" }

Key Endpoints

• POST /auth/register
• POST /auth/login
• GET /auth/me
• POST /api/rooms
• GET /api/rooms/ai-dm
• GET /api/rooms/{room_id}/messages
• POST /api/rooms/{room_id}/read
• GET /api/rooms/{room_id}/online-users
• GET /api/users/{user_id}/status
• GET /metrics, /health, /ready

Notes

• Redis is used for pub/sub, presence, and rate limiting.
• Message history supports pagination, search, and filters.