# kailasss2k05/event-driven-complaint-system architecture

> Architecture diagram of the GitHub repository kailasss2k05/event-driven-complaint-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kailasss2k05/event-driven-complaint-system
- Repository: https://github.com/kailasss2k05/event-driven-complaint-system

## Overview

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: [`frontend/src/App.jsx`](https://github.com/kailasss2k05/event-driven-complaint-system/blob/main/frontend/src/App.jsx) (App shell), [`backend/db/database.py`](https://github.com/kailasss2k05/event-driven-complaint-system/blob/main/backend/db/database.py) (PostgreSQL), [`backend/complaint_service/kafka_producer.py`](https://github.com/kailasss2k05/event-driven-complaint-system/blob/main/backend/complaint_service/kafka_producer.py) (Kafka bus), [`backend/notification_service/main.py`](https://github.com/kailasss2k05/event-driven-complaint-system/blob/main/backend/notification_service/main.py) (Notify API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_frontend_app["App shell<br/>react shell<br/>[App.jsx]"]
  node_frontend_api["API client<br/>http client<br/>[api.js]"]
  node_frontend_auth_store["Auth store<br/>client state<br/>[useAuthStore.js]"]
  node_frontend_notifications_hook["Notif hook<br/>websocket hook"]
  node_frontend_submit_complaint["Submit complaint<br/>citizen portal"]
  node_frontend_staff_dashboard["Staff dashboard<br/>staff portal<br/>[StaffDashboard.jsx]"]
  node_frontend_admin_dashboard["Admin dashboard<br/>admin portal<br/>[AdminDashboard.jsx]"]
  node_frontend_notifications_ui["Notifications<br/>ui panel<br/>[Notifications.jsx]"]
end

subgraph group_core_backend["Core backend"]
  node_complaint_service["Complaint API<br/>fastapi service<br/>[main.py]"]
  node_auth_module["Auth module<br/>jwt/oauth2<br/>[router.py]"]
  node_ml_service["ML API<br/>fastapi service<br/>[main.py]"]
  node_notification_service["Notify API<br/>fastapi/ws service<br/>[main.py]"]
  node_notif_ws["WS manager<br/>websocket hub"]
  node_notif_store["Notif store<br/>persistence"]
  node_notif_email["Email sender<br/>smtp adapter<br/>[email_service.py]"]
end

subgraph group_event_backend["Event workers"]
  node_validation_consumer["Validation worker<br/>kafka consumer<br/>[kafka_consumer.py]"]
  node_assignment_consumer["Assignment worker<br/>kafka consumer<br/>[kafka_consumer.py]"]
  node_audit_consumer["Audit worker<br/>kafka consumer<br/>[kafka_consumer.py]"]
end

subgraph group_data["Data layer"]
  node_database[("PostgreSQL<br/>shared db<br/>[database.py]")]
  node_schema["Schema<br/>[schema.sql]"]
end

subgraph group_infra["Infra"]
  node_topic_bootstrap["Topics<br/>kafka setup<br/>[create-topics.sh]"]
  node_kafka_bus["Kafka bus<br/>event backbone<br/>[kafka_producer.py]"]
end

node_frontend_app -->|"calls"| node_frontend_api
node_frontend_app -->|"state"| node_frontend_auth_store
node_frontend_app -->|"subscribes"| node_frontend_notifications_hook
node_frontend_app -->|"routes"| node_frontend_submit_complaint
node_frontend_app -->|"routes"| node_frontend_staff_dashboard
node_frontend_app -->|"routes"| node_frontend_admin_dashboard
node_frontend_app -->|"routes"| node_frontend_notifications_ui
node_frontend_api -->|"http"| node_complaint_service
node_frontend_api -->|"http"| node_notification_service
node_frontend_notifications_hook -->|"websocket"| node_notification_service
node_complaint_service -->|"auth"| node_auth_module
node_complaint_service -->|"predict"| node_ml_service
node_complaint_service -->|"persist"| node_database
node_complaint_service -->|"publish"| node_kafka_bus
node_auth_module -->|"users"| node_database
node_ml_service -.->|"load models"| node_database
node_kafka_bus -->|"consumes"| node_validation_consumer
node_kafka_bus -->|"consumes"| node_assignment_consumer
node_kafka_bus -->|"consumes"| node_audit_consumer
node_kafka_bus -->|"consumes"| node_notification_service
node_notification_service -->|"push"| node_notif_ws
node_notification_service -->|"store"| node_notif_store
node_notification_service -->|"email"| node_notif_email
node_notif_store -->|"persist"| node_database
node_validation_consumer -->|"read/write"| node_database
node_assignment_consumer -->|"read/write"| node_database
node_audit_consumer -->|"audit log"| node_database
node_topic_bootstrap -->|"init"| node_kafka_bus
node_schema -->|"defines"| node_database

click node_frontend_app "https://github.com/kailasss2k05/event-driven-complaint-system/blob/main/frontend/src/App.jsx"
click node_frontend_api "https://github.com/kailasss2k05/event-driven-complaint-system/blob/main/frontend/src/api/api.js"
click node_frontend_auth_store "https://github.com/kailasss2k05/event-driven-complaint-system/blob/main/frontend/src/hooks/useAuthStore.js"
click node_frontend_notifications_hook "https://github.com/kailasss2k05/event-driven-complaint-system/blob/main/frontend/src/hooks/useNotifications.js"
click node_frontend_submit_complaint "https://github.com/kailasss2k05/event-driven-complaint-system/blob/main/frontend/src/citizen/SubmitComplaint.jsx"
click node_frontend_staff_dashboard "https://github.com/kailasss2k05/event-driven-complaint-system/blob/main/frontend/src/staff/StaffDashboard.jsx"
click node_frontend_admin_dashboard "https://github.com/kailasss2k05/event-driven-complaint-system/blob/main/frontend/src/admin/AdminDashboard.jsx"
click node_frontend_notifications_ui "https://github.com/kailasss2k05/event-driven-complaint-system/blob/main/frontend/src/notifications/Notifications.jsx"
click node_complaint_service "https://github.com/kailasss2k05/event-driven-complaint-system/blob/main/backend/complaint_service/main.py"
click node_auth_module "https://github.com/kailasss2k05/event-driven-complaint-system/blob/main/backend/auth/router.py"
click node_ml_service "https://github.com/kailasss2k05/event-driven-complaint-system/blob/main/backend/ml_service/main.py"
click node_notification_service "https://github.com/kailasss2k05/event-driven-complaint-system/blob/main/backend/notification_service/main.py"
click node_notif_ws "https://github.com/kailasss2k05/event-driven-complaint-system/blob/main/backend/notification_service/websocket_manager.py"
click node_notif_store "https://github.com/kailasss2k05/event-driven-complaint-system/blob/main/backend/notification_service/notification_store.py"
click node_notif_email "https://github.com/kailasss2k05/event-driven-complaint-system/blob/main/backend/notification_service/email_service.py"
click node_validation_consumer "https://github.com/kailasss2k05/event-driven-complaint-system/blob/main/backend/validation_service/kafka_consumer.py"
click node_assignment_consumer "https://github.com/kailasss2k05/event-driven-complaint-system/blob/main/backend/assignment_service/kafka_consumer.py"
click node_audit_consumer "https://github.com/kailasss2k05/event-driven-complaint-system/blob/main/backend/audit_service/kafka_consumer.py"
click node_database "https://github.com/kailasss2k05/event-driven-complaint-system/blob/main/backend/db/database.py"
click node_schema "https://github.com/kailasss2k05/event-driven-complaint-system/blob/main/backend/db/schema.sql"
click node_topic_bootstrap "https://github.com/kailasss2k05/event-driven-complaint-system/blob/main/kafka/create-topics.sh"
click node_kafka_bus "https://github.com/kailasss2k05/event-driven-complaint-system/blob/main/backend/complaint_service/kafka_producer.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_frontend_app,node_frontend_api,node_frontend_auth_store,node_frontend_notifications_hook,node_frontend_submit_complaint,node_frontend_staff_dashboard,node_frontend_admin_dashboard,node_frontend_notifications_ui toneBlue
class node_complaint_service,node_auth_module,node_ml_service,node_notification_service,node_notif_ws,node_notif_store,node_notif_email toneAmber
class node_validation_consumer,node_assignment_consumer,node_audit_consumer toneMint
class node_database,node_schema toneRose
class node_topic_bootstrap,node_kafka_bus toneIndigo
```

## Components

### Frontend

React UI with role-based portals and shared client state

- [App shell](https://github.com/kailasss2k05/event-driven-complaint-system/blob/main/frontend/src/App.jsx): react shell · Main frontend composition and routing entrypoint · `frontend/src/App.jsx`
- [API client](https://github.com/kailasss2k05/event-driven-complaint-system/blob/main/frontend/src/api/api.js): http client · Centralized backend request layer · `frontend/src/api/api.js`
- [Auth store](https://github.com/kailasss2k05/event-driven-complaint-system/blob/main/frontend/src/hooks/useAuthStore.js): client state · Persists login state and role context · `frontend/src/hooks/useAuthStore.js`
- [Notif hook](https://github.com/kailasss2k05/event-driven-complaint-system/blob/main/frontend/src/hooks/useNotifications.js): websocket hook · Connects the UI to live notification updates · `frontend/src/hooks/useNotifications.js`
- [Submit complaint](https://github.com/kailasss2k05/event-driven-complaint-system/blob/main/frontend/src/citizen/SubmitComplaint.jsx): citizen portal · Citizen complaint intake flow · `frontend/src/citizen/SubmitComplaint.jsx`
- [Staff dashboard](https://github.com/kailasss2k05/event-driven-complaint-system/blob/main/frontend/src/staff/StaffDashboard.jsx): staff portal · Operational staff view for handling complaints · `frontend/src/staff/StaffDashboard.jsx`
- [Admin dashboard](https://github.com/kailasss2k05/event-driven-complaint-system/blob/main/frontend/src/admin/AdminDashboard.jsx): admin portal · Administrative oversight and management UI · `frontend/src/admin/AdminDashboard.jsx`
- [Notifications](https://github.com/kailasss2k05/event-driven-complaint-system/blob/main/frontend/src/notifications/Notifications.jsx): ui panel · User-facing notification inbox · `frontend/src/notifications/Notifications.jsx`

### Core backend

Request/response APIs for complaints, auth, and ML enrichment

- [Complaint API](https://github.com/kailasss2k05/event-driven-complaint-system/blob/main/backend/complaint_service/main.py): fastapi service · Main orchestration API for complaint workflows · `backend/complaint_service/main.py`
- [Auth module](https://github.com/kailasss2k05/event-driven-complaint-system/blob/main/backend/auth/router.py): jwt/oauth2 · Token issuance and role enforcement shared by the API · `backend/auth/router.py`
- [ML API](https://github.com/kailasss2k05/event-driven-complaint-system/blob/main/backend/ml_service/main.py): fastapi service · Synchronous classification and priority inference service · `backend/ml_service/main.py`
- [Notify API](https://github.com/kailasss2k05/event-driven-complaint-system/blob/main/backend/notification_service/main.py): fastapi/ws service · Notification delivery over HTTP and WebSocket · `backend/notification_service/main.py`
- [WS manager](https://github.com/kailasss2k05/event-driven-complaint-system/blob/main/backend/notification_service/websocket_manager.py): websocket hub · Tracks live client connections for push updates · `backend/notification_service/websocket_manager.py`
- [Notif store](https://github.com/kailasss2k05/event-driven-complaint-system/blob/main/backend/notification_service/notification_store.py): persistence · Notification record storage and retrieval · `backend/notification_service/notification_store.py`
- [Email sender](https://github.com/kailasss2k05/event-driven-complaint-system/blob/main/backend/notification_service/email_service.py): smtp adapter · Sends notification emails · `backend/notification_service/email_service.py`

### Event workers

Kafka consumer services reacting to complaint workflow events

- [Validation worker](https://github.com/kailasss2k05/event-driven-complaint-system/blob/main/backend/validation_service/kafka_consumer.py): kafka consumer · Re-checks complaint content from the event stream · `backend/validation_service/kafka_consumer.py`
- [Assignment worker](https://github.com/kailasss2k05/event-driven-complaint-system/blob/main/backend/assignment_service/kafka_consumer.py): kafka consumer · Routes validated complaints to departments · `backend/assignment_service/kafka_consumer.py`
- [Audit worker](https://github.com/kailasss2k05/event-driven-complaint-system/blob/main/backend/audit_service/kafka_consumer.py): kafka consumer · Records complaint event history · `backend/audit_service/kafka_consumer.py`

### Data layer

Shared PostgreSQL schema and persistence helpers

- [PostgreSQL](https://github.com/kailasss2k05/event-driven-complaint-system/blob/main/backend/db/database.py): shared db · Primary durable store for complaints and notifications · `backend/db/database.py`
- [Schema](https://github.com/kailasss2k05/event-driven-complaint-system/blob/main/backend/db/schema.sql): sql schema · Database structure and tables · `backend/db/schema.sql`

### Infra

Kafka topic bootstrap and runtime integration

- [Topics](https://github.com/kailasss2k05/event-driven-complaint-system/blob/main/kafka/create-topics.sh): kafka setup · Initializes the event topics used by the workflow · `kafka/create-topics.sh`
- [Kafka bus](https://github.com/kailasss2k05/event-driven-complaint-system/blob/main/backend/complaint_service/kafka_producer.py): event backbone · Asynchronous backbone for complaint workflow events · `backend/complaint_service/kafka_producer.py`

## Connections

- 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
