# bunnycoder1999/ccms-monitor architecture

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

- Interactive diagram: https://gitdiagram.com/bunnycoder1999/ccms-monitor
- Repository: https://github.com/bunnycoder1999/ccms-monitor

## Overview

#### Purpose and topology
This repository is a CCMS meter-monitoring system: a Next.js operator UI, a Spring Boot backend, and Kafka-based asynchronous meter-reading transport. The backend integrates with configurable service providers, including Jio, to obtain meter identities/readings, persist them, expose REST APIs, and publish/consume reading events.

#### Entry points and deployment
- Backend application entry point: `ccms_monitor/src/main/java/com/example/ccms_monitor/CcmsApplication.java`.
- Frontend is a Next.js App Router application rooted at `ccms-frontend/src/app/layout.tsx`; unauthenticated entry is `ccms-frontend/src/app/login/page.tsx`.
- Service/container orchestration is represented by root `compose.yaml`, `ccms_monitor/compose.yaml`, `ccms-frontend/compose.yaml`, and Kafka-specific `kafka-docker/docker-compose.yml`.
- Both application tiers provide Docker build definitions: `ccms_monitor/Dockerfile` and `ccms-frontend/Dockerfile`.

#### Backend API and integration boundary
Spring MVC controllers form the HTTP boundary for meter serial numbers, readings, Jio integration, and related read operations:
`ccms_monitor/src/main/java/com/example/ccms_monitor/controller/MeterSerialNoController.java`,
`ccms_monitor/src/main/java/com/example/ccms_monitor/controller/MeterReadingController.java`,
and `ccms_monitor/src/main/java/com/example/ccms_monitor/controller/JioController.java`.
Service-layer orchestration separates provider/API operations from transport: `service/JioService.java`, `service/DataFetchService.java`, and `service/MeterService.java`.

#### Provider authentication and scheduled ingestion
Provider definitions are configuration-driven through `config/ServiceProvider.java` and `config/ServiceProviderConfig.java`. Authentication handling is isolated in `service/AuthService.java`, backed by `config/AuthProperties.java`. Periodic retrieval is initiated by `scheduler/ScheduledTasks.java`, which drives the fetch-to-processing pipeline rather than requiring UI-triggered ingestion.

#### Persistence model
Meter serial numbers and readings are distinct domain entities:
`model/MeterSerialNo.java` and `model/MeterReading.java`.
Their repositories, `repository/MeterSerialNoRepo.java` and `repository/MeterReadingRepo.java`, define the database boundary used by services/controllers. Backend runtime configuration, including infrastructure connection settings, is centralized in `src/main/resources/application.properties`.

#### Kafka event pipeline
Kafka decouples reading production from downstream consumption. `kafka/KafkaProducerService.java` publishes `kafka/dto/MeterReadingEvent.java`; `kafka/KafkaConsumerService.java` receives events for processing/persistence workflows. Broker/client setup belongs in `config/KafkaConfig.java`. Kafka is external infrastructure supplied by `kafka-docker/docker-compose.yml`.

#### Frontend application flow
Authenticated navigation and shared shell are defined in `ccms-frontend/src/app/(authenticated)/layout.tsx`, with operational pages for the dashboard, meter IDs, and meter readings:
`dashboard/page.tsx`, `meter-ids/page.tsx`, and `meter-readings/page.tsx`.
The UI fetches backend data through service modules—`services/axiosInstance.ts`, `services/meterService.ts`, and `services/meterReadingService.ts`—rather than directly from pages.

#### Client state and presentation boundaries
React Query is installed at the app boundary through `providers/QueryProvider.tsx`; resource-specific query behavior is encapsulated in `hooks/useMeterQueries.ts` and `hooks/useMeterReadingQueries.ts`. Tables and fetch controls (`components/MeterTable.tsx`, `components/MeterReadingTable.tsx`, `components/MeterFetchForm.tsx`) render and trigger operational workflows. `providers/ThemeProvider.tsx` and `components/app-sidebar.tsx` provide cross-cutting UI state/navigation.

