Maintenance Module Analysis¶
1. Architecture Overview¶
The backend follows a Modular Monolith or Service-Oriented Architecture (SOA) built with Spring Boot.
-
Primary Modules:
cis-api: The main application handling business logic, user management, and persistence.cis-workflow: A dedicated service for handling workflow state transitions and task routing.cis-emailer: A shared module for email notifications.cis-search: A module for search functionality (integrated intocis-api).
-
Communication:
cis-apiandcis-workflowinteract via HTTP REST APIs (e.g.,cis-apitriggers tasks incis-workflow).- Shared Database (Oracle) is used for persistence across modules.
-
Database: Oracle Database (
jdbc:oracle:thin). - Security: Spring Security with OAuth2 and LDAP authentication.
2. Reusable Services & Controllers¶
The following components can be reused or extended for the Maintenance Module:
Workflow Orchestration¶
- Controller:
RoutingController(incis-workflow)- Endpoints:
/triggerTask,/processtask,/getNodeDetails. - Role: Entry point for moving workflows forward.
- Endpoints:
- Service:
WorkflowProcessDraftService&WorkflowProcessingService(incis-workflow)- Handles the creation and updating of workflow drafts.
- Business Logic Hook:
CisBusinessService(incis-workflow)- Contains specific logic for Maintenance request types (e.g.,
EXCISION_REQUEST,ENDORSEMENT_REQUEST). - Action: Extend this service to handle new Maintenance-specific logic.
- Contains specific logic for Maintenance request types (e.g.,
Document Management¶
- Services:
FileStorageService,FileDownloaderService(incis-api)- Handles file upload/download.
- Supports local storage and DigitalOcean Spaces (S3 compatible).
- Entity:
UserDocument,MaintenanceDraftDocument.
Notifications¶
- Services:
NotificationsService,EmailServiceHandler,SmsServiceHandler(incis-api).- Manages email and SMS notifications.
- Architecture:
cis-emailermodule handles the actual sending of emailscsgdata@dalrrd.gov.za.
Audit Trail¶
- Services:
LoginAuditorService,SystemLogs(entity).- Recommendation: Implement a dedicated
MaintenanceAuditServiceusingSystemLogsor similar pattern for transaction auditing.
- Recommendation: Implement a dedicated
3. Database Schema¶
The schema already contains significant support for Maintenance entities in cis-api.
Key Entities Identified¶
- MaintenanceDraft (
MAN_DRAFTtable)- Links to
User,Province,Workflow,MaintenanceDraftSteps,MaintenanceDraftAnnexures.
- Links to
- MaintenanceDraftRequest (
MAN_DRAFT_REQUEST) - MaintenanceDraftPayment (
MAN_DRAFT_PAYMENT) - CaveatService and entities exist for Caveats.
- Parcels: Access via
LodgementSgDataParcelSearchServiceor views likeVwSgdataParcels.
Extensions¶
- The
MAN_DRAFTtable handles various request types (Excision, Endorsement, etc.) viaREQUEST_TYPE_ID. - Check: Verify if
MaintenanceDraftcolumns cover all specific fields for new maintenance types, or if a JSON/EAV extension is needed inMaintenanceDraftAnnexure.
4. Workflow Integration¶
- Engine: Custom implementation driven by
cis-workflow. - Configuration:
- Flows seem to be defined via
WorkflowMatrixService/WorkflowScreenService(metadata driven). - Orchestration is triggered via
RoutingController.
- Flows seem to be defined via
- Routing:
- Tasks are assigned and routed based on the
processIdandnodeIdpassed toRoutingController. cis-apicallshttp://localhost:8091/triggerTaskto initiate/advance steps.
- Tasks are assigned and routed based on the
5. Security & Compliance¶
- Implementation: Spring Security 5 + OAuth2.
- Authentication:
- LDAP integration (
LdapSecurityConfig) withActive Directory. - JWT Tokens used for stateless authentication.
- LDAP integration (
- Access Control:
- RBAC is implemented (
RoleService,UserSecurity). - Method-level security is available (
@PreAuthorize).
- RBAC is implemented (
- SSL/TLS: Not enforced at application level (based on
httpURLs in config), likely offloaded to Load Balancer/Reverse Proxy.- Compliance Check: Ensure production
application-prod.yamluseshttps.
- Compliance Check: Ensure production
6. Integration Points¶
- Deeds Office:
- Current State: Likely integration via shared Oracle Database (
sgtrndb) or FTP (10.10.20.205). - Code: No direct REST API client found. Relies on
Parcelsdata in DB.
- Current State: Likely integration via shared Oracle Database (
- GIS Updates:
- Integration:
cis-searchmodule points to internal GIS server (http://10.10.20.210/CSGGIS). - API:
LodgementSgDataParcelSearchServiceinteracts with spatial data.
- Integration:
- Archiving:
- Managed via
FileStorageService(Local or Cloud Object Storage).
- Managed via
7. Gaps & Recommendations¶
- Deeds Interface Abstraction:
- Gap: Direct interaction code is missing or implicit via DB/FTP.
- Recommendation: Create a dedicated
DeedsOfficeServiceinterface to wrap DB/FTP interactions for better testability and potential future API upgrade.
- Workflow Visualization:
- Gap: Hard to visualize flows purely from code (
CisBusinessServicegiant switch statement). - Recommendation: Ensure
Workflow Studio(frontend/config tool) is synchronized withcis-workflowlogic.
- Gap: Hard to visualize flows purely from code (
- Maintenance Business Logic:
- Gap:
CisBusinessServiceaggregates many request types. - Recommendation: Refactor
CisBusinessServiceto use a Strategy Pattern for different Maintenance Request types (e.g.,ExcisionHandler,CancellationHandler) to avoid a monolithic service class.
- Gap: