# hemantmishra-lab/civicplus-microservices architecture

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

- Interactive diagram: https://gitdiagram.com/hemantmishra-lab/civicplus-microservices
- Repository: https://github.com/hemantmishra-lab/civicplus-microservices

## Overview

#### Purpose and entry points
CivicPlus is a civic grievance platform: citizens submit complaints; staff assign, update, escalate, notify, and analyze them. It is a Java 21/Spring Boot microservice system with a React/Vite client. External traffic enters the gateway; local full-stack startup is defined by `docker-compose.yml`. Primary runtime entry points are `api-gateway/src/main/java/com/hemant/civicplus/apigateway/ApiGatewayApplication.java` and `frontend/src/main.jsx`.

#### Edge, discovery, and configuration
Spring Cloud Gateway provides the single public REST perimeter, route selection, and CORS handling through `api-gateway/src/main/resources/application.yml` and `api-gateway/src/main/java/com/hemant/civicplus/apigateway/config/CorsConfig.java`. Eureka provides dynamic service registration/discovery from `discovery-server/src/main/java/com/hemant/civicplus/discoveryserver/DiscoveryServerApplication.java`. Central configuration is hosted by `config-server/src/main/java/com/hemant/civicplus/configserver/ConfigServerApplication.java`; service-local `application.yml` files remain deployment boundaries.

#### Identity and authorization
Auth owns registration, login, OTP/password recovery, refresh tokens, users, and roles, exposed by `auth-service/src/main/java/com/hemant/civicplus/authservice/controller/AuthController.java` and orchestrated in `auth-service/src/main/java/com/hemant/civicplus/authservice/application/AuthService.java`. Each protected service contains its own JWT filter/security configuration, making token validation decentralized; representative paths are `auth-service/src/main/java/com/hemant/civicplus/authservice/security/SecurityConfig.java` and `complaint-service/src/main/java/com/hemant/civicplus/complaintservice/security/JwtAuthFilter.java`.

#### Core complaint lifecycle
Complaint Service is the transactional system of record for creation, assignment, status changes, escalation, image references, and status history. Its API/application boundary is `complaint-service/src/main/java/com/hemant/civicplus/complaintservice/controller/ComplaintController.java` and `complaint-service/src/main/java/com/hemant/civicplus/complaintservice/application/ComplaintService.java`; persisted lifecycle data is modeled in `complaint-service/src/main/java/com/hemant/civicplus/complaintservice/domain/Complaint.java` and `complaint-service/src/main/java/com/hemant/civicplus/complaintservice/domain/StatusHistory.java`. It can make synchronous REST calls via its `RestTemplate` configuration, but downstream updates are primarily asynchronous.

#### Supporting business ownership
User profiles, including nearest-officer lookup and avatar metadata, belong to User Service: `user-service/src/main/java/com/hemant/civicplus/userservice/application/UserService.java` and `user-service/src/main/java/com/hemant/civicplus/userservice/domain/UserProfile.java`. Department Service owns departments and officers (`department-service/src/main/java/com/hemant/civicplus/departmentservice/application/DepartmentService.java`, `department-service/src/main/java/com/hemant/civicplus/departmentservice/domain/Officer.java`). Media Service isolates object upload/download behind `media-service/src/main/java/com/hemant/civicplus/mediaservice/controller/MediaController.java` and MinIO integration in `media-service/src/main/java/com/hemant/civicplus/mediaservice/config/MinioConfig.java`.

#### Event, notification, and analytics pipeline
Complaint Service publishes lifecycle events through `complaint-service/src/main/java/com/hemant/civicplus/complaintservice/kafka/ComplaintEventPublisher.java` to Kafka. Notification Service consumes them in `notification-service/src/main/java/com/hemant/civicplus/notificationservice/kafka/ComplaintEventListener.java`, persists notifications, and pushes real-time STOMP/WebSocket updates configured in `notification-service/src/main/java/com/hemant/civicplus/notificationservice/config/WebSocketConfig.java`. Analytics independently consumes the same event stream via `analytics-service/src/main/java/com/hemant/civicplus/analyticsservice/kafka/ComplaintEventConsumer.java`, maintains complaint statistics, and serves dashboard data through `analytics-service/src/main/java/com/hemant/civicplus/analyticsservice/controller/AnalyticsController.java`.

