# ranjeetj06/insighthub architecture

> Architecture diagram of the GitHub repository ranjeetj06/insighthub, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ranjeetj06/insighthub
- Repository: https://github.com/ranjeetj06/insighthub

## Overview

1. This repository is a small microservice-based system, not a single monolith. It contains three Spring Boot services under separate folders — `uploadClean`, `analysisInsights`, and `report` — plus a React frontend in `insighthub`. The services are connected primarily through RabbitMQ events, with MongoDB used for persisted analysis data and local file generation used for report outputs.

2. The user-facing entry point is the React app. Its components (`UploadSection`, `ResultSection`, `MainFrame`, etc.) suggest a simple flow: upload a dataset, trigger backend processing, and display results. `api.js` is the frontend integration point to the backend services.

3. `uploadClean` is the ingestion and cleaning boundary. It provides REST controllers for file upload and cleaning operations, stores or writes file content via `FileStorageService` / `FileWriteUtil`, applies CSV/Excel handling utilities, and publishes a `CleanedDataEvent`. This service is the first backend hop after the UI.

4. RabbitMQ is the central integration bus. Each backend service has its own `RabbitMQConfig`, and both `uploadClean` and `analysisInsights` include event model classes with the same `CleanedDataEvent` naming, indicating a producer/consumer handoff. This decouples file ingestion from downstream analysis and report creation.

5. `analysisInsights` is the analytics service. It consumes cleaned data through `InsightEventListener`, performs insight generation in `InsightServiceImpl`, and stores or retrieves analysis artifacts through `InsightResultRepository`. The model set includes summaries and correlations (`NumericSummary`, `CorrelationPair`, `TemporalCoverage`, `ValueCount`, `InsightResult`), so this service is responsible for converting cleaned data into structured findings.

6. `report` is the presentation/export service. It listens for events via `ReportEventListener` and provides a `ReportDownloadController` for retrieving generated outputs. Its utility classes (`GraphGenerator`, `CSVUtils`) and dependencies named in the README indicate this service turns analysis data into PDF/Excel reports with charts.

7. Each microservice follows the same internal layering pattern: controllers, service interfaces, service implementations, listeners, models, exceptions, and utility classes. That makes the diagram easy to draw as three parallel vertical stacks with a similar shape, but different domain responsibilities.

8. Persistence is service-scoped rather than shared. The only explicit repository in the tree is `InsightResultRepository` in `analysisInsights`, which aligns with the README’s MongoDB usage for analysis storage. The other services appear more transient or file-oriented, with `uploadClean` handling uploaded/cleaned files and `report` generating downloadable artifacts.

9. Error handling is standardized across services. Each backend module has `GlobalException`, `ResourceNotFoundException`, `ProcessFailureException`, and `ErrorResponse`, suggesting a consistent API error contract and a service-local exception boundary rather than cross-service exception propagation.

10. Infrastructure is intentionally split between local development and Kubernetes deployment. `docker-compose.yml` and the README show RabbitMQ and MongoDB as local dependencies, while the `k8s` directory contains manifests for namespaces, RBAC, persistent volumes, MongoDB, RabbitMQ, and each service deployment. That means the architecture includes both containerized runtime dependencies and orchestration manifests.

11. The likely end-to-end data flow is: user uploads CSV/Excel in the React app → `uploadClean` cleans and emits a message → `analysisInsights` consumes the cleaned dataset and computes insights → `report` generates a downloadable report from the analyzed data. The services are therefore separated by business stage rather than by UI/API tier.

12. For an architecture diagram, the most important boundaries are: client UI, ingestion/cleaning service, analytics service, report generation service, message broker, and data/storage backends. The key external technologies that materially shape the design are React, Spring Boot 3/Java 17, RabbitMQ, MongoDB, Docker/Docker Compose, and Kubernetes.

