# pariharashish/dgh architecture

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

- Interactive diagram: https://gitdiagram.com/pariharashish/dgh
- Repository: https://github.com/pariharashish/dgh

## Overview

#### Purpose and runtime
This is a Maven-based Java/Spring backend for managing oil-and-gas domain data: basins, contract areas, facilities, wells, tanks, devices, operators, tariffs, users, access control, alerts, change requests, audits, and reports. The application entry point is `src/main/java/com/logicladder/dgh/DghApplication.java`; environment-specific Spring properties are under `src/main/resources/application.properties` and `src/main/resources/application-*.properties`.

#### HTTP API boundary
REST controllers are the inbound boundary, organized by domain and reporting:
- `src/main/java/com/logicladder/dgh/controller/WellController.java`
- `src/main/java/com/logicladder/dgh/controller/DeviceController.java`
- `src/main/java/com/logicladder/dgh/controller/reports/GlobalReportsController.java`

Requests pass through request/response logging and centralized exception handling at `src/main/java/com/logicladder/dgh/components/RequestResponseLoggingInterceptor.java` and `src/main/java/com/logicladder/dgh/configuration/GlobalExceptionHandler.java`. DTOs form the API contract boundary before persistence/domain mapping, e.g. `src/main/java/com/logicladder/dgh/dto/WellDto.java`.

#### Authentication and authorization
JWT authentication is exposed through `src/main/java/com/logicladder/dgh/security/controller/AuthenticationRestController.java`. Token extraction, validation, and Spring Security integration are centered on:
- `src/main/java/com/logicladder/dgh/security/JwtAuthorizationTokenFilter.java`
- `src/main/java/com/logicladder/dgh/security/JwtTokenUtil.java`
- `src/main/java/com/logicladder/dgh/security/config/WebSecurityConfig.java`

Authorization appears to be role/page-group based, persisted through `src/main/java/com/logicladder/dgh/entity/app/AccessRolePageGroup.java` and accessed through `src/main/java/com/logicladder/dgh/security/repository/IAccessRolePageGroupRepository.java`.

#### Core business and persistence layers
Controllers delegate to interface-driven services and implementations, which operate on JPA entities and repositories/DAOs. Representative flow is controller → service → repository/DAO → relational persistence:
- `src/main/java/com/logicladder/dgh/service/impl/WellServiceImpl.java`
- `src/main/java/com/logicladder/dgh/security/repository/IWellRepository.java`
- `src/main/java/com/logicladder/dgh/entity/app/Well.java`

The repository contains both Spring Data-style repositories and custom generic DAO implementations, with transaction setup in `src/main/java/com/logicladder/dgh/configuration/JpaTransactionConfig.java`. Dozer mappings support DTO/entity conversion via `src/main/java/com/logicladder/dgh/configuration/DozerConfig.java`.

#### Logic Ladder integration and asynchronous workflows
A distinct integration layer synchronizes or orchestrates domain actions with an external “Logic Ladder” service. It has domain-specific interfaces/implementations for wells, devices, facilities, contract areas, alerts, and change requests:
- `src/main/java/com/logicladder/dgh/logic/ladder/service/impl/WellLogicLadderServiceImpl.java`
- `src/main/java/com/logicladder/dgh/logic/ladder/service/impl/DeviceLogicLadderServiceImpl.java`
- `src/main/java/com/logicladder/dgh/logic/ladder/service/impl/AsyncLogicLadderServiceImpl.java`

External request/response schemas are isolated under `src/main/java/com/logicladder/dgh/thirdparty/request/dto/` and `src/main/java/com/logicladder/dgh/thirdparty/response/dto/`. `RestTemplate` configuration at `src/main/java/com/logicladder/dgh/configuration/RestTemplateConfig.java` is the likely outbound HTTP client boundary.

#### Audit, notifications, and reporting
Hibernate insert/update listeners provide a cross-cutting audit/event capture path:
- `src/main/java/com/logicladder/dgh/hibernate/events/HibernateInsertUpdateEventListener.java`
- `src/main/java/com/logicladder/dgh/entity/app/AuditLog.java`
- `src/main/java/com/logicladder/dgh/entity/app/EventLog.java`

