# Messaging Platform Architecture

## 1) Backend Architecture (FastAPI)

### High-Level Components
- API Gateway (`FastAPI` REST + WebSocket entrypoint)
- Auth Service (JWT, refresh token, email verification, password reset)
- User Service (profile, avatar metadata, user lookup)
- Chat Service (private/group/channel lifecycle and membership)
- Message Service (create/list/edit/delete messages with pagination)
- Realtime Gateway (WebSocket session management, typing/read events)
- Media Service (presigned upload URL + attachment metadata)
- Notification Service (mention and offline notifications)
- Email Service (verification and reset email delivery abstraction)
- Worker Layer (`Celery`) for async tasks (email, push, cleanup)

### Runtime Topology
- Stateless API instances behind a load balancer
- PostgreSQL for source-of-truth data
- Redis for cache, rate-limit counters, and pub/sub fan-out
- MinIO (S3-compatible) for media blobs
- Celery workers + Redis broker for background jobs

### Realtime Scaling
- Each WebSocket node subscribes to Redis channels by chat/user scope.
- Incoming `send_message` persists to PostgreSQL first.
- Message event is published to Redis; all nodes broadcast to online members.
- Offline recipients are queued for notifications.

### Security Layers
- JWT access + refresh tokens (short-lived access, longer refresh)
- `bcrypt` password hashing
- Email verification required before login
- Tokenized password reset flow
- DB indexes on auth and chat/message lookup paths
- Ready extension points for rate limiting and anti-spam middleware

### Suggested Backend Tree
```text
backend/
  app/
    main.py
    config/
      settings.py
    database/
      base.py
      session.py
      models.py
    auth/
      models.py
      schemas.py
      repository.py
      service.py
      router.py
    users/
      models.py
      schemas.py
      repository.py
      service.py
      router.py
    chats/
      models.py
      schemas.py
      repository.py
      service.py
      router.py
    messages/
      models.py
      schemas.py
      repository.py
      service.py
      router.py
    media/
      models.py
      schemas.py
      repository.py
      service.py
      router.py
    realtime/
      models.py
      schemas.py
      repository.py
      service.py
      router.py
    notifications/
      models.py
      schemas.py
      repository.py
      service.py
      router.py
    email/
      models.py
      schemas.py
      repository.py
      service.py
      router.py
    utils/
      security.py
```

## 2) Web Client Architecture (React + TypeScript)

### Layers
- `src/api`: typed Axios clients (auth, users, chats, messages, media)
- `src/store`: Zustand stores (session, chat list, active chat, realtime state)
- `src/chat`: domain logic (message normalization, optimistic updates)
- `src/hooks`: composable hooks (`useAuth`, `useChatMessages`, `useWebSocket`)
- `src/components`: reusable UI units (message bubble, composer, media picker)
- `src/pages`: route-level pages (`Login`, `Register`, `Chats`, `ChatDetail`)

### Data Flow
- HTTP for CRUD and pagination
- WebSocket for realtime events (`receive_message`, typing, read receipts)
- Optimistic UI on send, rollback on failure
- Local cache keyed by chat id + pagination cursor

## 3) Android Architecture (Kotlin + Compose)

### Layers (MVVM)
- `network`: Retrofit API + WebSocket client
- `data`: DTOs + Room entities + DAOs
- `repository`: sync strategy between remote and local cache
- `viewmodel`: state, intents, side-effects
- `ui/screens`: Compose screens (`Auth`, `ChatList`, `ChatRoom`, `Profile`)
- `ui/components`: reusable composables

### Realtime Strategy
- WebSocket manager as singleton service (Hilt)
- ChatViewModel subscribes to events by selected chat
- Persist inbound messages to Room first, then render state from DB flows
- Push notifications bridged to deep links into chat screens