#### Client and infrastructure boundaries
The React SPA handles routes, authenticated views, API access, and Redux state at `frontend/src/App.jsx`, `frontend/src/api/axios.js`, and `frontend/src/store/index.js`. Docker Compose provisions services plus MySQL logical databases, Kafka, Redis, and MinIO; each state-owning backend uses Flyway migrations, e.g. `complaint-service/src/main/resources/db/migration/V1__init_complaint_schema.sql`. Containers are supplied per service, with a limited Kubernetes gateway manifest at `kubernetes/api-gateway.yaml`.

Main entry points: [`api-gateway/src/main/java/com/hemant/civicplus/apigateway/ApiGatewayApplication.java`](https://github.com/hemantmishra-lab/civicplus-microservices/blob/main/api-gateway/src/main/java/com/hemant/civicplus/apigateway/ApiGatewayApplication.java) (API Gateway), [`complaint-service/src/main/java/com/hemant/civicplus/complaintservice/application/ComplaintService.java`](https://github.com/hemantmishra-lab/civicplus-microservices/blob/main/complaint-service/src/main/java/com/hemant/civicplus/complaintservice/application/ComplaintService.java) (Complaint Service), [`docker-compose.yml`](https://github.com/hemantmishra-lab/civicplus-microservices/blob/main/docker-compose.yml) (Docker Compose), [`complaint-service/src/main/java/com/hemant/civicplus/complaintservice/controller/ComplaintController.java`](https://github.com/hemantmishra-lab/civicplus-microservices/blob/main/complaint-service/src/main/java/com/hemant/civicplus/complaintservice/controller/ComplaintController.java) (Complaint API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client & Edge"]
  node_frontend["React SPA<br/>Vite client<br/>[main.jsx]"]
  node_gateway{{"API Gateway<br/>Spring Cloud Gateway"}}
end

subgraph group_platform["Platform Services"]
  node_config["Config Server<br/>Spring Config"]
  node_discovery["Discovery Server<br/>Eureka"]
  node_auth["Auth Service<br/>identity service<br/>[AuthService.java]"]
  node_jwt["JWT Security<br/>per-service security<br/>[JwtAuthFilter.java]"]
  node_user["User Service<br/>profile service<br/>[UserService.java]"]
  node_department["Department Service<br/>organization service"]
  node_media["Media Service<br/>object media API"]
end

subgraph group_complaints["Complaint Lifecycle"]
  node_complaint_api["Complaint API<br/>REST controller"]
  node_complaint_app["Complaint Service<br/>application service"]
  node_complaint_data[("Complaint Data<br/>MySQL lifecycle schema")]
end

subgraph group_events["Events &amp; Insights"]
  node_kafka["Kafka<br/>event stream"]
  node_notification["Notification Service<br/>event consumer"]
  node_websocket["STOMP/WebSocket<br/>realtime delivery"]
  node_analytics["Analytics Service<br/>event consumer"]
  node_analytics_api["Analytics API<br/>dashboard REST API"]
end

subgraph group_infra["Runtime Infrastructure"]
  node_compose["Docker Compose<br/>local runtime<br/>[docker-compose.yml]"]
  node_minio[("MinIO<br/>object storage")]
end

node_compose -->|"starts"| node_gateway
node_compose -->|"provisions"| node_kafka
node_compose -->|"provisions"| node_minio
node_frontend -->|"REST API"| node_gateway
node_frontend -->|"realtime updates"| node_websocket
node_gateway -->|"routes"| node_auth
node_gateway -->|"routes"| node_complaint_api
node_gateway -->|"routes"| node_user
node_gateway -->|"routes"| node_department
node_gateway -->|"routes"| node_media
node_gateway -->|"routes"| node_analytics_api
node_config -.->|"central config"| node_gateway
node_config -.->|"central config"| node_complaint_app
node_discovery -.->|"service discovery"| node_gateway
node_discovery -.->|"registers"| node_complaint_app
node_auth -->|"issues tokens"| node_jwt
node_jwt -.->|"protects"| node_complaint_api
node_complaint_api -->|"lifecycle commands"| node_complaint_app
node_complaint_app -->|"persists"| node_complaint_data
node_complaint_app -.->|"profile lookup"| node_user
node_complaint_app -.->|"officer assignment"| node_department
node_media -->|"stores objects"| node_minio
node_complaint_app -->|"publishes lifecycle events"| node_kafka
node_kafka -->|"consumes events"| node_notification
node_notification -->|"pushes notifications"| node_websocket
node_kafka -->|"consumes events"| node_analytics
node_analytics -->|"serves statistics"| node_analytics_api

click node_compose "https://github.com/hemantmishra-lab/civicplus-microservices/blob/main/docker-compose.yml"
click node_frontend "https://github.com/hemantmishra-lab/civicplus-microservices/blob/main/frontend/src/main.jsx"
click node_gateway "https://github.com/hemantmishra-lab/civicplus-microservices/blob/main/api-gateway/src/main/java/com/hemant/civicplus/apigateway/ApiGatewayApplication.java"
click node_config "https://github.com/hemantmishra-lab/civicplus-microservices/blob/main/config-server/src/main/java/com/hemant/civicplus/configserver/ConfigServerApplication.java"
click node_discovery "https://github.com/hemantmishra-lab/civicplus-microservices/blob/main/discovery-server/src/main/java/com/hemant/civicplus/discoveryserver/DiscoveryServerApplication.java"
click node_auth "https://github.com/hemantmishra-lab/civicplus-microservices/blob/main/auth-service/src/main/java/com/hemant/civicplus/authservice/application/AuthService.java"
click node_jwt "https://github.com/hemantmishra-lab/civicplus-microservices/blob/main/complaint-service/src/main/java/com/hemant/civicplus/complaintservice/security/JwtAuthFilter.java"
click node_user "https://github.com/hemantmishra-lab/civicplus-microservices/blob/main/user-service/src/main/java/com/hemant/civicplus/userservice/application/UserService.java"
click node_department "https://github.com/hemantmishra-lab/civicplus-microservices/blob/main/department-service/src/main/java/com/hemant/civicplus/departmentservice/application/DepartmentService.java"
click node_media "https://github.com/hemantmishra-lab/civicplus-microservices/blob/main/media-service/src/main/java/com/hemant/civicplus/mediaservice/controller/MediaController.java"
click node_complaint_api "https://github.com/hemantmishra-lab/civicplus-microservices/blob/main/complaint-service/src/main/java/com/hemant/civicplus/complaintservice/controller/ComplaintController.java"
click node_complaint_app "https://github.com/hemantmishra-lab/civicplus-microservices/blob/main/complaint-service/src/main/java/com/hemant/civicplus/complaintservice/application/ComplaintService.java"
click node_complaint_data "https://github.com/hemantmishra-lab/civicplus-microservices/blob/main/complaint-service/src/main/resources/db/migration/V1__init_complaint_schema.sql"
click node_notification "https://github.com/hemantmishra-lab/civicplus-microservices/blob/main/notification-service/src/main/java/com/hemant/civicplus/notificationservice/kafka/ComplaintEventListener.java"
click node_websocket "https://github.com/hemantmishra-lab/civicplus-microservices/blob/main/notification-service/src/main/java/com/hemant/civicplus/notificationservice/config/WebSocketConfig.java"
click node_analytics "https://github.com/hemantmishra-lab/civicplus-microservices/blob/main/analytics-service/src/main/java/com/hemant/civicplus/analyticsservice/kafka/ComplaintEventConsumer.java"
click node_analytics_api "https://github.com/hemantmishra-lab/civicplus-microservices/blob/main/analytics-service/src/main/java/com/hemant/civicplus/analyticsservice/controller/AnalyticsController.java"

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,node_gateway toneBlue
class node_config,node_discovery,node_auth,node_jwt,node_user,node_department,node_media toneAmber
class node_complaint_api,node_complaint_app,node_complaint_data toneMint
class node_kafka,node_notification,node_websocket,node_analytics,node_analytics_api toneRose
class node_compose,node_minio toneIndigo
```

## Components

### Client & Edge

- [React SPA](https://github.com/hemantmishra-lab/civicplus-microservices/blob/main/frontend/src/main.jsx): Vite client · Authenticated views, API client, and Redux state. · `frontend/src/main.jsx`
- [API Gateway](https://github.com/hemantmishra-lab/civicplus-microservices/blob/main/api-gateway/src/main/java/com/hemant/civicplus/apigateway/ApiGatewayApplication.java): Spring Cloud Gateway · Public REST perimeter, routing, and CORS. · `api-gateway/src/main/java/com/hemant/civicplus/apigateway/ApiGatewayApplication.java`

### Platform Services

- [Config Server](https://github.com/hemantmishra-lab/civicplus-microservices/blob/main/config-server/src/main/java/com/hemant/civicplus/configserver/ConfigServerApplication.java): Spring Config · Central configuration host. · `config-server/src/main/java/com/hemant/civicplus/configserver/ConfigServerApplication.java`
- [Discovery Server](https://github.com/hemantmishra-lab/civicplus-microservices/blob/main/discovery-server/src/main/java/com/hemant/civicplus/discoveryserver/DiscoveryServerApplication.java): Eureka · Dynamic service registration and discovery. · `discovery-server/src/main/java/com/hemant/civicplus/discoveryserver/DiscoveryServerApplication.java`
- [Auth Service](https://github.com/hemantmishra-lab/civicplus-microservices/blob/main/auth-service/src/main/java/com/hemant/civicplus/authservice/application/AuthService.java): identity service · Registration, login, recovery, refresh tokens, users, and roles. · `auth-service/src/main/java/com/hemant/civicplus/authservice/application/AuthService.java`
- [JWT Security](https://github.com/hemantmishra-lab/civicplus-microservices/blob/main/complaint-service/src/main/java/com/hemant/civicplus/complaintservice/security/JwtAuthFilter.java): per-service security · Each protected service validates tokens locally. · `complaint-service/src/main/java/com/hemant/civicplus/complaintservice/security/JwtAuthFilter.java`
- [User Service](https://github.com/hemantmishra-lab/civicplus-microservices/blob/main/user-service/src/main/java/com/hemant/civicplus/userservice/application/UserService.java): profile service · Profiles, nearest-officer lookup, and avatar metadata. · `user-service/src/main/java/com/hemant/civicplus/userservice/application/UserService.java`
- [Department Service](https://github.com/hemantmishra-lab/civicplus-microservices/blob/main/department-service/src/main/java/com/hemant/civicplus/departmentservice/application/DepartmentService.java): organization service · Departments and officers. · `department-service/src/main/java/com/hemant/civicplus/departmentservice/application/DepartmentService.java`
- [Media Service](https://github.com/hemantmishra-lab/civicplus-microservices/blob/main/media-service/src/main/java/com/hemant/civicplus/mediaservice/controller/MediaController.java): object media API · Isolates upload and download operations. · `media-service/src/main/java/com/hemant/civicplus/mediaservice/controller/MediaController.java`

### Complaint Lifecycle

- [Complaint API](https://github.com/hemantmishra-lab/civicplus-microservices/blob/main/complaint-service/src/main/java/com/hemant/civicplus/complaintservice/controller/ComplaintController.java): REST controller · Complaint lifecycle API boundary. · `complaint-service/src/main/java/com/hemant/civicplus/complaintservice/controller/ComplaintController.java`
- [Complaint Service](https://github.com/hemantmishra-lab/civicplus-microservices/blob/main/complaint-service/src/main/java/com/hemant/civicplus/complaintservice/application/ComplaintService.java): application service · Creates, assigns, updates, escalates, and records lifecycle changes. · `complaint-service/src/main/java/com/hemant/civicplus/complaintservice/application/ComplaintService.java`
- [Complaint Data](https://github.com/hemantmishra-lab/civicplus-microservices/blob/main/complaint-service/src/main/resources/db/migration/V1__init_complaint_schema.sql): MySQL lifecycle schema · Complaints and status history, migrated with Flyway. · `complaint-service/src/main/resources/db/migration/V1__init_complaint_schema.sql`

### Events & Insights

- **Kafka**: event stream · Carries complaint lifecycle events.
- [Notification Service](https://github.com/hemantmishra-lab/civicplus-microservices/blob/main/notification-service/src/main/java/com/hemant/civicplus/notificationservice/kafka/ComplaintEventListener.java): event consumer · Persists notifications from complaint events. · `notification-service/src/main/java/com/hemant/civicplus/notificationservice/kafka/ComplaintEventListener.java`
- [STOMP/WebSocket](https://github.com/hemantmishra-lab/civicplus-microservices/blob/main/notification-service/src/main/java/com/hemant/civicplus/notificationservice/config/WebSocketConfig.java): realtime delivery · Pushes notification updates to clients. · `notification-service/src/main/java/com/hemant/civicplus/notificationservice/config/WebSocketConfig.java`
- [Analytics Service](https://github.com/hemantmishra-lab/civicplus-microservices/blob/main/analytics-service/src/main/java/com/hemant/civicplus/analyticsservice/kafka/ComplaintEventConsumer.java): event consumer · Maintains complaint statistics and dashboard data. · `analytics-service/src/main/java/com/hemant/civicplus/analyticsservice/kafka/ComplaintEventConsumer.java`
- [Analytics API](https://github.com/hemantmishra-lab/civicplus-microservices/blob/main/analytics-service/src/main/java/com/hemant/civicplus/analyticsservice/controller/AnalyticsController.java): dashboard REST API · `analytics-service/src/main/java/com/hemant/civicplus/analyticsservice/controller/AnalyticsController.java`

### Runtime Infrastructure

- [Docker Compose](https://github.com/hemantmishra-lab/civicplus-microservices/blob/main/docker-compose.yml): local runtime · Provisions the full local stack. · `docker-compose.yml`
- **MinIO**: object storage

## Connections

- Docker Compose → API Gateway: starts
- Docker Compose → Kafka: provisions
- Docker Compose → MinIO: provisions
- React SPA → API Gateway: REST API
- React SPA → STOMP/WebSocket: realtime updates
- API Gateway → Auth Service: routes
- API Gateway → Complaint API: routes
- API Gateway → User Service: routes
- API Gateway → Department Service: routes
- API Gateway → Media Service: routes
- API Gateway → Analytics API: routes
- Config Server → API Gateway: central config
- Config Server → Complaint Service: central config
- Discovery Server → API Gateway: service discovery
- Discovery Server → Complaint Service: registers
- Auth Service → JWT Security: issues tokens
- JWT Security → Complaint API: protects
- Complaint API → Complaint Service: lifecycle commands
- Complaint Service → Complaint Data: persists
- Complaint Service → User Service: profile lookup
- Complaint Service → Department Service: officer assignment
- Media Service → MinIO: stores objects
- Complaint Service → Kafka: publishes lifecycle events
- Kafka → Notification Service: consumes events
- Notification Service → STOMP/WebSocket: pushes notifications
- Kafka → Analytics Service: consumes events
- Analytics Service → Analytics API: serves statistics