Main entry points: [`ccms_monitor/src/main/java/com/example/ccms_monitor/controller/MeterReadingController.java`](https://github.com/bunnycoder1999/ccms-monitor/blob/main/ccms_monitor/src/main/java/com/example/ccms_monitor/controller/MeterReadingController.java) (Meter REST controllers), [`kafka-docker/docker-compose.yml`](https://github.com/bunnycoder1999/ccms-monitor/blob/main/kafka-docker/docker-compose.yml) (Kafka broker), [`ccms-frontend/src/app/layout.tsx`](https://github.com/bunnycoder1999/ccms-monitor/blob/main/ccms-frontend/src/app/layout.tsx) (App shell & login), [`compose.yaml`](https://github.com/bunnycoder1999/ccms-monitor/blob/main/compose.yaml) (Service orchestration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Next.js Operator UI"]
  node_ui_app["App shell &amp; login<br/>Next.js routes<br/>[layout.tsx]"]
  node_ui_pages["Operations pages<br/>Next.js pages"]
  node_ui_queries["Query hooks<br/>React Query"]
  node_ui_api["Backend API client<br/>frontend services"]
  node_ui_components["Meter operations UI<br/>React components"]
end

subgraph group_backend["Spring Boot Backend"]
  node_backend_app["CCMS application<br/>Spring Boot entry"]
  node_api["Meter REST controllers<br/>Spring MVC"]
  node_services["Meter &amp; provider services<br/>service layer"]
  node_provider_config["Provider configuration<br/>provider registry"]
  node_auth["Provider authentication<br/>auth service"]
  node_scheduler["Scheduled ingestion<br/>Spring scheduler"]
  node_domain["Meter domain<br/>JPA entities"]
  node_repositories[("Meter repositories<br/>Spring Data")]
end

subgraph group_events["Kafka Transport"]
  node_producer["Reading event producer<br/>Kafka producer"]
  node_broker["Kafka broker<br/>event broker<br/>[docker-compose.yml]"]
  node_consumer["Reading event consumer<br/>Kafka consumer"]
end

subgraph group_infra["Deployment &amp; Infrastructure"]
  node_database[("Application database<br/>persistent store")]
  node_compose{{"Service orchestration<br/>Docker Compose<br/>[compose.yaml]"}}
  node_containers{{"Application containers<br/>Docker builds"}}
end

node_ui_app -->|"routes users to"| node_ui_pages
node_ui_app -->|"installs query provider"| node_ui_queries
node_ui_pages -->|"renders"| node_ui_components
node_ui_components -->|"uses"| node_ui_queries
node_ui_queries -->|"fetches through"| node_ui_api
node_ui_api -->|"REST requests"| node_api
node_backend_app -->|"hosts"| node_api
node_api -->|"delegates to"| node_services
node_scheduler -->|"triggers ingestion"| node_services
node_services -->|"selects provider"| node_provider_config
node_services -->|"authenticates provider calls"| node_auth
node_services -->|"reads and writes"| node_repositories
node_repositories -->|"persists"| node_domain
node_repositories -->|"stores in"| node_database
node_services -->|"publishes readings"| node_producer
node_producer -->|"publishes events"| node_broker
node_broker -->|"delivers events"| node_consumer
node_consumer -->|"persists processing results"| node_repositories
node_compose -->|"builds and runs"| node_containers
node_compose -->|"provisions"| node_broker

click node_ui_app "https://github.com/bunnycoder1999/ccms-monitor/blob/main/ccms-frontend/src/app/layout.tsx"
click node_backend_app "https://github.com/bunnycoder1999/ccms-monitor/blob/main/ccms_monitor/src/main/java/com/example/ccms_monitor/CcmsApplication.java"
click node_api "https://github.com/bunnycoder1999/ccms-monitor/blob/main/ccms_monitor/src/main/java/com/example/ccms_monitor/controller/MeterReadingController.java"
click node_broker "https://github.com/bunnycoder1999/ccms-monitor/blob/main/kafka-docker/docker-compose.yml"
click node_compose "https://github.com/bunnycoder1999/ccms-monitor/blob/main/compose.yaml"
click node_containers "https://github.com/bunnycoder1999/ccms-monitor/blob/main/ccms_monitor/Dockerfile"

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_pages,node_ui_queries,node_ui_api,node_ui_components toneBlue
class node_backend_app,node_api,node_services,node_provider_config,node_auth,node_scheduler,node_domain,node_repositories toneAmber
class node_producer,node_broker,node_consumer toneMint
class node_database,node_compose,node_containers toneRose
```

## Components

### Next.js Operator UI

- [App shell & login](https://github.com/bunnycoder1999/ccms-monitor/blob/main/ccms-frontend/src/app/layout.tsx): Next.js routes · Provides the root shell, authentication entry, and authenticated navigation. · `ccms-frontend/src/app/layout.tsx`
- **Operations pages**: Next.js pages · Dashboard, meter IDs, and meter readings workflows.
- **Query hooks**: React Query · Resource-specific meter and reading query behavior.
- **Backend API client**: frontend services · Axios-backed meter and reading API modules.
- **Meter operations UI**: React components · Tables and fetch controls render operational workflows.

### Spring Boot Backend

- [CCMS application](https://github.com/bunnycoder1999/ccms-monitor/blob/main/ccms_monitor/src/main/java/com/example/ccms_monitor/CcmsApplication.java): Spring Boot entry · `ccms_monitor/src/main/java/com/example/ccms_monitor/CcmsApplication.java`
- [Meter REST controllers](https://github.com/bunnycoder1999/ccms-monitor/blob/main/ccms_monitor/src/main/java/com/example/ccms_monitor/controller/MeterReadingController.java): Spring MVC · HTTP boundary for meter serials, readings, and Jio operations. · `ccms_monitor/src/main/java/com/example/ccms_monitor/controller/MeterReadingController.java`
- **Meter & provider services**: service layer · Orchestrates meter operations, provider APIs, and data fetching.
- **Provider configuration**: provider registry · Config-driven service-provider definitions.
- **Provider authentication**: auth service · Uses configured authentication properties for provider access.
- **Scheduled ingestion**: Spring scheduler · Initiates periodic fetch-to-processing work.
- **Meter domain**: JPA entities · Separate meter serial number and reading records.
- **Meter repositories**: Spring Data · Database boundary for serial numbers and readings.

### Kafka Transport

- **Reading event producer**: Kafka producer · Publishes MeterReadingEvent messages.
- [Kafka broker](https://github.com/bunnycoder1999/ccms-monitor/blob/main/kafka-docker/docker-compose.yml): event broker · External asynchronous reading transport. · `kafka-docker/docker-compose.yml`
- **Reading event consumer**: Kafka consumer · Processes received reading events for persistence workflows.

### Deployment & Infrastructure

- **Application database**: persistent store · Infrastructure connection settings are in application properties.
- [Service orchestration](https://github.com/bunnycoder1999/ccms-monitor/blob/main/compose.yaml): Docker Compose · Coordinates application and infrastructure containers. · `compose.yaml`
- [Application containers](https://github.com/bunnycoder1999/ccms-monitor/blob/main/ccms_monitor/Dockerfile): Docker builds · Backend and frontend images are built independently. · `ccms_monitor/Dockerfile`

## Connections

- App shell & login → Operations pages: routes users to
- App shell & login → Query hooks: installs query provider
- Operations pages → Meter operations UI: renders
- Meter operations UI → Query hooks: uses
- Query hooks → Backend API client: fetches through
- Backend API client → Meter REST controllers: REST requests
- CCMS application → Meter REST controllers: hosts
- Meter REST controllers → Meter & provider services: delegates to
- Scheduled ingestion → Meter & provider services: triggers ingestion
- Meter & provider services → Provider configuration: selects provider
- Meter & provider services → Provider authentication: authenticates provider calls
- Meter & provider services → Meter repositories: reads and writes
- Meter repositories → Meter domain: persists
- Meter repositories → Application database: stores in
- Meter & provider services → Reading event producer: publishes readings
- Reading event producer → Kafka broker: publishes events
- Kafka broker → Reading event consumer: delivers events
- Reading event consumer → Meter repositories: persists processing results
- Service orchestration → Application containers: builds and runs
- Service orchestration → Kafka broker: provisions