# guna-meda/egov-monorepo architecture

> Architecture diagram of the GitHub repository guna-meda/egov-monorepo, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/guna-meda/egov-monorepo
- Repository: https://github.com/guna-meda/egov-monorepo

## Overview

eGOV is a grievance-management monorepo: citizens submit complaints and view them on maps, while staff browse complaints and ward analytics. The intended enrichment stages classify complaint text and detect recurrence, but the README describes their connection through ingestion as planned; the enrichment function is currently a stub. The map and upload routes are visible in frontend source, and API/controller ownership is visible in sampled service files. Internal service, persistence, and API-client wiring not shown in the excerpts is represented only where documented; uncertain links are omitted.

Main entry points: [`frontend/src/routes.ts`](https://github.com/guna-meda/egov-monorepo/blob/main/frontend/src/routes.ts) (Web routes), [`ingestion-service/app/enrichment/pipeline.py`](https://github.com/guna-meda/egov-monorepo/blob/main/ingestion-service/app/enrichment/pipeline.py) (Enrichment pipeline), [`frontend/src/api/complaintApi.ts`](https://github.com/guna-meda/egov-monorepo/blob/main/frontend/src/api/complaintApi.ts) (Complaint API client), [`complaint-service/src/services/complaint.service.ts`](https://github.com/guna-meda/egov-monorepo/blob/main/complaint-service/src/services/complaint.service.ts) (Complaint operations)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web application"]
  node_frontend_routes["Web routes<br/>[routes.ts]"]
  node_grievance_action["Submission action"]
  node_map_loader["Map loader<br/>[mapLoader.ts]"]
  node_complaint_api_client["Complaint API client<br/>[complaintApi.ts]"]
  node_media_api_client["Media API client<br/>[mediaApi.ts]"]
end

subgraph group_complaints["Complaint service"]
  node_complaint_routes["Complaint routes"]
  node_complaint_controller["Complaint controller"]
  node_complaint_service["Complaint operations"]
  node_complaint_repository["Complaint repository"]
  node_complaint_store[("Complaint database")]
  node_media_routes["Media routes<br/>[media.routes.ts]"]
  node_media_service["Media operations<br/>[media.service.ts]"]
end

subgraph group_geospatial["GIS service"]
  node_gis_routes["GIS routes<br/>[gis.routes.ts]"]
  node_gis_controller["GIS controller<br/>[gis.controller.ts]"]
  node_gis_service["GIS operations<br/>[gis.service.ts]"]
  node_gis_repository["GIS repository<br/>[gis.repository.ts]"]
  node_boundary_store[("Boundary database")]
end

subgraph group_analysis["Complaint analysis"]
  node_classifier_api["Classification API<br/>[routes.py]"]
  node_predictor["Category predictor<br/>[predictor.py]"]
  node_recurrence_api["Recurrence API<br/>[recurrence.py]"]
  node_recurrence_service["Recurrence detection"]
end

subgraph group_enrichment["Planned enrichment"]
  node_ingestion_consumer["Kafka consumer<br/>[kafka_consumer.py]"]
  node_enrichment_pipeline["Enrichment pipeline<br/>[pipeline.py]"]
  node_enrichment_store[("Enrichment records")]
end

node_citizen(("Citizen"))
node_staff(("Staff"))
node_cloudinary[("Cloudinary")]
node_kafka["Kafka"]

node_citizen -->|"uses"| node_frontend_routes
node_staff -->|"uses"| node_frontend_routes
node_frontend_routes -->|"dispatches"| node_grievance_action
node_grievance_action -->|"submits through"| node_complaint_api_client
node_frontend_routes -->|"loads map"| node_map_loader
node_frontend_routes -->|"requests complaints"| node_complaint_api_client
node_complaint_api_client -->|"HTTP requests"| node_complaint_routes
node_complaint_routes -->|"dispatches"| node_complaint_controller
node_complaint_controller -->|"calls"| node_complaint_service
node_complaint_service -->|"uses"| node_complaint_repository
node_complaint_repository -->|"reads and writes"| node_complaint_store
node_media_api_client -->|"HTTP requests"| node_media_routes
node_media_routes -->|"dispatches"| node_media_service
node_media_service -->|"stores media"| node_cloudinary
node_map_loader -->|"requests boundaries"| node_gis_routes
node_gis_routes -->|"dispatches"| node_gis_controller
node_gis_controller -->|"calls"| node_gis_service
node_gis_service -->|"uses"| node_gis_repository
node_gis_repository -->|"reads and writes"| node_boundary_store
node_kafka -.->|"delivers events"| node_ingestion_consumer
node_complaint_service -.->|"publishes created event"| node_kafka
node_ingestion_consumer -.->|"passes payload"| node_enrichment_pipeline
node_enrichment_pipeline -.->|"requests classification"| node_classifier_api
node_enrichment_pipeline -.->|"requests recurrence"| node_recurrence_api
node_classifier_api -->|"calls"| node_predictor
node_recurrence_api -->|"calls"| node_recurrence_service
node_enrichment_pipeline -.->|"writes results"| node_enrichment_store
node_complaint_api_client -.->|"reads results"| node_enrichment_store

click node_frontend_routes "https://github.com/guna-meda/egov-monorepo/blob/main/frontend/src/routes.ts"
click node_grievance_action "https://github.com/guna-meda/egov-monorepo/blob/main/frontend/src/actions/grievanceUploadAction.ts"
click node_map_loader "https://github.com/guna-meda/egov-monorepo/blob/main/frontend/src/loaders/mapLoader.ts"
click node_complaint_api_client "https://github.com/guna-meda/egov-monorepo/blob/main/frontend/src/api/complaintApi.ts"
click node_media_api_client "https://github.com/guna-meda/egov-monorepo/blob/main/frontend/src/api/mediaApi.ts"
click node_complaint_routes "https://github.com/guna-meda/egov-monorepo/blob/main/complaint-service/src/routes/complaint.routes.ts"
click node_complaint_controller "https://github.com/guna-meda/egov-monorepo/blob/main/complaint-service/src/controllers/complaint.controller.ts"
click node_complaint_service "https://github.com/guna-meda/egov-monorepo/blob/main/complaint-service/src/services/complaint.service.ts"
click node_complaint_repository "https://github.com/guna-meda/egov-monorepo/blob/main/complaint-service/src/repositories/complaint.repository.ts"
click node_complaint_store "https://github.com/guna-meda/egov-monorepo/blob/main/packages/shared/src/db/schema/complaint.schema.ts"
click node_media_routes "https://github.com/guna-meda/egov-monorepo/blob/main/complaint-service/src/routes/media.routes.ts"
click node_media_service "https://github.com/guna-meda/egov-monorepo/blob/main/complaint-service/src/services/media.service.ts"
click node_gis_routes "https://github.com/guna-meda/egov-monorepo/blob/main/gis-service/src/routes/gis.routes.ts"
click node_gis_controller "https://github.com/guna-meda/egov-monorepo/blob/main/gis-service/src/controllers/gis.controller.ts"
click node_gis_service "https://github.com/guna-meda/egov-monorepo/blob/main/gis-service/src/services/gis.service.ts"
click node_gis_repository "https://github.com/guna-meda/egov-monorepo/blob/main/gis-service/src/repositories/gis.repository.ts"
click node_boundary_store "https://github.com/guna-meda/egov-monorepo/blob/main/gis-service/src/db/schema/boundary_layers.schema.ts"
click node_classifier_api "https://github.com/guna-meda/egov-monorepo/blob/main/classification-service/src/api/routes.py"
click node_predictor "https://github.com/guna-meda/egov-monorepo/blob/main/classification-service/src/classification/predictor.py"
click node_recurrence_api "https://github.com/guna-meda/egov-monorepo/blob/main/recurrence-service/app/api/v1/recurrence.py"
click node_recurrence_service "https://github.com/guna-meda/egov-monorepo/blob/main/recurrence-service/app/services/recurrence_service.py"
click node_ingestion_consumer "https://github.com/guna-meda/egov-monorepo/blob/main/ingestion-service/app/consumer/kafka_consumer.py"
click node_enrichment_pipeline "https://github.com/guna-meda/egov-monorepo/blob/main/ingestion-service/app/enrichment/pipeline.py"
click node_enrichment_store "https://github.com/guna-meda/egov-monorepo/blob/main/packages/shared/src/db/schema/ai_enrichment.schema.ts"

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_routes,node_grievance_action,node_map_loader,node_complaint_api_client,node_media_api_client toneBlue
class node_complaint_routes,node_complaint_controller,node_complaint_service,node_complaint_repository,node_complaint_store,node_media_routes,node_media_service,node_cloudinary toneAmber
class node_gis_routes,node_gis_controller,node_gis_service,node_gis_repository,node_boundary_store toneMint
class node_classifier_api,node_predictor,node_recurrence_api,node_recurrence_service toneRose
class node_ingestion_consumer,node_enrichment_pipeline,node_enrichment_store,node_citizen,node_staff,node_kafka toneIndigo
```

## Components

### Web application

- [Web routes](https://github.com/guna-meda/egov-monorepo/blob/main/frontend/src/routes.ts): `frontend/src/routes.ts`
- [Submission action](https://github.com/guna-meda/egov-monorepo/blob/main/frontend/src/actions/grievanceUploadAction.ts): `frontend/src/actions/grievanceUploadAction.ts`
- [Map loader](https://github.com/guna-meda/egov-monorepo/blob/main/frontend/src/loaders/mapLoader.ts): `frontend/src/loaders/mapLoader.ts`
- [Complaint API client](https://github.com/guna-meda/egov-monorepo/blob/main/frontend/src/api/complaintApi.ts): `frontend/src/api/complaintApi.ts`
- [Media API client](https://github.com/guna-meda/egov-monorepo/blob/main/frontend/src/api/mediaApi.ts): `frontend/src/api/mediaApi.ts`

### Complaint service

- [Complaint routes](https://github.com/guna-meda/egov-monorepo/blob/main/complaint-service/src/routes/complaint.routes.ts): `complaint-service/src/routes/complaint.routes.ts`
- [Complaint controller](https://github.com/guna-meda/egov-monorepo/blob/main/complaint-service/src/controllers/complaint.controller.ts): `complaint-service/src/controllers/complaint.controller.ts`
- [Complaint operations](https://github.com/guna-meda/egov-monorepo/blob/main/complaint-service/src/services/complaint.service.ts): `complaint-service/src/services/complaint.service.ts`
- [Complaint repository](https://github.com/guna-meda/egov-monorepo/blob/main/complaint-service/src/repositories/complaint.repository.ts): `complaint-service/src/repositories/complaint.repository.ts`
- [Complaint database](https://github.com/guna-meda/egov-monorepo/blob/main/packages/shared/src/db/schema/complaint.schema.ts): `packages/shared/src/db/schema/complaint.schema.ts`
- [Media routes](https://github.com/guna-meda/egov-monorepo/blob/main/complaint-service/src/routes/media.routes.ts): `complaint-service/src/routes/media.routes.ts`
- [Media operations](https://github.com/guna-meda/egov-monorepo/blob/main/complaint-service/src/services/media.service.ts): `complaint-service/src/services/media.service.ts`

### GIS service

- [GIS routes](https://github.com/guna-meda/egov-monorepo/blob/main/gis-service/src/routes/gis.routes.ts): `gis-service/src/routes/gis.routes.ts`
- [GIS controller](https://github.com/guna-meda/egov-monorepo/blob/main/gis-service/src/controllers/gis.controller.ts): `gis-service/src/controllers/gis.controller.ts`
- [GIS operations](https://github.com/guna-meda/egov-monorepo/blob/main/gis-service/src/services/gis.service.ts): `gis-service/src/services/gis.service.ts`
- [GIS repository](https://github.com/guna-meda/egov-monorepo/blob/main/gis-service/src/repositories/gis.repository.ts): `gis-service/src/repositories/gis.repository.ts`
- [Boundary database](https://github.com/guna-meda/egov-monorepo/blob/main/gis-service/src/db/schema/boundary_layers.schema.ts): `gis-service/src/db/schema/boundary_layers.schema.ts`

### Complaint analysis

- [Classification API](https://github.com/guna-meda/egov-monorepo/blob/main/classification-service/src/api/routes.py): `classification-service/src/api/routes.py`
- [Category predictor](https://github.com/guna-meda/egov-monorepo/blob/main/classification-service/src/classification/predictor.py): `classification-service/src/classification/predictor.py`
- [Recurrence API](https://github.com/guna-meda/egov-monorepo/blob/main/recurrence-service/app/api/v1/recurrence.py): `recurrence-service/app/api/v1/recurrence.py`
- [Recurrence detection](https://github.com/guna-meda/egov-monorepo/blob/main/recurrence-service/app/services/recurrence_service.py): `recurrence-service/app/services/recurrence_service.py`

### Planned enrichment

- [Kafka consumer](https://github.com/guna-meda/egov-monorepo/blob/main/ingestion-service/app/consumer/kafka_consumer.py): `ingestion-service/app/consumer/kafka_consumer.py`
- [Enrichment pipeline](https://github.com/guna-meda/egov-monorepo/blob/main/ingestion-service/app/enrichment/pipeline.py): `ingestion-service/app/enrichment/pipeline.py`
- [Enrichment records](https://github.com/guna-meda/egov-monorepo/blob/main/packages/shared/src/db/schema/ai_enrichment.schema.ts): `packages/shared/src/db/schema/ai_enrichment.schema.ts`

### Other components

- **Citizen**
- **Staff**
- **Cloudinary**
- **Kafka**

## Connections

- Citizen → Web routes: uses
- Staff → Web routes: uses
- Web routes → Submission action: dispatches
- Submission action → Complaint API client: submits through
- Web routes → Map loader: loads map
- Web routes → Complaint API client: requests complaints
- Complaint API client → Complaint routes: HTTP requests
- Complaint routes → Complaint controller: dispatches
- Complaint controller → Complaint operations: calls
- Complaint operations → Complaint repository: uses
- Complaint repository → Complaint database: reads and writes
- Media API client → Media routes: HTTP requests
- Media routes → Media operations: dispatches
- Media operations → Cloudinary: stores media
- Map loader → GIS routes: requests boundaries
- GIS routes → GIS controller: dispatches
- GIS controller → GIS operations: calls
- GIS operations → GIS repository: uses
- GIS repository → Boundary database: reads and writes
- Kafka → Kafka consumer: delivers events
- Complaint operations → Kafka: publishes created event
- Kafka consumer → Enrichment pipeline: passes payload
- Enrichment pipeline → Classification API: requests classification
- Enrichment pipeline → Recurrence API: requests recurrence
- Classification API → Category predictor: calls
- Recurrence API → Recurrence detection: calls
- Enrichment pipeline → Enrichment records: writes results
- Complaint API client → Enrichment records: reads results