Main entry points: [`k8s/rabbitmq.yml`](https://github.com/ranjeetj06/insighthub/blob/master/k8s/rabbitmq.yml) (RabbitMQ), [`analysisInsights/src/main/java/com/insight/analysisinsights/services/serviceImpl/InsightServiceImpl.java`](https://github.com/ranjeetj06/insighthub/blob/master/analysisInsights/src/main/java/com/insight/analysisinsights/services/serviceImpl/InsightServiceImpl.java) (Insight Core), [`insighthub/src/components/MainFrame.jsx`](https://github.com/ranjeetj06/insighthub/blob/master/insighthub/src/components/MainFrame.jsx) (Main Frame), [`uploadClean/src/main/java/com/insight/uploadclean/service/ServiceImpl/CleaningServiceImpl.java`](https://github.com/ranjeetj06/insighthub/blob/master/uploadClean/src/main/java/com/insight/uploadclean/service/ServiceImpl/CleaningServiceImpl.java) (Cleaning Core)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_ui_app["App<br/>react shell<br/>[App.js]"]
  node_ui_main["Main Frame<br/>ui layout<br/>[MainFrame.jsx]"]
  node_ui_upload["Upload Section<br/>ui form<br/>[UploadSection.jsx]"]
  node_ui_result["Result Section<br/>ui display<br/>[ResultSection.jsx]"]
  node_ui_api["API Client<br/>frontend api<br/>[api.js]"]
end

subgraph group_upload["Upload Clean"]
  node_upload_ctrl["Upload API<br/>rest controller"]
  node_upload_clean_ctrl["Cleaning API<br/>rest controller"]
  node_upload_service["Cleaning Core<br/>service impl"]
  node_upload_store[("File Storage<br/>storage service")]
  node_upload_event["Cleaned Event<br/>event model"]
end

subgraph group_analysis["Analysis Insights"]
  node_analysis_listener["Insight Listener<br/>event listener"]
  node_analysis_service["Insight Core<br/>service impl"]
  node_analysis_repo[("Insight Repo<br/>mongo repository")]
  node_analysis_models["Insight Models<br/>domain models<br/>[InsightResult.java]"]
end

subgraph group_report["Report Service"]
  node_report_listener["Report Listener<br/>event listener"]
  node_report_controller["Download API<br/>rest controller"]
  node_report_service["Report Core<br/>service impl"]
  node_report_utils["Report Utils<br/>report tooling"]
end

subgraph group_infra["Infrastructure"]
  node_rabbitmq["RabbitMQ<br/>message broker<br/>[rabbitmq.yml]"]
  node_mongodb[("MongoDB<br/>database<br/>[mongodb.yml]")]
  node_k8s_upload["Upload Deploy<br/>k8s manifest<br/>[upload-clean.yml]"]
  node_k8s_analysis["Analysis Deploy<br/>k8s manifest"]
  node_k8s_report["Report Deploy<br/>k8s manifest<br/>[report.yml]"]
end

node_ui_app -->|"composes"| node_ui_main
node_ui_main -->|"hosts"| node_ui_upload
node_ui_main -->|"hosts"| node_ui_result
node_ui_upload -->|"calls"| node_ui_api
node_ui_result -->|"calls"| node_ui_api
node_ui_api -->|"REST"| node_upload_ctrl
node_upload_ctrl -->|"delegates"| node_upload_clean_ctrl
node_upload_clean_ctrl -->|"uses"| node_upload_service
node_upload_service -->|"writes"| node_upload_store
node_upload_service -->|"publishes"| node_upload_event
node_upload_event -->|"sends"| node_rabbitmq
node_rabbitmq -->|"delivers"| node_analysis_listener
node_analysis_listener -->|"triggers"| node_analysis_service
node_analysis_service -->|"produces"| node_analysis_models
node_analysis_service -->|"persists"| node_analysis_repo
node_analysis_repo -->|"stores"| node_mongodb
node_analysis_service -->|"publishes"| node_rabbitmq
node_rabbitmq -->|"delivers"| node_report_listener
node_report_listener -->|"triggers"| node_report_service
node_report_service -->|"renders"| node_report_utils
node_report_service -->|"exposes"| node_report_controller
node_k8s_upload -.->|"deploys"| node_upload_ctrl
node_k8s_analysis -.->|"deploys"| node_analysis_listener
node_k8s_report -.->|"deploys"| node_report_controller
node_k8s_upload -.->|"connects"| node_rabbitmq
node_k8s_analysis -.->|"connects"| node_mongodb
node_k8s_report -.->|"connects"| node_rabbitmq

click node_ui_app "https://github.com/ranjeetj06/insighthub/blob/master/insighthub/src/App.js"
click node_ui_main "https://github.com/ranjeetj06/insighthub/blob/master/insighthub/src/components/MainFrame.jsx"
click node_ui_upload "https://github.com/ranjeetj06/insighthub/blob/master/insighthub/src/components/UploadSection.jsx"
click node_ui_result "https://github.com/ranjeetj06/insighthub/blob/master/insighthub/src/components/ResultSection.jsx"
click node_ui_api "https://github.com/ranjeetj06/insighthub/blob/master/insighthub/src/api.js"
click node_upload_ctrl "https://github.com/ranjeetj06/insighthub/blob/master/uploadClean/src/main/java/com/insight/uploadclean/controllers/FileUploadController.java"
click node_upload_clean_ctrl "https://github.com/ranjeetj06/insighthub/blob/master/uploadClean/src/main/java/com/insight/uploadclean/controllers/CleaningController.java"
click node_upload_service "https://github.com/ranjeetj06/insighthub/blob/master/uploadClean/src/main/java/com/insight/uploadclean/service/ServiceImpl/CleaningServiceImpl.java"
click node_upload_store "https://github.com/ranjeetj06/insighthub/blob/master/uploadClean/src/main/java/com/insight/uploadclean/service/ServiceImpl/FileStorageServiceImpl.java"
click node_upload_event "https://github.com/ranjeetj06/insighthub/blob/master/uploadClean/src/main/java/com/insight/uploadclean/model/CleanedDataEvent.java"
click node_analysis_listener "https://github.com/ranjeetj06/insighthub/blob/master/analysisInsights/src/main/java/com/insight/analysisinsights/listener/InsightEventListener.java"
click node_analysis_service "https://github.com/ranjeetj06/insighthub/blob/master/analysisInsights/src/main/java/com/insight/analysisinsights/services/serviceImpl/InsightServiceImpl.java"
click node_analysis_repo "https://github.com/ranjeetj06/insighthub/blob/master/analysisInsights/src/main/java/com/insight/analysisinsights/repository/InsightResultRepository.java"
click node_analysis_models "https://github.com/ranjeetj06/insighthub/blob/master/analysisInsights/src/main/java/com/insight/analysisinsights/models/InsightResult.java"
click node_report_listener "https://github.com/ranjeetj06/insighthub/blob/master/report/src/main/java/com/insight/report/listener/ReportEventListener.java"
click node_report_controller "https://github.com/ranjeetj06/insighthub/blob/master/report/src/main/java/com/insight/report/controller/ReportDownloadController.java"
click node_report_service "https://github.com/ranjeetj06/insighthub/blob/master/report/src/main/java/com/insight/report/service/ServiceImpl/ReportServiceImpl.java"
click node_report_utils "https://github.com/ranjeetj06/insighthub/blob/master/report/src/main/java/com/insight/report/utils/GraphGenerator.java"
click node_rabbitmq "https://github.com/ranjeetj06/insighthub/blob/master/k8s/rabbitmq.yml"
click node_mongodb "https://github.com/ranjeetj06/insighthub/blob/master/k8s/mongodb.yml"
click node_k8s_upload "https://github.com/ranjeetj06/insighthub/blob/master/k8s/upload-clean.yml"
click node_k8s_analysis "https://github.com/ranjeetj06/insighthub/blob/master/k8s/analysis-insights.yml"
click node_k8s_report "https://github.com/ranjeetj06/insighthub/blob/master/k8s/report.yml"

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_ui_app,node_ui_main,node_ui_upload,node_ui_result,node_ui_api toneBlue
class node_upload_ctrl,node_upload_clean_ctrl,node_upload_service,node_upload_store,node_upload_event toneAmber
class node_analysis_listener,node_analysis_service,node_analysis_repo,node_analysis_models toneMint
class node_report_listener,node_report_controller,node_report_service,node_report_utils toneRose
class node_rabbitmq,node_mongodb,node_k8s_upload,node_k8s_analysis,node_k8s_report toneIndigo
```

## Components

### Frontend

React UI and API client

- [App](https://github.com/ranjeetj06/insighthub/blob/master/insighthub/src/App.js): react shell · Top-level React application composition · `insighthub/src/App.js`
- [Main Frame](https://github.com/ranjeetj06/insighthub/blob/master/insighthub/src/components/MainFrame.jsx): ui layout · Primary page workflow container · `insighthub/src/components/MainFrame.jsx`
- [Upload Section](https://github.com/ranjeetj06/insighthub/blob/master/insighthub/src/components/UploadSection.jsx): ui form · Dataset upload entry component · `insighthub/src/components/UploadSection.jsx`
- [Result Section](https://github.com/ranjeetj06/insighthub/blob/master/insighthub/src/components/ResultSection.jsx): ui display · Shows analysis and report outcomes · `insighthub/src/components/ResultSection.jsx`
- [API Client](https://github.com/ranjeetj06/insighthub/blob/master/insighthub/src/api.js): frontend api · Frontend integration point for backend calls · `insighthub/src/api.js`

### Upload Clean

Ingestion and cleaning microservice

- [Upload API](https://github.com/ranjeetj06/insighthub/blob/master/uploadClean/src/main/java/com/insight/uploadclean/controllers/FileUploadController.java): rest controller · Handles file upload requests · `uploadClean/src/main/java/com/insight/uploadclean/controllers/FileUploadController.java`
- [Cleaning API](https://github.com/ranjeetj06/insighthub/blob/master/uploadClean/src/main/java/com/insight/uploadclean/controllers/CleaningController.java): rest controller · Exposes cleaning operations · `uploadClean/src/main/java/com/insight/uploadclean/controllers/CleaningController.java`
- [Cleaning Core](https://github.com/ranjeetj06/insighthub/blob/master/uploadClean/src/main/java/com/insight/uploadclean/service/ServiceImpl/CleaningServiceImpl.java): service impl · Parses, cleans, and emits downstream events · `uploadClean/src/main/java/com/insight/uploadclean/service/ServiceImpl/CleaningServiceImpl.java`
- [File Storage](https://github.com/ranjeetj06/insighthub/blob/master/uploadClean/src/main/java/com/insight/uploadclean/service/ServiceImpl/FileStorageServiceImpl.java): storage service · Persists uploaded and cleaned files locally · `uploadClean/src/main/java/com/insight/uploadclean/service/ServiceImpl/FileStorageServiceImpl.java`
- [Cleaned Event](https://github.com/ranjeetj06/insighthub/blob/master/uploadClean/src/main/java/com/insight/uploadclean/model/CleanedDataEvent.java): event model · Message published after cleaning completes · `uploadClean/src/main/java/com/insight/uploadclean/model/CleanedDataEvent.java`

### Analysis Insights

Analytics and persistence microservice

- [Insight Listener](https://github.com/ranjeetj06/insighthub/blob/master/analysisInsights/src/main/java/com/insight/analysisinsights/listener/InsightEventListener.java): event listener · Consumes cleaned-data messages from RabbitMQ · `analysisInsights/src/main/java/com/insight/analysisinsights/listener/InsightEventListener.java`
- [Insight Core](https://github.com/ranjeetj06/insighthub/blob/master/analysisInsights/src/main/java/com/insight/analysisinsights/services/serviceImpl/InsightServiceImpl.java): service impl · Generates summaries, correlations, and findings · `analysisInsights/src/main/java/com/insight/analysisinsights/services/serviceImpl/InsightServiceImpl.java`
- [Insight Repo](https://github.com/ranjeetj06/insighthub/blob/master/analysisInsights/src/main/java/com/insight/analysisinsights/repository/InsightResultRepository.java): mongo repository · Persists and retrieves analysis results · `analysisInsights/src/main/java/com/insight/analysisinsights/repository/InsightResultRepository.java`
- [Insight Models](https://github.com/ranjeetj06/insighthub/blob/master/analysisInsights/src/main/java/com/insight/analysisinsights/models/InsightResult.java): domain models · Structured analytics outputs and supporting metrics · `analysisInsights/src/main/java/com/insight/analysisinsights/models/InsightResult.java`

### Report Service

Report generation and download microservice

- [Report Listener](https://github.com/ranjeetj06/insighthub/blob/master/report/src/main/java/com/insight/report/listener/ReportEventListener.java): event listener · Receives analysis-related events for report creation · `report/src/main/java/com/insight/report/listener/ReportEventListener.java`
- [Download API](https://github.com/ranjeetj06/insighthub/blob/master/report/src/main/java/com/insight/report/controller/ReportDownloadController.java): rest controller · Serves generated report downloads · `report/src/main/java/com/insight/report/controller/ReportDownloadController.java`
- [Report Core](https://github.com/ranjeetj06/insighthub/blob/master/report/src/main/java/com/insight/report/service/ServiceImpl/ReportServiceImpl.java): service impl · Builds downloadable report artifacts · `report/src/main/java/com/insight/report/service/ServiceImpl/ReportServiceImpl.java`
- [Report Utils](https://github.com/ranjeetj06/insighthub/blob/master/report/src/main/java/com/insight/report/utils/GraphGenerator.java): report tooling · Generates charts and CSV output for reports · `report/src/main/java/com/insight/report/utils/GraphGenerator.java`

### Infrastructure

Broker, database, and deployment manifests

- [RabbitMQ](https://github.com/ranjeetj06/insighthub/blob/master/k8s/rabbitmq.yml): message broker · Asynchronous handoff between microservices · `k8s/rabbitmq.yml`
- [MongoDB](https://github.com/ranjeetj06/insighthub/blob/master/k8s/mongodb.yml): database · Persistent store for analysis data · `k8s/mongodb.yml`
- [Upload Deploy](https://github.com/ranjeetj06/insighthub/blob/master/k8s/upload-clean.yml): k8s manifest · Kubernetes deployment manifest for upload-clean · `k8s/upload-clean.yml`
- [Analysis Deploy](https://github.com/ranjeetj06/insighthub/blob/master/k8s/analysis-insights.yml): k8s manifest · Kubernetes deployment manifest for analysis-insights · `k8s/analysis-insights.yml`
- [Report Deploy](https://github.com/ranjeetj06/insighthub/blob/master/k8s/report.yml): k8s manifest · Kubernetes deployment manifest for report · `k8s/report.yml`

## Connections

- App → Main Frame: composes · App assembles the main page shell
- Main Frame → Upload Section: hosts · Main frame contains upload flow
- Main Frame → Result Section: hosts · Main frame contains result display
- Upload Section → API Client: calls · Upload UI invokes backend API client
- Result Section → API Client: calls · Results UI fetches backend data
- API Client → Upload API: REST · Frontend starts the ingestion workflow
- Upload API → Cleaning API: delegates · Upload controller forwards cleaning actions
- Cleaning API → Cleaning Core: uses · Controller delegates to cleaning logic
- Cleaning Core → File Storage: writes · Cleaned or uploaded files are stored locally
- Cleaning Core → Cleaned Event: publishes · Cleaning completion emits a broker event
- Cleaned Event → RabbitMQ: sends · RabbitMQ carries the cleaned dataset message
- RabbitMQ → Insight Listener: delivers · Analytics service consumes the cleaned event
- Insight Listener → Insight Core: triggers · Listener hands off to insight generation
- Insight Core → Insight Models: produces · Service creates structured insight objects
- Insight Core → Insight Repo: persists · Generated insights are stored in MongoDB
- Insight Repo → MongoDB: stores · Repository writes to the database backend
- Insight Core → RabbitMQ: publishes · Analysis results can be forwarded downstream
- RabbitMQ → Report Listener: delivers · Report service consumes analysis-related events
- Report Listener → Report Core: triggers · Listener starts report assembly
- Report Core → Report Utils: renders · Utilities generate charts and tabular output
- Report Core → Download API: exposes · Controller serves generated reports for download
- Upload Deploy → Upload API: deploys · Kubernetes manifest defines the upload-clean service
- Analysis Deploy → Insight Listener: deploys · Kubernetes manifest defines the analysis-insights service
- Report Deploy → Download API: deploys · Kubernetes manifest defines the report service
- Upload Deploy → RabbitMQ: connects · Upload service depends on RabbitMQ
- Analysis Deploy → MongoDB: connects · Analysis service depends on MongoDB
- Report Deploy → RabbitMQ: connects · Report service depends on RabbitMQ
