🚀 Shareholding Microservices Architecture (Event-driven, FastAPI, Kafka, gRPC)

Author: Utsav Moradiya
Last Updated: 2025-06-29 22:02:12

---

🧠 Concept Summary

Each user is treated as a shareholder. Their share value fluctuates randomly every few seconds. The updates are:

• Streamed via Kafka and WebSocket/GraphQL Subscriptions
• Displayed in real-time on a dashboard
• Saved to DB via event when user clicks "Save Snapshot"

---

🏗️ Architecture Overview

                             Frontend (React + Apollo)
                                │
                                ▼
                          Gateway Service (Optional)
                                │
        ┌───────────────────────┼──────────────────────┐
        ▼                       ▼                      ▼
   User Service          Kafka Broker          Notification Service (gRPC)
     │                        ▲                      ▲
     ▼                        │                      │
PostgreSQL             Topic: user.price.update    WebSocket/Email/SMS

---

⚙️ Tech Stack

• Backend: FastAPI, gRPC, SQLAlchemy (Async)
• Real-time: Kafka, WebSocket, GraphQL Subscriptions
• Frontend: React + Tailwind + Apollo Client
• DB: PostgreSQL, Redis (cache)
• DevOps: Docker, Docker Compose

---

✅ Microservice Functionality

1. User Service (/api/v1/users)

Endpoint	Method	Description
/register	POST	Register user, assign value
/login	POST	Login and return JWT
/me	GET	Protected route (JWT)
/save-snapshot	POST	Fires event to save value
/graphql	POST	Query users + subscriptions
/ws	WS	WebSocket real-time feed

2. Notification Service

• gRPC Server:
  • SendEmailNotification
  • SendSMSNotification
• Kafka Consumer:
  • Topic: user.price.update
  • Broadcast via WebSocket

3. Analytics Service

Endpoint	Method	Description
/analytics/user/{id}	GET	Avg change, snapshot history

---

🔄 Background Worker

• Updates all user share values randomly every 5s
• Sends to Kafka user.price.update

---

🧪 Test Scenarios

1. ✅ Register new user via /api/v1/users/register
2. ✅ Login and get JWT
3. ✅ Subscribe to GraphQL via WebSocket (onUserRegistered)
4. ✅ View updates in frontend (WebSocket/GraphQL)
5. ✅ Save snapshot and verify event stored in DB
6. ✅ gRPC call to Notification triggered on event
7. ✅ Kafka message logged for all updates

---

📦 Docker Commands

• docker-compose up --build
• Check ports:
  • Kafka: localhost:9092
  • Zookeeper: localhost:2181
  • User Service: localhost:8001
  • Notification Service: localhost:8002

---

🧰 Project Structure

user_service/
├── src/
│   ├── api/
│   ├── db/
│   ├── graphql/
│   ├── kafka/
│   ├── grpc/
│   ├── websocket/
│   └── main.py
notification_service/
├── src/
│   ├── grpc/
│   ├── kafka/
│   └── main.py
frontend/
├── src/
│   └── ... (React app)
analytics_service/
├── src/
│   └── ...

---

📌 Notes

• Use WebSocketClient or GraphQL Playground to test subscriptions
• JWT auth is applied to GraphQL context and WebSockets
• Event-driven + loosely coupled microservices = scalable

---