How kailasss2k05/event-driven-complaint-system works
1. Overall shape
- This repo is an event-driven municipal complaint platform split into a React frontend and several Python FastAPI services.
- The runtime architecture is centered on request/response for user actions plus Kafka for asynchronous workflow steps and fan-out side effects.
2. Primary user-facing boundary
- The frontend in frontend/src is a Vite/React app with three main portals: citizen, staff, and admin.
- It talks to backend APIs over HTTP for auth, complaint operations, and notification history, and keeps a WebSocket connection to the notification service for live updates.
3. Complaint service as the main orchestration point
- backend/complaint_service/main.py is the core API on port 8000.
- It handles signup/login, complaint submission, complaint lookup, image upload, and admin/staff workflows such as assignment and status changes.
- This service is the main entry point that ties together authentication, PostgreSQL persistence, ML enrichment, and Kafka event publishing.
4. Authentication boundary
- backend/auth/ contains JWT/OAuth2/security code and the auth router/schemas.
- Auth is not a standalone external service; it is a shared backend module used by the complaint API to issue tokens and enforce role-based access like user, department_admin, and super_admin.
5. ML enrichment path
- backend/ml_service/main.py exposes the ML API on port 8001 with predict/translate/summarize endpoints.
- model_loader.py loads persisted models from ml_model/saved_models, while the training scripts and datasets under ml_model/training and ml_model/dataset are offline assets, not part of the live request path.
- The complaint service calls this ML service synchronously to classify complaints and infer priority before emitting downstream events.
6. Kafka as the asynchronous backbone
- Kafka is the integration layer between the complaint service and downstream processing.
- The repo defines topics such as complaint-submitted, complaint-validated, complaint-categorized, complaint-assigned, and complaint-status-updated.
- kafka/create-topics.sh initializes the topic set during deployment.
7. Consumer microservices
- validation_service, assignment_service, and audit_service are separate Kafka consumer processes, each with its own kafka_consumer.py.
- Validation re-checks complaint content, assignment routes work to departments, and audit records event history.
- These services are intentionally decoupled from the user-facing API and react only to Kafka events.
8. Notification subsystem
- backend/notification_service/ is another FastAPI service on port 8002 with both HTTP and WebSocket interfaces.
- It persists notifications through notification_store.py, pushes live updates through websocket_manager.py, and sends email via email_service.py.
- It also consumes Kafka events so notifications are generated from the same event stream as audit/assignment/validation.
9. Data layer
- PostgreSQL is the primary durable store, configured through backend/db/database.py and backend/db/schema.sql.
- seed_admin_users.py indicates bootstrap data for administrative access.
- The notification service also reads/writes its own notification records, so the database acts as shared persistence across multiple services rather than a single monolithic schema owner.
10. Operational flow of a complaint
- A citizen submits a complaint in the frontend.
- The complaint service authenticates the user, optionally uploads images, calls ML for categorization/priority, saves the record, and publishes Kafka events.
- Validation, assignment, audit, and notification services react independently; status updates later propagate back through the same event-driven path.
11. Infrastructure and deployment boundary
- docker-compose.yml coordinates the full stack: Kafka/Zookeeper, the FastAPI services, and supporting infrastructure.
- The single Dockerfile suggests a shared Python container base for backend services.
- .env.example shows the main external dependencies that materially affect architecture: Kafka broker, PostgreSQL/NeonDB, SMTP for email, JWT secrets, and Cloudinary for image storage.
12. Frontend architecture
- The React app is organized by role and concern: auth, citizen, staff, admin, notifications, shared components, and layout.
- useAuthStore manages authentication state, useNotifications connects to the notification stream, and api/api.js centralizes backend calls.
- This keeps the UI thin: stateful client behavior, but business workflow remains in backend services.
13. Key architectural boundary to draw
- Draw the system as three synchronous edges: frontend → complaint service, complaint service → ML service, frontend ↔ notification service.
- Then draw Kafka as the asynchronous hub feeding validation, assignment, audit, and notification consumers.
- PostgreSQL sits as the shared persistence layer, while SMTP and Cloudinary are external service integrations used by specific backend components.
Main entry points: App.jsx App shell · database.py PostgreSQL · kafka_producer.py Kafka bus · main.py Notify API
Components 22
Frontend
React UI with role-based portals and shared client state
- App shell · Main frontend composition and routing entrypoint
frontend/src/App.jsx - API client · Centralized backend request layer
frontend/src/api/api.js - Auth store · Persists login state and role context
frontend/src/hooks/useAuthStore.js - Notif hook · Connects the UI to live notification updates
frontend/src/hooks/useNotifications.js - Submit complaint · Citizen complaint intake flow
frontend/src/citizen/SubmitComplaint.jsx - Staff dashboard · Operational staff view for handling complaints
frontend/src/staff/StaffDashboard.jsx - Admin dashboard · Administrative oversight and management UI
frontend/src/admin/AdminDashboard.jsx - Notifications · User-facing notification inbox
frontend/src/notifications/Notifications.jsx
Core backend
Request/response APIs for complaints, auth, and ML enrichment
- Complaint API · Main orchestration API for complaint workflows
backend/complaint_service/main.py - Auth module · Token issuance and role enforcement shared by the API
backend/auth/router.py - ML API · Synchronous classification and priority inference service
backend/ml_service/main.py - Notify API · Notification delivery over HTTP and WebSocket
backend/notification_service/main.py - WS manager · Tracks live client connections for push updates
backend/notification_service/websocket_manager.py - Notif store · Notification record storage and retrieval
backend/notification_service/notification_store.py - Email sender · Sends notification emails
backend/notification_service/email_service.py
Event workers
Kafka consumer services reacting to complaint workflow events
- Validation worker · Re-checks complaint content from the event stream
backend/validation_service/kafka_consumer.py - Assignment worker · Routes validated complaints to departments
backend/assignment_service/kafka_consumer.py - Audit worker · Records complaint event history
backend/audit_service/kafka_consumer.py
Data layer
Shared PostgreSQL schema and persistence helpers
- PostgreSQL · Primary durable store for complaints and notifications
backend/db/database.py - Schema · Database structure and tables
backend/db/schema.sql
Connections 29
- App shell → API client: calls · UI uses the shared request layer
- App shell → Auth store: state · App reads authentication state
- App shell → Notif hook: subscribes · App enables live notification updates
- App shell → Submit complaint: routes · Citizen flow enters complaint submission
- App shell → Staff dashboard: routes · Staff flow enters operational dashboard
- App shell → Admin dashboard: routes · Admin flow enters oversight dashboard
- App shell → Notifications: routes · User opens notification inbox
- API client → Complaint API: http · Primary backend API calls
- API client → Notify API: http · Fetches notification history
- Notif hook → Notify API: websocket · Receives live notification pushes
- Complaint API → Auth module: auth · Issues and validates JWT-based access
- Complaint API → ML API: predict · Calls ML enrichment synchronously
- Complaint API → PostgreSQL: persist · Stores complaints and workflow state
- Complaint API → Kafka bus: publish · Emits workflow events downstream
- Auth module → PostgreSQL: users · Relies on persisted user and role data
- ML API → PostgreSQL: load models · Uses local persistence only indirectly through service runtime
- Kafka bus → Validation worker: consumes · Validation worker reacts to complaint events
- Kafka bus → Assignment worker: consumes · Assignment worker reacts to validated complaints
- Kafka bus → Audit worker: consumes · Audit worker records event history
- Kafka bus → Notify API: consumes · Notification service also reacts to events
- Notify API → WS manager: push · Maintains WebSocket delivery channel
- Notify API → Notif store: store · Persists notification records
- Notify API → Email sender: email · Sends email alerts for selected events
- Notif store → PostgreSQL: persist · Notification data is stored in PostgreSQL
- Validation worker → PostgreSQL: read/write · May validate against persisted complaint state
- Assignment worker → PostgreSQL: read/write · Assignment decisions can be persisted
- Audit worker → PostgreSQL: audit log · Stores event history snapshots
- Topics → Kafka bus: init · Creates the topic set used by the system
- Schema → PostgreSQL: defines · Schema describes the shared database structure