chatapplicationbackend-7fz4ma/README.md

# Chat Application Backend

A real-time chat application backend built with FastAPI and SQLite, featuring WebSocket support for instant messaging.

## Features

- User authentication with JWT
- User profile management
- Real-time messaging with WebSockets
- Support for direct messages and group chats
- Message read status tracking
- Typing indicators
- RESTful API for chat functionality
- Database migrations with Alembic
- Health check endpoint

## Tech Stack

- **Framework**: FastAPI
- **Database**: SQLite
- **ORM**: SQLAlchemy
- **Authentication**: JWT (JSON Web Tokens)
- **Real-time Communication**: WebSockets
- **Migration**: Alembic

## Project Structure

```
.
├── alembic/                 # Database migration files
│   ├── versions/            # Migration version scripts
│   ├── env.py               # Alembic environment configuration
│   └── script.py.mako       # Migration script template
├── app/                     # Application package
│   ├── api/                 # API endpoints
│   │   ├── dependencies/    # Endpoint dependencies (auth, etc.)
│   │   └── endpoints/       # API route definitions
│   ├── core/                # Core application components
│   │   ├── config.py        # Application configuration
│   │   └── security.py      # Security utilities
│   ├── db/                  # Database components
│   │   ├── repositories/    # Database CRUD operations
│   │   └── session.py       # Database session management
│   ├── models/              # SQLAlchemy ORM models
│   ├── schemas/             # Pydantic schemas for validation
│   ├── services/            # Business logic services
│   └── utils/               # Utility functions
├── main.py                  # Application entry point
├── alembic.ini              # Alembic configuration
└── requirements.txt         # Project dependencies
```

## API Endpoints

### Authentication

- `POST /api/v1/auth/signup` - Register a new user
- `POST /api/v1/auth/login` - Login and get access token
- `GET /api/v1/auth/me` - Get current user information

### User Management

- `GET /api/v1/users` - List all users
- `GET /api/v1/users/{user_id}` - Get user details
- `PUT /api/v1/users/me` - Update current user profile

### Conversations

- `POST /api/v1/conversations` - Create a new conversation
- `GET /api/v1/conversations` - List user's conversations
- `GET /api/v1/conversations/{conversation_id}` - Get conversation details
- `PUT /api/v1/conversations/{conversation_id}` - Update conversation details

### Messages

- `POST /api/v1/conversations/{conversation_id}/messages` - Send a message
- `GET /api/v1/conversations/{conversation_id}/messages` - Get conversation messages
- `PUT /api/v1/messages/{message_id}/read` - Mark a message as read
- `GET /api/v1/messages/unread/count` - Get unread message count

### WebSocket

- `WebSocket /api/v1/ws` - Real-time messaging WebSocket endpoint

### Health Check

- `GET /health` - Application health check endpoint

## Getting Started

### Prerequisites

- Python 3.8+
- SQLite

### Installation

1. Clone the repository
2. Install dependencies:

```bash
pip install -r requirements.txt
```

3. Run database migrations:

```bash
alembic upgrade head
```

4. Start the server:

```bash
uvicorn main:app --reload
```

The API will be available at http://localhost:8000 with documentation at http://localhost:8000/docs.

## WebSocket Communication Protocol

The WebSocket endpoint supports the following message types:

### Authentication

Client sends:
```json
{
  "token": "your_jwt_token"
}
```

### Send Message

Client sends:
```json
{
  "type": "message",
  "conversation_id": "conversation_uuid",
  "content": "Hello, world!",
  "recipient_id": "recipient_uuid" // Optional, for direct messages
}
```

### Mark Message as Read

Client sends:
```json
{
  "type": "mark_read",
  "message_id": "message_uuid"
}
```

### Typing Indicator

Client sends:
```json
{
  "type": "typing",
  "conversation_id": "conversation_uuid"
}
```

### Server Push Notifications

Server sends:

1. New message:
```json
{
  "type": "new_message",
  "message": {
    "id": "message_uuid",
    "content": "Hello, world!",
    "sender_id": "sender_uuid",
    "recipient_id": "recipient_uuid",
    "conversation_id": "conversation_uuid",
    "is_read": false,
    "created_at": "2023-05-12T10:30:00Z",
    "updated_at": "2023-05-12T10:30:00Z"
  },
  "timestamp": "2023-05-12T10:30:00Z"
}
```

2. Message read confirmation:
```json
{
  "type": "message_read",
  "message_id": "message_uuid",
  "timestamp": "2023-05-12T10:31:00Z"
}
```

3. User typing notification:
```json
{
  "type": "user_typing",
  "user_id": "user_uuid",
  "conversation_id": "conversation_uuid",
  "timestamp": "2023-05-12T10:32:00Z"
}
```

## License

This project is licensed under the MIT License.