Skip to content

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 into cis-api).
  • Communication:

    • cis-api and cis-workflow interact via HTTP REST APIs (e.g., cis-api triggers tasks in cis-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 (in cis-workflow)
    • Endpoints: /triggerTask, /processtask, /getNodeDetails.
    • Role: Entry point for moving workflows forward.
  • Service: WorkflowProcessDraftService & WorkflowProcessingService (in cis-workflow)
    • Handles the creation and updating of workflow drafts.
  • Business Logic Hook: CisBusinessService (in cis-workflow)
    • Contains specific logic for Maintenance request types (e.g., EXCISION_REQUEST, ENDORSEMENT_REQUEST).
    • Action: Extend this service to handle new Maintenance-specific logic.

Document Management

  • Services: FileStorageService, FileDownloaderService (in cis-api)
    • Handles file upload/download.
    • Supports local storage and DigitalOcean Spaces (S3 compatible).
    • Entity: UserDocument, MaintenanceDraftDocument.

Notifications

  • Services: NotificationsService, EmailServiceHandler, SmsServiceHandler (in cis-api).
    • Manages email and SMS notifications.
  • Architecture: cis-emailer module handles the actual sending of emails csgdata@dalrrd.gov.za.

Audit Trail

  • Services: LoginAuditorService, SystemLogs (entity).
    • Recommendation: Implement a dedicated MaintenanceAuditService using SystemLogs or similar pattern for transaction auditing.

3. Database Schema

The schema already contains significant support for Maintenance entities in cis-api.

Key Entities Identified

  • MaintenanceDraft (MAN_DRAFT table)
    • Links to User, Province, Workflow, MaintenanceDraftSteps, MaintenanceDraftAnnexures.
  • MaintenanceDraftRequest (MAN_DRAFT_REQUEST)
  • MaintenanceDraftPayment (MAN_DRAFT_PAYMENT)
  • CaveatService and entities exist for Caveats.
  • Parcels: Access via LodgementSgDataParcelSearchService or views like VwSgdataParcels.

Extensions

  • The MAN_DRAFT table handles various request types (Excision, Endorsement, etc.) via REQUEST_TYPE_ID.
  • Check: Verify if MaintenanceDraft columns cover all specific fields for new maintenance types, or if a JSON/EAV extension is needed in MaintenanceDraftAnnexure.

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.
  • Routing:
    • Tasks are assigned and routed based on the processId and nodeId passed to RoutingController.
    • cis-api calls http://localhost:8091/triggerTask to initiate/advance steps.

5. Security & Compliance

  • Implementation: Spring Security 5 + OAuth2.
  • Authentication:
    • LDAP integration (LdapSecurityConfig) with Active Directory.
    • JWT Tokens used for stateless authentication.
  • Access Control:
    • RBAC is implemented (RoleService, UserSecurity).
    • Method-level security is available (@PreAuthorize).
  • SSL/TLS: Not enforced at application level (based on http URLs in config), likely offloaded to Load Balancer/Reverse Proxy.
    • Compliance Check: Ensure production application-prod.yaml uses https.

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 Parcels data in DB.
  • GIS Updates:
    • Integration: cis-search module points to internal GIS server (http://10.10.20.210/CSGGIS).
    • API: LodgementSgDataParcelSearchService interacts with spatial data.
  • Archiving:
    • Managed via FileStorageService (Local or Cloud Object Storage).

7. Gaps & Recommendations

  1. Deeds Interface Abstraction:
    • Gap: Direct interaction code is missing or implicit via DB/FTP.
    • Recommendation: Create a dedicated DeedsOfficeService interface to wrap DB/FTP interactions for better testability and potential future API upgrade.
  2. Workflow Visualization:
    • Gap: Hard to visualize flows purely from code (CisBusinessService giant switch statement).
    • Recommendation: Ensure Workflow Studio (frontend/config tool) is synchronized with cis-workflow logic.
  3. Maintenance Business Logic:
    • Gap: CisBusinessService aggregates many request types.
    • Recommendation: Refactor CisBusinessService to use a Strategy Pattern for different Maintenance Request types (e.g., ExcisionHandler, CancellationHandler) to avoid a monolithic service class.