Messenger/ARCHITECTURE.md

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

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