User/operator lifecycle actions generate templated email notifications through `src/main/java/com/logicladder/dgh/service/impl/MailServiceImpl.java` and FreeMarker templates in `src/main/resources/templates/`. SMS capability is represented by `src/main/java/com/logicladder/dgh/util/CallSmscApi.java`.

Reporting includes API-configurable boards/endpoints and Jasper report generation:
- `src/main/java/com/logicladder/dgh/controller/reports/config/BoardConfigServiceImpl.java`
- `src/main/java/com/logicladder/dgh/controller/reports/jasper/AbstractReportGenerator.java`
- `src/main/resources/templates/DGHReportTemplate.jrxml`

Main entry points: [`src/main/java/com/logicladder/dgh/security/repository/IWellRepository.java`](https://github.com/pariharashish/dgh/blob/main/src/main/java/com/logicladder/dgh/security/repository/IWellRepository.java) (Repositories & DAOs), [`src/main/java/com/logicladder/dgh/controller/WellController.java`](https://github.com/pariharashish/dgh/blob/main/src/main/java/com/logicladder/dgh/controller/WellController.java) (Domain REST controllers), [`src/main/java/com/logicladder/dgh/service/impl/WellServiceImpl.java`](https://github.com/pariharashish/dgh/blob/main/src/main/java/com/logicladder/dgh/service/impl/WellServiceImpl.java) (Domain services), [`src/main/java/com/logicladder/dgh/security/config/WebSecurityConfig.java`](https://github.com/pariharashish/dgh/blob/main/src/main/java/com/logicladder/dgh/security/config/WebSecurityConfig.java) (Spring Security)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["HTTP API"]
  node_controllers["Domain REST controllers"]
  node_report_controller["Reports API<br/>REST controller"]
  node_logging["Request logging<br/>MVC interceptor"]
  node_exceptions["Exception handling<br/>exception handler"]
  node_dto["API DTOs<br/>contract models<br/>[WellDto.java]"]
end

subgraph group_security["Security"]
  node_auth_api["Authentication API<br/>REST controller"]
  node_jwt_filter["JWT authorization filter<br/>security filter"]
  node_security_config["Spring Security<br/>security configuration"]
  node_access_control["Role/page access<br/>authorization persistence"]
end

subgraph group_core["Core domain"]
  node_services["Domain services<br/>service layer"]
  node_mapping["DTO/entity mapping<br/>Dozer configuration<br/>[DozerConfig.java]"]
  node_repositories["Repositories &amp; DAOs<br/>persistence layer"]
  node_entities["JPA domain entities<br/>entity model<br/>[Well.java]"]
  node_database[("Relational database<br/>persistence store")]
end

subgraph group_integration["Logic Ladder integration"]
  node_logic_ladder["Logic Ladder services<br/>integration services"]
  node_async_logic_ladder["Async integration<br/>asynchronous service"]
  node_external_contracts["External DTO contracts<br/>third-party schemas"]
  node_rest_client["Outbound HTTP client<br/>RestTemplate configuration"]
  node_external_logic_ladder["Logic Ladder platform<br/>external service"]
end

subgraph group_crosscutting["Audit, notifications &amp; reports"]
  node_audit_listener["Hibernate audit listener<br/>persistence event listener"]
  node_audit_logs["Audit &amp; event logs<br/>audit entities<br/>[AuditLog.java]"]
  node_mail["Email notifications<br/>mail service"]
  node_jasper["Jasper reporting<br/>report generator"]
end

node_app{{"Spring application<br/>application entry"}}

node_app -->|"boots"| node_security_config
node_security_config -->|"installs"| node_jwt_filter
node_auth_api -->|"issues/validates tokens"| node_jwt_filter
node_controllers -.->|"intercepted by"| node_logging
node_controllers -.->|"errors handled by"| node_exceptions
node_controllers -->|"accepts/returns"| node_dto
node_controllers -->|"delegates to"| node_services
node_dto -->|"mapped through"| node_mapping
node_mapping -->|"converts"| node_entities
node_services -->|"persists via"| node_repositories
node_repositories -->|"manages"| node_entities
node_repositories -->|"reads/writes"| node_database
node_security_config -->|"authorizes via"| node_access_control
node_services -->|"orchestrates"| node_logic_ladder
node_logic_ladder -->|"queues async work"| node_async_logic_ladder
node_logic_ladder -->|"uses"| node_external_contracts
node_external_contracts -->|"sent through"| node_rest_client
node_rest_client -->|"HTTP"| node_external_logic_ladder
node_repositories -.->|"entity changes trigger"| node_audit_listener
node_audit_listener -->|"records"| node_audit_logs
node_services -.->|"sends lifecycle notices"| node_mail
node_report_controller -->|"generates reports"| node_jasper
node_jasper -->|"queries data"| node_repositories

click node_app "https://github.com/pariharashish/dgh/blob/main/src/main/java/com/logicladder/dgh/DghApplication.java"
click node_controllers "https://github.com/pariharashish/dgh/blob/main/src/main/java/com/logicladder/dgh/controller/WellController.java"
click node_report_controller "https://github.com/pariharashish/dgh/blob/main/src/main/java/com/logicladder/dgh/controller/reports/GlobalReportsController.java"
click node_logging "https://github.com/pariharashish/dgh/blob/main/src/main/java/com/logicladder/dgh/components/RequestResponseLoggingInterceptor.java"
click node_exceptions "https://github.com/pariharashish/dgh/blob/main/src/main/java/com/logicladder/dgh/configuration/GlobalExceptionHandler.java"
click node_dto "https://github.com/pariharashish/dgh/blob/main/src/main/java/com/logicladder/dgh/dto/WellDto.java"
click node_auth_api "https://github.com/pariharashish/dgh/blob/main/src/main/java/com/logicladder/dgh/security/controller/AuthenticationRestController.java"
click node_jwt_filter "https://github.com/pariharashish/dgh/blob/main/src/main/java/com/logicladder/dgh/security/JwtAuthorizationTokenFilter.java"
click node_security_config "https://github.com/pariharashish/dgh/blob/main/src/main/java/com/logicladder/dgh/security/config/WebSecurityConfig.java"
click node_access_control "https://github.com/pariharashish/dgh/blob/main/src/main/java/com/logicladder/dgh/security/repository/IAccessRolePageGroupRepository.java"
click node_services "https://github.com/pariharashish/dgh/blob/main/src/main/java/com/logicladder/dgh/service/impl/WellServiceImpl.java"
click node_mapping "https://github.com/pariharashish/dgh/blob/main/src/main/java/com/logicladder/dgh/configuration/DozerConfig.java"
click node_repositories "https://github.com/pariharashish/dgh/blob/main/src/main/java/com/logicladder/dgh/security/repository/IWellRepository.java"
click node_entities "https://github.com/pariharashish/dgh/blob/main/src/main/java/com/logicladder/dgh/entity/app/Well.java"
click node_logic_ladder "https://github.com/pariharashish/dgh/blob/main/src/main/java/com/logicladder/dgh/logic/ladder/service/impl/WellLogicLadderServiceImpl.java"
click node_async_logic_ladder "https://github.com/pariharashish/dgh/blob/main/src/main/java/com/logicladder/dgh/logic/ladder/service/impl/AsyncLogicLadderServiceImpl.java"
click node_rest_client "https://github.com/pariharashish/dgh/blob/main/src/main/java/com/logicladder/dgh/configuration/RestTemplateConfig.java"
click node_audit_listener "https://github.com/pariharashish/dgh/blob/main/src/main/java/com/logicladder/dgh/hibernate/events/HibernateInsertUpdateEventListener.java"
click node_audit_logs "https://github.com/pariharashish/dgh/blob/main/src/main/java/com/logicladder/dgh/entity/app/AuditLog.java"
click node_mail "https://github.com/pariharashish/dgh/blob/main/src/main/java/com/logicladder/dgh/service/impl/MailServiceImpl.java"
click node_jasper "https://github.com/pariharashish/dgh/blob/main/src/main/java/com/logicladder/dgh/controller/reports/jasper/AbstractReportGenerator.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_controllers,node_report_controller,node_logging,node_exceptions,node_dto toneBlue
class node_auth_api,node_jwt_filter,node_security_config,node_access_control toneAmber
class node_services,node_mapping,node_repositories,node_entities,node_database toneMint
class node_logic_ladder,node_async_logic_ladder,node_external_contracts,node_rest_client,node_external_logic_ladder toneRose
class node_audit_listener,node_audit_logs,node_mail,node_jasper toneIndigo
class node_app toneNeutral
```

## Components

### HTTP API

- [Domain REST controllers](https://github.com/pariharashish/dgh/blob/main/src/main/java/com/logicladder/dgh/controller/WellController.java): REST controllers · Domain APIs for wells, devices, and related oil-and-gas data. · `src/main/java/com/logicladder/dgh/controller/WellController.java`
- [Reports API](https://github.com/pariharashish/dgh/blob/main/src/main/java/com/logicladder/dgh/controller/reports/GlobalReportsController.java): REST controller · `src/main/java/com/logicladder/dgh/controller/reports/GlobalReportsController.java`
- [Request logging](https://github.com/pariharashish/dgh/blob/main/src/main/java/com/logicladder/dgh/components/RequestResponseLoggingInterceptor.java): MVC interceptor · `src/main/java/com/logicladder/dgh/components/RequestResponseLoggingInterceptor.java`
- [Exception handling](https://github.com/pariharashish/dgh/blob/main/src/main/java/com/logicladder/dgh/configuration/GlobalExceptionHandler.java): exception handler · `src/main/java/com/logicladder/dgh/configuration/GlobalExceptionHandler.java`
- [API DTOs](https://github.com/pariharashish/dgh/blob/main/src/main/java/com/logicladder/dgh/dto/WellDto.java): contract models · `src/main/java/com/logicladder/dgh/dto/WellDto.java`

### Security

- [Authentication API](https://github.com/pariharashish/dgh/blob/main/src/main/java/com/logicladder/dgh/security/controller/AuthenticationRestController.java): REST controller · `src/main/java/com/logicladder/dgh/security/controller/AuthenticationRestController.java`
- [JWT authorization filter](https://github.com/pariharashish/dgh/blob/main/src/main/java/com/logicladder/dgh/security/JwtAuthorizationTokenFilter.java): security filter · `src/main/java/com/logicladder/dgh/security/JwtAuthorizationTokenFilter.java`
- [Spring Security](https://github.com/pariharashish/dgh/blob/main/src/main/java/com/logicladder/dgh/security/config/WebSecurityConfig.java): security configuration · `src/main/java/com/logicladder/dgh/security/config/WebSecurityConfig.java`
- [Role/page access](https://github.com/pariharashish/dgh/blob/main/src/main/java/com/logicladder/dgh/security/repository/IAccessRolePageGroupRepository.java): authorization persistence · `src/main/java/com/logicladder/dgh/security/repository/IAccessRolePageGroupRepository.java`

### Core domain

- [Domain services](https://github.com/pariharashish/dgh/blob/main/src/main/java/com/logicladder/dgh/service/impl/WellServiceImpl.java): service layer · Interface-driven business operations and orchestration. · `src/main/java/com/logicladder/dgh/service/impl/WellServiceImpl.java`
- [DTO/entity mapping](https://github.com/pariharashish/dgh/blob/main/src/main/java/com/logicladder/dgh/configuration/DozerConfig.java): Dozer configuration · `src/main/java/com/logicladder/dgh/configuration/DozerConfig.java`
- [Repositories & DAOs](https://github.com/pariharashish/dgh/blob/main/src/main/java/com/logicladder/dgh/security/repository/IWellRepository.java): persistence layer · Spring Data repositories and custom generic DAOs. · `src/main/java/com/logicladder/dgh/security/repository/IWellRepository.java`
- [JPA domain entities](https://github.com/pariharashish/dgh/blob/main/src/main/java/com/logicladder/dgh/entity/app/Well.java): entity model · `src/main/java/com/logicladder/dgh/entity/app/Well.java`
- **Relational database**: persistence store

### Logic Ladder integration

- [Logic Ladder services](https://github.com/pariharashish/dgh/blob/main/src/main/java/com/logicladder/dgh/logic/ladder/service/impl/WellLogicLadderServiceImpl.java): integration services · Domain synchronization for wells, devices, facilities, and related workflows. · `src/main/java/com/logicladder/dgh/logic/ladder/service/impl/WellLogicLadderServiceImpl.java`
- [Async integration](https://github.com/pariharashish/dgh/blob/main/src/main/java/com/logicladder/dgh/logic/ladder/service/impl/AsyncLogicLadderServiceImpl.java): asynchronous service · `src/main/java/com/logicladder/dgh/logic/ladder/service/impl/AsyncLogicLadderServiceImpl.java`
- **External DTO contracts**: third-party schemas
- [Outbound HTTP client](https://github.com/pariharashish/dgh/blob/main/src/main/java/com/logicladder/dgh/configuration/RestTemplateConfig.java): RestTemplate configuration · `src/main/java/com/logicladder/dgh/configuration/RestTemplateConfig.java`
- **Logic Ladder platform**: external service

### Audit, notifications & reports

- [Hibernate audit listener](https://github.com/pariharashish/dgh/blob/main/src/main/java/com/logicladder/dgh/hibernate/events/HibernateInsertUpdateEventListener.java): persistence event listener · Captures insert and update events. · `src/main/java/com/logicladder/dgh/hibernate/events/HibernateInsertUpdateEventListener.java`
- [Audit & event logs](https://github.com/pariharashish/dgh/blob/main/src/main/java/com/logicladder/dgh/entity/app/AuditLog.java): audit entities · `src/main/java/com/logicladder/dgh/entity/app/AuditLog.java`
- [Email notifications](https://github.com/pariharashish/dgh/blob/main/src/main/java/com/logicladder/dgh/service/impl/MailServiceImpl.java): mail service · Uses FreeMarker templates for lifecycle notifications. · `src/main/java/com/logicladder/dgh/service/impl/MailServiceImpl.java`
- [Jasper reporting](https://github.com/pariharashish/dgh/blob/main/src/main/java/com/logicladder/dgh/controller/reports/jasper/AbstractReportGenerator.java): report generator · `src/main/java/com/logicladder/dgh/controller/reports/jasper/AbstractReportGenerator.java`

### Other components

- [Spring application](https://github.com/pariharashish/dgh/blob/main/src/main/java/com/logicladder/dgh/DghApplication.java): application entry · `src/main/java/com/logicladder/dgh/DghApplication.java`

## Connections

- Spring application → Spring Security: boots
- Spring Security → JWT authorization filter: installs
- Authentication API → JWT authorization filter: issues/validates tokens
- Domain REST controllers → Request logging: intercepted by
- Domain REST controllers → Exception handling: errors handled by
- Domain REST controllers → API DTOs: accepts/returns
- Domain REST controllers → Domain services: delegates to
- API DTOs → DTO/entity mapping: mapped through
- DTO/entity mapping → JPA domain entities: converts
- Domain services → Repositories & DAOs: persists via
- Repositories & DAOs → JPA domain entities: manages
- Repositories & DAOs → Relational database: reads/writes
- Spring Security → Role/page access: authorizes via
- Domain services → Logic Ladder services: orchestrates
- Logic Ladder services → Async integration: queues async work
- Logic Ladder services → External DTO contracts: uses
- External DTO contracts → Outbound HTTP client: sent through
- Outbound HTTP client → Logic Ladder platform: HTTP
- Repositories & DAOs → Hibernate audit listener: entity changes trigger
- Hibernate audit listener → Audit & event logs: records
- Domain services → Email notifications: sends lifecycle notices
- Reports API → Jasper reporting: generates reports
- Jasper reporting → Repositories & DAOs: queries data