first commit

ARCHITECTURE.md

@@ -0,0 +1,132 @@
+# 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
+