Skip to content

Module: cis-api (Core Cadastral Engine)

cis-api is the foundational transactional core of the Cadastral Information System (CIS). Running on Java 25 with Spring Boot 4.1.2, it encapsulates the statutory land administration domains, spatial property registration, survey examination, and historical records preservation.


1. Domain Architecture Overview

cis-api acts as a stateless OAuth2 Resource Server listening on port 8089. It validates RS256 cryptographically signed JSON Web Tokens (JWT) forwarded by cis-bff and orchestrates seven major business domain modules:

graph TD
    classDef domain fill:#E8F5E9,stroke:#2E7D32,stroke-width:2px,color:#1B5E20;
    classDef lib fill:#E0F7FA,stroke:#00838F,stroke-width:1.5px,color:#006064;

    API[cis-api Core Application :8089]

    subgraph BUSINESS_MODULES["Core Cadastral Business Modules"]
        INFO["1. Information System & Data Viewer"]:::domain
        RESERV["2. Reservation Engine"]:::domain
        LODGE["3. Lodgement Engine"]:::domain
        EXAM["4. Examination Engine<br/>(Phase 1 & Phase 2 Examination)"]:::domain
        RELODGE["5. Relodgement Engine"]:::domain
        MAINT["6. Maintenance Engine"]:::domain
        ARCH["7. Archival & Historical Records (HRA)"]:::domain
    end

    subgraph EMBEDDED_LIBS["Embedded Submodules"]
        SEARCH["cis-search<br/>(Spatial & Lucene Search)"]:::lib
        EMAIL["cis-emailer<br/>(PDF Generation & Email Notifications)"]:::lib
    end

    API --> INFO
    API --> RESERV
    API --> LODGE
    API --> EXAM
    API --> RELODGE
    API --> MAINT
    API --> ARCH

    INFO -.->|Search Queries| SEARCH
    INFO -.->|Dispatch Mails| EMAIL
    RESERV -.->|Acknowledgement Notices| EMAIL
    LODGE -.->|Batch Handoff| EXAM
    LODGE -.->|Proforma Invoices| EMAIL
    EXAM -.->|Defect Queries| RELODGE
    EXAM -.->|Query & Outcome Letters| EMAIL
    EXAM -.->|Approved Dockets| ARCH
    RELODGE -.->|Amended Batches| EXAM
    RELODGE -.->|Acknowledgement Notices| EMAIL
    MAINT -.->|Outcome Letters| EMAIL
    ARCH -.->|Catalog Indexing| SEARCH
    ARCH -.->|PlanSafe Strongroom Tracking| EMAIL

2. Deep Dive: Core Business Modules

Module 1: Information System & Data Viewer — Lifecycle Management

The Information System & Data Viewer is the public-facing and professional discovery gateway of the Cadastral Information System (CIS). It enables registered land surveyors, conveyancers, government planners, and citizens to discover, inspect, simulate statutory fees, purchase, and extract authoritative cadastral diagrams, beacon coordinates, ownership records, and spatial layers.


1.1 Complete End-to-End Lifecycle Vector Architecture

Below is the verified end-to-end 6-stage lifecycle architecture of the Information System:

Module 1: Information System Lifecycle Architecture


1.2 Chronological Stage-by-Stage Lifecycle Walkthrough

%%{init: {'theme': 'base', 'themeVariables': { 'fontSize': '14px', 'fontFamily': 'Roboto', 'lineColor': '#066636' }}}%%
flowchart LR
    classDef stage fill:#E8F5E9,stroke:#066636,stroke-width:2px,color:#003319;
    classDef action fill:#FFFFFF,stroke:#3b82f6,stroke-width:1.5px,color:#1e3a8a;
    classDef complete fill:#F3E8FF,stroke:#7E22CE,stroke-width:2px,color:#581C87;

    S1["1. Search & Discovery<br/>(Parcel / Erf / Farm / Scheme)"]:::stage
    S2["2. Spatial Data Viewer<br/>(Overlay Layers & Beacons)"]:::stage
    S3["3. Cart & Quota<br/>(Alpha / Diagram / Spatial)"]:::stage
    S4["4. Fee Simulator & Proforma<br/>(Statutory Tariffs & PDF)"]:::stage
    S5["5. Checkout Settlement<br/>(Payment / Exemption Hook)"]:::stage
    S6["6. S3 Packaging & Dispatch<br/>(ZIP Stream & Notification)"]:::complete

    S1 --> S2 --> S3 --> S4 --> S5 --> S6
Stage 1: Multi-Criteria Search & Discovery Engine
  • Objective: Rapidly identify cadastral land parcels, survey records, and spatial units across millions of national records.
  • Core Mechanisms:
    • Parcel Search (ParcelSearchService): Queries parcels by administrative hierarchy (Province, Major Region, Minor Region, Erf Number, Portion Number, Farm Name, Agricultural Holding).
    • Sectional Title Search (SectionalSearchService): Locates sectional schemes by scheme name, filing year, registration number, or unit number.
    • SG Number Search (NumberSearchService): Direct lookups by statutory Surveyor-General Diagram number (e.g., SG Dsg No 1234/2024), General Plan (GP), Compilation number, or Lease record.
    • Street Address Search (StreetSearchService): Cross-references municipal street numbers and road centerlines with underlying cadastral polygons.
    • NGI Geodetic Search (NgiSearchService): Discovers national geodetic beacons, trigonometrical stations, and GPS benchmarks.
  • Query Acceleration with cis-search:
    • Utilizes embedded Lucene indices synchronized with the SearchContext enum (PARCEL, FARM, SECTIONAL_TITLE, NGI) to achieve sub-second response times without cross-network RPC latency.
Stage 2: Interactive Spatial Data Viewer & Coordinate Inspection
  • Objective: Allow users to visually verify spatial boundaries, neighboring cadastre, servitudes, and beacon coordinates prior to procurement.
  • Core Capabilities (DataViewerResource, DataViewerService):
    • Layer Configuration (DataViewerConfiguration): Retrieves active spatial layers categorized by statutory hierarchy (Erven, Farm Portions, Servitudes, Mining Rights, Municipal Reserves).
    • Spatial SQL Projection (DataViewerCustomImpl): Executes dynamic spatial geometry queries (CustomQueryResultSetProjection) to project bounding polygons and beacon coordinates directly onto client web map controls.
    • Session Audit Logging (DataViewerLog): Automatically logs the requesting user ID, spatial bounding box coordinates, zoom scale, and access timestamp to enforce audit accountability.
Stage 3: Shopping Cart Assembly & Quota Management
  • Objective: Aggregate requested documents and data extracts, determine statutory item classifications, and evaluate user quota allowances.
  • Granular Item Data Models (CartItems):
    • AlphaNumeric Data (CartItemAlphaNumericData): Official land registry ownership records, parent title deed references, and registered endorsements.
    • Survey Diagram Documents (CartItemDiagramData): High-resolution digital scans and PDF copies of official Surveyor-General diagrams.
    • Spatial Data Exports (CartItemSpatialData): Machine-readable ESRI Shapefiles, DXF CAD files, and ASCII beacon coordinate tables.
    • Certified Copies (CartItemCertificateData): Statutorily certified cadastral extracts required for legal proceedings or deeds office registration.
  • Quota & Staging Engine (CartStage, CartStageData):
    • Items are staged in transient CartStage records.
    • The engine evaluates whether the user represents an exempt statutory entity (e.g., Municipal Planner, Department of Rural Development) or an account holder with free monthly quota balances.
Stage 4: Fee Simulation & Proforma Invoicing
  • Objective: Mathematically compute authoritative statutory tariffs, apply VAT, and generate formal proforma invoice documentation.
  • Tariff Calculation Mechanics (FeeSimulatorService):
    • Resolves item costs dynamically via InvoiceItemCostProjection based on data classification, output format (PDF vs Shapefile), and page count.
    • Eliminates client-side price tampering by computing all financial line items exclusively on the backend.
  • Proforma Invoice Compilation (InvoiceResource, InvoiceService):
    • Creates an official InvoicePerforma entity associated with a unique transaction reference and workflowId.
    • Flying Saucer (XHTML-to-PDF) compiles a formal tax invoice document featuring statutory headers, breakdowns, and payment EFT reference codes.
    • Triggers InvoiceNotification via cis-emailer to dispatch the proforma invoice directly to the customer's email.
Stage 5: Order Checkout & Workflow State Promotion
  • Objective: Validate payment settlement (or statutory exemption) and promote the transient staging cart to an active fulfillment order.
  • Checkout Processing (CartResource.checkout):
    • Ingests CheckoutVm carrying the payment confirmation token, credit card gateway receipt, or official statutory fee waiver certificate.
    • Invokes CartResource.addToFinalCart (addCartHook):
      1. Migrates items from CartStage to permanent Cart and CartItems tables.
      2. Assigns a formal tracking number (CIS-INF-YYYY-NNNNNN).
      3. Cleans up transient staging tables (/api/cart/empty).
    • Promotes the cis-workflow business process state to PAID / DISPATCH_READY.
Stage 6: S3 Document Packaging & Multi-Channel Dispatch
  • Objective: Assemble requested cadastral files from secure object storage, compress into a secure ZIP container, and fulfill delivery across digital channels.
  • Automated Packaging Pipeline (DispatchResource, GlobalDispatchService):
    • Object Storage Retrieval: Fetches raw diagram PDFs and shapefiles directly from RustFS S3 (Port 9000).
    • Zero-Disk-Leak Streaming: Uses Java's ZipOutputStream to stream the compressed docs.zip archive directly to the client or storage destination without creating temporary files on the container filesystem.
    • Secure Download Token: Generates an encrypted, time-limited token granting access to the assembled archive.
  • Multi-Channel Fulfillment:
    • Email Delivery: cis-emailer dispatches completion notifications with secure download links via Mailpit / SMTP (Port 1025).
    • SFTP Push: For bulk corporate orders or external data partners, uploadDocsOnFtp automatically pushes batch archives directly to the SFTP Server (Port 2022).
    • Applicant SMS: Enqueues an instant tracking SMS via the SMS Gateway confirming that the cadastral documents are ready for download.

1.3 Detailed Sequence Interaction Diagram

The sequence diagram below details the chronological request-reply interaction across all tiers during an Information System transaction:

sequenceDiagram
    autonumber
    actor User as Citizen / Professional Surveyor
    participant BFF as cis-bff (:8080)
    participant API as cis-api (:8089)
    participant Search as cis-search (In-Memory)
    participant WF as cis-workflow (:8090)
    participant S3 as RustFS S3 (:9000)
    participant Mail as Mailpit / SMTP (:1025)
    participant DB as Oracle Database 23 (:1521)

    %% 1. Search Phase
    User->>BFF: POST /api/search/parcel (Erf 104, Pretoria)
    BFF->>API: Forward with Bearer JWT
    API->>Search: Execute spatial Lucene query (SearchContext.PARCEL)
    Search->>DB: Query relational parcels & beacons
    DB-->>API: Return ParcelErfProjection
    API-->>User: Search Results (Available Diagram PDFs & Shapefiles)

    %% 2. Cart & Quota Phase
    User->>BFF: POST /api/cart/add (CartStageDataDto)
    BFF->>API: Add Item to Stage
    API->>DB: Persist transient CartStage & CartStageData
    API-->>User: Cart Stage Updated (Item count: 1)

    %% 3. Invoicing Phase
    User->>BFF: POST /api/invoice/save (Request Proforma)
    BFF->>API: Generate Invoice Data
    API->>API: FeeSimulatorService: Compute statutory tariff
    API->>DB: Persist InvoicePerforma record
    API->>Mail: Dispatch Proforma Invoice PDF to customer
    API-->>User: Proforma Invoice Generated (Invoice #INV-2026-089)

    %% 4. Checkout Phase
    User->>BFF: POST /api/cart/checkout (CheckoutVm: Proof of Payment)
    BFF->>API: Execute Checkout Hook
    API->>DB: Finalize Cart & promote CartStage -> Cart
    API->>WF: Transition state to PAID (Trigger AutoDispatchWorkflow)
    WF-->>API: Workflow State = DISPATCH_READY
    API-->>User: Checkout Successful (Order #ORD-2026-4412)

    %% 5. Fulfillment Phase
    WF->>API: Trigger GlobalDispatchService
    API->>S3: Retrieve Diagram PDFs & Shapefiles (S3 API :9000)
    S3-->>API: Binary file streams
    API->>API: ZipOutputStream: Stream into docs.zip
    API->>S3: Store final assembled docs.zip
    API->>Mail: Send completion email with secure download token
    API-->>User: Order Fulfilled (Download link active)

1.4 State Machine: Cart & Order Progression

stateDiagram-v2
    [*] --> BROWSE: User searches land records
    BROWSE --> STAGED: Item added to cart (CartStage)
    STAGED --> STAGED: Modify items / Add bulk
    STAGED --> PROFORMA_ISSUED: Checkout initiated (Fee simulator executed)
    PROFORMA_ISSUED --> SETTLED: Payment confirmed or statutory exemption verified
    PROFORMA_ISSUED --> CANCELLED: Stale stage cleanup / User empties cart
    SETTLED --> FINALIZED: addCartHook promotes CartStage to permanent Cart
    FINALIZED --> PACKAGING: GlobalDispatchService fetches S3 blobs
    PACKAGING --> COMPLETED: docs.zip assembled, email sent, SMS dispatched
    COMPLETED --> [*]

1.5 Information System REST API Reference Matrix

HTTP Verb Endpoint Handler Method Request Body / Params Primary Role / Description
POST /api/search/parcel SearchResource.searchParcel ParcelSearchVm Queries land parcels by Erf, Portion, Farm, or Allotment.
POST /api/search/sectional SearchResource.searchSectional SectionalSearchVm Queries sectional title schemes and registered unit numbers.
POST /api/search/number SearchResource.searchNumber NumberSearchVm Direct lookup by SG Diagram, GP, or compilation reference.
GET /api/data-viewer/getObjectType DataViewerResource.getType None Lists distinct spatial layer categories available for display.
POST /api/data-viewer/execute/query DataViewerResource.executeCustomQuery DataViewerRequestVm Projects spatial geometry and beacon coordinates for map display.
GET /api/cart/ CartResource.getCartDetails userId Retrieves active user cart and staged procurement items.
POST /api/cart/add CartResource.addToCart CartStageDataDto Adds an alphanumeric, diagram, or spatial item to staging cart.
POST /api/cart/checkout CartResource.checkout CheckoutVm Executes order checkout, payment validation, and exemption checks.
POST /api/invoice/items/cost InvoiceResource.getInvoiceItemCosting InvoiceItemCostVm Computes dynamic statutory tariff fees via FeeSimulatorService.
GET /api/invoice/generate InvoiceResource.generatePdf workflowId Compiles official Flying Saucer PDF tax invoice docket.
GET /api/dispatch/downloadDispatchDocs DispatchResource.downloadZippedDocs workflowId Streams assembled docs.zip package via ZipOutputStream.
POST /api/dispatch/sendDispatchEmail/{id} DispatchResource.sendDispatchEmail workflowId Dispatches completion notification with secure download token.

Module 2: Reservation Engine — Statutory Algorithms & Lifecycle Architecture

The Reservation Engine is the statutory land administration engine of the Cadastral Information System (CIS). Prior to conducting an on-the-ground physical survey, a Professional Land Surveyor (PLS) must obtain authoritative, unique, and statutorily reserved parcel identifiers (Erf numbers, Farm portion numbers, Leasehold identifiers) from the Surveyor-General (SG).

The engine enforces strict statutory numbering sequences, validates parent property records against the national land cadastre, manages multi-step draft survey progression, generates cryptographic barcode acknowledgement dockets, enforces SLA retention periods, and handles surveyor-to-surveyor ownership transfers.


2.1 Complete End-to-End Lifecycle Vector Architecture

Below is the verified end-to-end 6-stage lifecycle architecture of the Reservation Engine, illustrating draft progression, the 12 statutory algorithms, dual staging/final execution pipelines, barcode dockets, and automated lifecycle monitors:

Module 2: Reservation Engine Statutory Algorithms & Lifecycle Architecture


2.2 Chronological Stage-by-Stage Lifecycle Walkthrough

%%{init: {'theme': 'base', 'themeVariables': { 'fontSize': '14px', 'fontFamily': 'Roboto', 'lineColor': '#1e3a8a' }}}%%
flowchart LR
    classDef stage fill:#EFF6FF,stroke:#1E40AF,stroke-width:2px,color:#1E3A8A;
    classDef algo fill:#FEF3C7,stroke:#D97706,stroke-width:2px,color:#78350F;
    classDef complete fill:#ECFDF5,stroke:#047857,stroke-width:2px,color:#064E3B;

    S1["1. Surveyor Draft Wizard<br/>(Multi-Step Auto-Save)"]:::stage
    S2["2. Parent Parcel Scrutiny<br/>(Cadastre Boundary Audit)"]:::stage
    S3["3. Algorithmic Preview<br/>(AlgoOutputType.STAGING)"]:::algo
    S4["4. Scrutiny & Lodgement<br/>(QC Checklist & Checkout)"]:::stage
    S5["5. SG Approval & Commit<br/>(AlgoOutputType.FINAL)"]:::complete
    S6["6. Lifecycle Monitoring<br/>(SLA Timers & Expiry)"]:::complete

    S1 --> S2 --> S3 --> S4 --> S5 --> S6
Stage 1: Surveyor Application & Multi-Step Draft Wizard
  • Objective: Allow professional surveyors to incrementally draft complex land transactions spanning multiple statutory actions without risk of session data loss.
  • Core Capabilities (ReservationDraftService, ReservationDraftStepsService):
    • Draft Persistence: Surveyors initiate a reservation docket (ReservationDraft) linked to their professional council accreditation ID.
    • Step-Level Isolation (ReservationDraftSteps): Complex survey schemes (e.g., closing a public lane and consolidating it with five adjoining erven) are constructed as distinct, sequential steps.
    • Outcome Chaining (isCopyOutcomeOfPrevious = true): The engine enables outputs of step \(N\) (e.g., newly formed parcels from a Street Closure) to be fed directly as inputs into step \(N+1\) (e.g., Consolidation) via addDraftStepByOutcomeIds and addDraftRequestByOutcomeIds.
Stage 2: Parent Parcel Designation & Validation Scrutiny
  • Objective: Validate the legal existence, parent ownership, and administrative boundary integrity of the land parcels subject to reservation.
  • Cadastral Validation Mechanics (ProcessReservationAlgo, LodgementValidationService):
    • Queries the core land registry to ensure the parent Erf or Farm portion is currently in an ACTIVE un-cancelled state.
    • Verifies that the parcel is not currently locked by an existing pending survey reservation or expropriation caveat.
    • Resolves administrative boundaries: Province -> Registration Division -> Major Region (Municipality) -> Minor Region (Township/Allotment Area).
Stage 3: Algorithmic Preview Execution (AlgoOutputType.STAGING)
  • Objective: Allow the surveyor to execute reservation algorithms in simulation mode, inspecting provisional parcel numbers and remainder designations before statutory commitment.
  • Staging Mechanics (ReservationAlgoFactory):
    • When processReservationDraftAlgo is called with AlgoOutputType.STAGING:
      1. The factory resolves the concrete algorithm corresponding to the statutory ReservationReason.
      2. The algorithm computes provisional numbers, remaining balances, and parent-child linkages in memory.
      3. Transient records are written to ReservationDraftOutcome marked as STAGED.
      4. Crucially, the persistent global parcel sequence counters in the database are not incremented, preventing sequence gaps if the surveyor modifies the proposal.
Stage 4: Examiner Scrutiny, Checklists & Lodgement Checkout
  • Objective: Enforce cadastral compliance checklists, assemble applicant affidavits, and execute formal lodgement checkout.
  • Scrutiny & Checkout Pipeline (ReservationResource.saveDraftCheckout):
    • Evaluates mandatory statutory questions (ReservationDraftChecklist): municipal planning approval references, environmental authorization flags, and consent endorsements.
    • Surveyors upload supporting documentation (town planning consent dockets, draft sketches) directly to RustFS S3 (Port 9000).
    • Invokes saveDraftCheckout to promote the draft into a formal reservation docket:
      • Transitions draft state to SUBMITTED.
      • Dispatches a process execution event to cis-workflow (Port 8090), placing the dossier into the Surveyor-General scrutiny work queue.
Stage 5: Surveyor-General Approval, Final Number Commitment & Barcode Docket
  • Objective: Authorize reservation, commit irrevocable statutory parcel numbers, and generate legally certified acknowledgement letters.
  • Final Execution & Docket Generation (AlgoOutputType.FINAL, ReservationAcknowledgementLetterService):
    • Upon examination officer sign-off in cis-workflow, the engine triggers ProcessReservationAlgo with AlgoOutputType.FINAL.
    • Pessimistic Lock & Sequence Commitment:
      • Obtains an exclusive database lock on the township/farm sequence counter.
      • Allocates official statutory parcel numbers (e.g., Erf 1052 Pretoria, Portion 44 of Farm Hartebeestpoort 410-JR).
      • Emits permanent records into ReservationDraftOutcome and core cadastral master tables.
    • Certified Acknowledgement Letter:
      • Generates an official Surveyor-General Acknowledgement Letter PDF via Flying Saucer.
      • Embeds Code128 / QR barcodes encoding the reservation reference, assigned parcel numbers, allocation timestamp, and SG digital signature.
      • Archives the generated PDF in RustFS S3 and delivers it to the surveyor via cis-emailer (Mailpit, Port 1025).
Stage 6: Active Lifecycle Management, Automated Expiry & Ownership Transfer
  • Objective: Enforce statutory reservation expiration timelines, issue proactive warning notifications, and facilitate surveyor transfers.
  • Lifecycle Governance Mechanics:
    • Automated Expiry Scheduler (ReservationExpiryNotification, TaskReminderService):
      • Statutory parcel reservations remain valid for a legally mandated period (e.g., 24 months).
      • A scheduled daemon periodically scans active reservations against system SLA clocks.
      • Dispatches 60-day and 30-day proactive expiry reminder emails to the land surveyor.
      • If unlodged upon deadline arrival, the engine triggers EXPIRED status, freeing the reserved numbers back into the cadastral registry.
    • Surveyor-to-Surveyor Transfer (ReservationTransferOutcomeLetterService):
      • If a developer transfers land development rights to a new professional surveyor, the engine facilitates a formal cession workflow.
      • Requires formal consent documentation, updates surveyor ownership references, generates an official Transfer Outcome Letter, and records an unalterable audit log.

2.3 The 12 Statutory Land Administration Algorithms (Deep Dive)

The CIS Reservation Engine implements 12 distinct statutory land administration algorithms in package com.dw.ngms.cis.service.reservation.algo.*. Each algorithm enforces specific cadastral rules mandated by the Land Survey Act:

Algorithm Name Statutory Reason Code Target Cadastral Domain Calculation Mechanics & Number Allocation Rules Remainder / Balance Preservation
Subdivision SUBDIVISION Erven, Farms, Agricultural Holdings, Leases Splits a parent parcel into \(N\) new child portions. Reads highest existing portion number for parent and assigns sequential integers \((max + 1) \dots (max + N)\). Preserves un-subdivided remainder balance as Portion 0 (Remainder of Erf/Farm).
Consolidation CONSOLIDATION Contiguous Erven, Farms Merges two or more contiguous parcels into a single unified cadastral entity. Queries township registry and assigns the next highest unallocated Erf/Farm number. Extinguishes all parent parcel numbers; marks parent records as superseded upon lodgement.
Excision EXCISION Agricultural Holdings Excises agricultural holding land out of an Agricultural Holdings Register and converts it into urban township erven under town planning schemes. Records excision certificate references; adjusts holding balance or extinguishes holding entity.
Creation of Town CREATION_OF_TOWN New Township Establishment Allocates complete numbering sequence for a newly proclaimed township: Erven \(1 \dots N\), including parks, municipal erven, and institutional sites. Establishes new township registry; links all child erven to the mother farm portions being built upon.
Extension of Township EXTENSION_OF_TOWNSHIPS Township Extension Phases Allocates additional erven for an existing proclaimed township (Phase 2, 3, etc.). Identifies the highest registered Erf number across all prior phases and begins from \((max + 1)\). Maintains uninterrupted continuous numerical sequence across all township extensions.
Creation of Farm CREATION_OF_FARMS Rural Cadastre / State Releases Establishes a brand new farm entity within a Registration Division (e.g., Farm 950-JR). Allocates Portion 0 as the mother parcel. Assigns Registration Division code, initial mother boundary, and province reference.
Lease Erven LEASE_ERVEN Long-Term Registered Leases Allocates statutory leasehold parcel numbers (prefixed with L or distinct lease sequences) over an existing parent parcel without fee alienating the underlying freehold ownership. Underlying parent parcel remains intact and active; lease polygon is registered as a subordinate right.
Public Place Closure PUBLIC_PLACE_CLOSURE Parks, Public Squares Formally closes a municipal public open space, park, or civic square. Converts the closed space into one or more registrable Erf numbers. Updates municipal vesting schedule; requires formal gazette proclamation reference.
Street Closure STREET_CLOSURE Road Reserves, Lanes Closes existing public road reserves, street lanes, or pedestrian walkways. Allocates provisional numbers to closed street strips for consolidation with adjoining owners. Amalgamates closed road strips with contiguous erven or assigns standalone Erf numbers.
Re-Designation RE_DESIGNATION Cadastral Unit Classification Changes the statutory cadastral designation of a parcel (e.g., converting a Farm Portion absorbed into an urban boundary into an Erf number, or vice versa). Maintains full historical cross-reference link between old designation and new statutory identifier.
Relay-Out RELAYOUT Approved General Plans Re-configures the internal parcel boundary layout of an approved General Plan (GP) before physical deeds registration has occurred. Cancels prior provisional parcel numbers within the GP perimeter and assigns a re-indexed layout sequence.
State Land STATELAND National & Provincial State Land Administers statutory parcel reservations, subdivisions, and land disposals specifically governing state-owned property and communal land tenures. Enforces ministerial consent validations and specialized state land registry prefixes.

2.4 Multi-Step Draft Progression & Step Outcome Chaining

Real-world cadastral developments rarely involve a single isolated statutory action. A typical mixed-use urban development requires multiple interdependent steps:

%%{init: {'theme': 'base', 'themeVariables': { 'fontSize': '13px', 'fontFamily': 'Roboto' }}}%%
flowchart TD
    classDef step fill:#EFF6FF,stroke:#2563EB,stroke-width:2px,color:#1E40AF;
    classDef outcome fill:#FEF3C7,stroke:#D97706,stroke-width:1.5px,color:#78350F;
    classDef final fill:#ECFDF5,stroke:#059669,stroke-width:2px,color:#065F46;

    subgraph Step1["Step 1: Street Closure (PUBLIC_ROAD_CLOSURE)"]
        P1["Input: Public Road Reserve<br/>(Church Street Strip)"]:::step
        A1["Algorithm: StreetClosure"]:::step
        O1["Outcome 1: Closed Street Strip<br/>(Provisional Erf 1050)"]:::outcome
        P1 --> A1 --> O1
    end

    subgraph Step2["Step 2: Consolidation (CONSOLIDATION)"]
        P2A["Input A: Closed Street (Erf 1050)"]:::step
        P2B["Input B: Adjoining Property (Erf 104)"]:::step
        A2["Algorithm: Consolidation"]:::step
        O2["Outcome 2: Unified Consolidated Parcel<br/>(Provisional Erf 1051)"]:::outcome
        O1 -.->|isCopyOutcomeOfPrevious = true| P2A
        P2B --> A2
        P2A --> A2
        A2 --> O2
    end

    subgraph Step3["Step 3: Subdivision (SUBDIVISION)"]
        P3["Input: Consolidated Erf 1051"]:::step
        A3["Algorithm: Subdivision (3 Portions)"]:::step
        O3A["Portion 1 of Erf 1051"]:::final
        O3B["Portion 2 of Erf 1051"]:::final
        O3C["Remainder of Erf 1051"]:::final
        O2 -.->|isCopyOutcomeOfPrevious = true| P3
        P3 --> A3
        A3 --> O3A
        A3 --> O3B
        A3 --> O3C
    end
Programmatic Mechanics of Chaining
  1. ReservationDraftSteps: Each step in the wizard has an integer stepNo and a designated ReservationReason.
  2. Outcome Staging: When Step 1 runs, ProcessReservationAlgo inserts staged records into ReservationDraftOutcome with stepNo = 1.
  3. Automated Inheritance (isCopyOutcomeOfPrevious):
  4. When Step 2 is configured with isCopyOutcomeOfPrevious = true, ReservationDraftService.addDraftStepByOutcomeIds copies the outcome identifiers from Step 1 directly into the input ReservationDraftRequest list for Step 2.
  5. This ensures complete mathematical and legal continuity across chained surveyor applications.

2.5 Dual Execution Pipeline: STAGING vs FINAL

The reservation engine uses a dual execution mode defined by the AlgoOutputType enum:

%%{init: {'theme': 'base', 'themeVariables': { 'fontSize': '14px', 'fontFamily': 'Roboto' }}}%%
flowchart LR
    classDef staging fill:#FFFBEB,stroke:#F59E0B,stroke-width:2px,color:#92400E;
    classDef final fill:#F0FDF4,stroke:#16A34A,stroke-width:2px,color:#166534;

    subgraph STAGING_PIPELINE["STAGING Execution Pipeline (Ephemeral Preview)"]
        ReqS["Surveyor clicks 'Generate Preview'"]:::staging
        CallS["processReservationDraftAlgo(STAGING)"]:::staging
        CompS["Compute Next Sequential Numbers"]:::staging
        PersS["Persist to ReservationDraftOutcome<br/>(Status = STAGED)"]:::staging
        LockS["NO DB Sequence Lock Acquired<br/>(Global counters remain unchanged)"]:::staging
        ReqS --> CallS --> CompS --> PersS --> LockS
    end

    subgraph FINAL_PIPELINE["FINAL Execution Pipeline (Statutory Commitment)"]
        ReqF["Examiner clicks 'Approve Reservation'"]:::final
        CallF["processReservationDraftAlgo(FINAL)"]:::final
        LockF["Acquire Exclusive DB Sequence Lock"]:::final
        IncrF["Increment Global Township/Farm Counter"]:::final
        PersF["Write Permanent Reservation Records"]:::final
        DocF["Generate Barcode Letter & QR Code"]:::final
        ReqF --> CallF --> LockF --> IncrF --> PersF --> DocF
    end
  • AlgoOutputType.STAGING:
  • Used during draft editing. Surveyors can recalculate numbers multiple times as plans evolve.
  • Writes provisional outcomes to ReservationDraftOutcome. If the draft is discarded, no database cleanup of statutory sequence tables is necessary.
  • AlgoOutputType.FINAL:
  • Invoked exclusively by cis-workflow upon formal Examiner approval.
  • Acquires a pessimistic database lock, increments the official statutory sequence counter, and guarantees that assigned parcel numbers are permanent and unalterable.

2.6 Detailed Sequence Interaction Diagram

The sequence diagram below details the chronological interaction across all architectural tiers during an end-to-end statutory reservation lifecycle:

sequenceDiagram
    autonumber
    actor PLS as Land Surveyor (PLS)
    participant BFF as cis-bff (:8080)
    participant API as cis-api (:8089)
    participant Algo as ReservationAlgoFactory
    participant WF as cis-workflow (:8090)
    participant DB as Oracle Database 23 (:1521)
    participant S3 as RustFS S3 (:9000)
    participant Mail as Mailpit / SMTP (:1025)

    %% 1. Draft Initiation
    PLS->>BFF: POST /api/reservation/draft (Create Draft Docket)
    BFF->>API: Forward with Bearer JWT
    API->>DB: Persist ReservationDraft & Steps
    DB-->>API: Return draftId = 5041
    API-->>PLS: Draft Initialized

    %% 2. Staging Algorithmic Preview
    PLS->>BFF: POST /api/reservation/processDraftAlgo (draftId, STAGING)
    BFF->>API: Execute Staging Algorithm
    API->>Algo: resolve(SUBDIVISION).process(draftData, STAGING)
    Algo->>DB: Read max portion from Cadastre (Erf 104 -> Max Portion = 3)
    Algo-->>API: Return Provisional Portions 4, 5 and Remainder
    API->>DB: Persist transient ReservationDraftOutcome (STAGED)
    API-->>PLS: Staged Numbers Displayed for Review

    %% 3. Lodgement & Workflow Trigger
    PLS->>BFF: POST /api/reservation/saveDraftCheckout (Checklist & Documents)
    BFF->>API: Process Checkout & Submission
    API->>S3: Store Town Planning Consents & Sketches
    API->>WF: Initiate Process (WF-RES-2026-901)
    WF-->>API: Status = PENDING_EXAMINATION
    API-->>PLS: Reservation Dossier Lodged

    %% 4. Examiner Scrutiny & Approval
    Note over WF,API: SG Cadastral Examiner Scrutinizes Boundary & Legal Compliance
    WF->>API: Trigger Statutory Approval Callback
    API->>Algo: resolve(SUBDIVISION).process(draftData, FINAL)
    Algo->>DB: Lock Sequence Counter & Commit Portions 4, 5
    API->>API: ReservationAcknowledgementLetterService.generatePdf()
    API->>S3: Upload Barcode Acknowledgement Letter PDF
    API->>Mail: Dispatch Acknowledgement Email with PDF Docket
    API-->>PLS: Statutory Reservation Approved & Number Letter Issued

2.7 State Machine: Statutory Reservation Parcel Lifecycle

stateDiagram-v2
    [*] --> DRAFT: Surveyor initiates reservation draft
    DRAFT --> DRAFT: Add steps / configure algorithms
    DRAFT --> STAGED_PREVIEW: Execute AlgoOutputType.STAGING
    STAGED_PREVIEW --> DRAFT: Modify parcel parameters
    STAGED_PREVIEW --> SUBMITTED: Surveyor lodges draft & completes checklist
    SUBMITTED --> UNDER_EXAMINATION: Ingested into cis-workflow
    UNDER_EXAMINATION --> QUERIED: Examiner requests clarification
    QUERIED --> UNDER_EXAMINATION: Surveyor submits rectified dockets
    UNDER_EXAMINATION --> REJECTED: Statutory non-compliance / overlap
    UNDER_EXAMINATION --> APPROVED: Examiner endorses reservation
    APPROVED --> ACTIVE: Final numbers committed & Barcode Letter issued
    ACTIVE --> TRANSFERRED: Cession of reservation to alternate PLS
    ACTIVE --> INCORPORATED: Physical survey lodged & registered in deeds
    ACTIVE --> EXPIRED: SLA timer elapsed without survey lodgement
    EXPIRED --> [*]
    REJECTED --> [*]
    INCORPORATED --> [*]

2.8 Reservation Engine REST API Reference Matrix

The table below catalogs the primary REST endpoints exposed by ReservationResource (com.dw.ngms.cis.web.rest.reservation.ReservationResource):

HTTP Verb Endpoint Handler Method Request Body / Parameters Statutory Function / Description
POST /api/reservation/draft createDraft ReservationDraftDto Initializes a new multi-step reservation application docket.
GET /api/reservation/draft/{draftId} getDraft draftId Retrieves complete draft state including steps, requests, and outcomes.
POST /api/reservation/draft/step addDraftStep ReservationDraftStepsDto Appends a sequential statutory step to an active reservation draft.
POST /api/reservation/draft/step/byOutcomeIds addDraftStepByOutcomeIds StepOutcomeChainDto Chains outputs of previous step as inputs to a new statutory step.
POST /api/reservation/processDraftAlgo processReservationDraftAlgo draftId, AlgoOutputType Executes algorithmic reservation in either STAGING or FINAL mode.
POST /api/reservation/saveDraftCheckout saveDraftCheckout ReservationCheckoutVm Validates checklists, locks draft, and triggers cis-workflow lodgement.
GET /api/reservation/pending getPendingReservations Pageable Queries pending reservation applications awaiting examiner scrutiny.
POST /api/reservation/approve approveReservation ReservationApprovalVm SG Examiner endpoint: triggers FINAL number commit and barcode PDF.
GET /api/reservation/downloadAckLetter/{id} downloadAckLetter reservationId Streams the certified PDF acknowledgement letter with QR/Barcodes.
POST /api/reservation/transfer transferReservation ReservationTransferDto Executes surveyor-to-surveyor reservation cession and issues letter.
POST /api/reservation/reDesignation reDesignateParcel ReDesignationRequestDto Executes parcel re-designation with historical audit linkage.
GET /api/reservation/expiry/check checkExpiringReservations None Triggered by scheduler: identifies reservations nearing statutory SLA lapse.

Module 3: Lodgement Engine — Statutory Survey Intake & Docket Architecture

The Lodgement Engine governs the formal submission, parent property verification, sectional title scheme modeling, fee calculation, batch issuance, and document packaging of cadastral survey records prepared by Professional Land Surveyors (PLS).

It bridges the statutory gap between provisional parcel reservations (Module 2) and formal examination scrutiny (Module 4).


3.1 Complete End-to-End Lifecycle Vector Architecture

Below is the verified end-to-end 6-stage lifecycle architecture of the Lodgement Engine, detailing reservation inheritance, multi-category document intake, Sectional Title scheme ingestion, participation quota calculations, batch numbering, and proforma tax invoicing:

Module 3: Lodgement Engine Statutory Survey Intake & Docket Architecture


3.2 Chronological Stage-by-Stage Lifecycle Walkthrough

%%{init: {'theme': 'base', 'themeVariables': { 'fontSize': '14px', 'fontFamily': 'Roboto', 'lineColor': '#1e40af' }}}%%
flowchart LR
    classDef stage fill:#EFF6FF,stroke:#1E40AF,stroke-width:2px,color:#1E3A8A;
    classDef scheme fill:#EEF2FF,stroke:#4338CA,stroke-width:2px,color:#312E81;
    classDef complete fill:#ECFDF5,stroke:#047857,stroke-width:2px,color:#064E3B;

    S1["1. Draft & Reservation Link<br/>(Import Outcome Parcels)"]:::stage
    S2["2. Survey Records Upload<br/>(Diagrams, Plans, S3)"]:::stage
    S3["3. Sectional Title & PQ<br/>(Units, Floors & Quotas)"]:::scheme
    S4["4. Fee Simulator & Proforma<br/>(Statutory Tariffs & PDF)"]:::stage
    S5["5. Payment & QC Checklists<br/>(Settlement Scrutiny)"]:::stage
    S6["6. Batch Issue & Handoff<br/>(Batch No & Level 1 Queue)"]:::complete

    S1 --> S2 --> S3 --> S4 --> S5 --> S6
Stage 1: Lodgement Draft Initiation & Statutory Reservation Inheritance
  • Objective: Establish an official lodgement docket and inherit pre-reserved parcel numbers and administrative records from Module 2.
  • Core Capabilities (LodgementDraftService, LodgementDraftStepsService):
    • Draft Docket Creation: Surveyors initiate a LodgementDraft record linked to their authenticated professional user ID.
    • Statutory Linkage (addStepsByReservationRef):
      • Ingests the Surveyor-General approved reservation reference (e.g., SG-RES-2026-00412).
      • Retrieves all underlying ReservationOutcome records (reserved parcel numbers, LPI strings, parent designations).
      • Automatically populates sequential LodgementDraftStep records with stepType = LODGED and creates corresponding LodgementDraftRequest entities.
      • Validates that the reservation reference has not expired according to statutory SLA timers.
Stage 2: Multi-Category Survey Records & Spatial Data Ingestion
  • Objective: Ingest the complete physical and digital dossier required by the Land Survey Act into high-performance object storage.
  • Document Ingestion Mechanics (LodgementResource.uploadReservationRequestDoc, LodgementDraftAnnexure):
    • Streams files directly into RustFS S3 (Port 9000) without local disk persistence leaks.
    • Supports statutory document categories:
      • Survey Diagrams (SG Dsg): Single or multi-page surveyor diagram PDFs detailing boundary beacons and line tables.
      • General Plans (GP): Multi-sheet layout plans for extensive township establishments and large agricultural subdivisions.
      • Working Plans & Field Books: Raw observational field notes, total station observation logs, and traverse closure sheets.
      • Beacon Coordinate CSVs / ASCII Data: Machine-readable coordinate tables for automated mathematical scrutiny.
      • Planning Consents (Annexures): Municipal SPLUMA authorizations, Environmental Impact Assessment (EIA) records, and consent affidavits.
Stage 3: Sectional Title (ST) Scheme Modeling & Participation Quota (PQ) Calculation
  • Objective: Model complex multi-tier architectural schemes and compute legally binding Participation Quotas.
  • Sectional Scheme Architecture (LodgementSchemeService, PqCalculatorService):
    • If the survey represents a Sectional Title development under the Sectional Titles Act, the surveyor models:
      • StScheme: Master scheme metadata, local authority jurisdiction, and registered name.
      • SchemeBuilding: Physical building structures, blocks, and architectural elevations.
      • SchemeSection: Individual residential apartments, commercial offices, or industrial units with defined floor areas (\(m^2\)).
      • SchemeEUA: Exclusive Use Areas (garages, private gardens, parking bays) and associated legend designations.
      • SectionalTitleCrossSection: Height profiles, cross-sections, and common property boundaries.
    • Automated PQ Apportionment: Invokes PqCalculatorService.calculate(schemeId) to compute mathematical quotas to 4 decimal places, enforcing \(\sum PQ = 100.0000\%\).
Stage 4: Fee Simulation & Proforma Tax Invoicing
  • Objective: Dynamically determine statutory examination tariffs and generate official proforma invoice documentation.
  • Tariff Mechanics (LodgementFeeSimulatorService, LodgementPerformaInvoiceGenerationService):
    • Computes examination fees based on the number of newly created parcels, portions, sectional title sections, and document page counts.
    • Compiles a formal tax proforma invoice PDF via Flying Saucer containing the Department of Agriculture, Land Reform and Rural Development (DALRRD) tax headers, statutory banking details, and EFT reference codes.
    • Triggers cis-emailer to dispatch the proforma invoice PDF directly to the surveyor.
Stage 5: Payment Settlement Scrutiny & Mandatory Quality Checklists
  • Objective: Validate financial settlement (or statutory fee exemption) and enforce surveyor compliance affidavits.
  • Settlement & Scrutiny Mechanics (LodgementDraftPayment, QcChecklistService):
    • Surveyors record payment details via POST /lodgement/addPayment, uploading EFT receipts or official government fee waiver certificates.
    • Evaluates statutory quality control responses (QcChecklistResponse), requiring the surveyor to attest that beacons have been physically placed and mathematical closures conform to statutory standards.
Stage 6: Statutory Batch Issuance, SG Document Number Allocation & Examination Handoff
  • Objective: Commit the lodgement submission into an official provincial examination batch and allocate statutory document identifiers.
  • Batch Promotion Mechanics (LodgementDraftService.issueBatch):
    • Provincial Batch Numbering:
      • Invokes allocateNextBatchNumber(provinceId).
      • Generates the official batch reference text: <batchNo>/<year> (e.g., 412/2026).
      • Persists record to LodgementBatch with isExamined = 0.
    • SG Document Numbering:
      • Iterates through all lodged documents and allocates sequential document numbers via getMaxDocumentNumber(provinceId, docType).
      • Generates official statutory document text: <prefix><docNo>/<year> (e.g., Dsg 89/2026).
      • Emits records into LodgementBatchSgDocument.
    • Acknowledgement Letter & Workflow Handoff:
      • Generates an official Barcode Acknowledgement Letter PDF (LodgementAcknowledgementLetterService).
      • Dispatches a process event to cis-workflow (Port 8090), handing the batch over to the Examination Engine (Module 4).

3.3 Deep Dive: Sectional Title (ST) Schemes & Participation Quota (PQ) Engine

The Sectional Title submodule in cis-api (com.dw.ngms.cis.service.lodgment.scheme.* and PqCalculatorService) models multi-story sectional properties and enforces strict statutory Participation Quota mathematics:

%%{init: {'theme': 'base', 'themeVariables': { 'fontSize': '13px', 'fontFamily': 'Roboto' }}}%%
flowchart TD
    classDef scheme fill:#EEF2FF,stroke:#4338CA,stroke-width:2px,color:#312E81;
    classDef comp fill:#EFF6FF,stroke:#2563EB,stroke-width:1.5px,color:#1E40AF;
    classDef calc fill:#FEF3C7,stroke:#D97706,stroke-width:2px,color:#78350F;

    SCHEME["StScheme<br/>(Scheme Name, Filing Year, Mother Erf)"]:::scheme

    subgraph ARCHITECTURE["Architectural Hierarchy"]
        BLDG["SchemeBuilding<br/>(Block Plans & Floors)"]:::comp
        SEC["SchemeSection<br/>(Unit 1..N, Floor Areas m²)"]:::comp
        EUA["SchemeEUA<br/>(Exclusive Use Areas: Garages, Yards)"]:::comp
        CROSS["CrossSectionDetails<br/>(Structural Elevations)"]:::comp
    end

    subgraph PQ_ENGINE["Participation Quota (PQ) Engine (PqCalculatorService)"]
        CLASS["Classify Section Types<br/>(Residential vs Non-Residential vs Mixed)"]:::calc
        FORMULA["Apply Statutory Quota Formula:<br/>PQ % = (Section Area / Total Area) * 100"]:::calc
        ROUND["Enforce 4 Decimal Precision<br/>(RoundingMode.HALF_UP)"]:::calc
        BALANCE["Invariant Check:<br/>Sum of all PQ = 100.0000%"]:::calc
    end

    SCHEME --> ARCHITECTURE
    BLDG --> SEC
    BLDG --> EUA
    BLDG --> CROSS
    SEC --> PQ_ENGINE
    CLASS --> FORMULA --> ROUND --> BALANCE
Participation Quota Mathematical Formulation

Under the Sectional Titles Act, the participation quota determines each unit owner's share in the common property, voting rights in the body corporate, and municipal rates apportionment:

\[ \text{PQ}_i = \left( \frac{\text{Floor Area of Section}_i}{\sum_{k=1}^N \text{Floor Area of Section}_k} \right) \times 100 \]
Variable / Parameter Mathematical Definition Statutory Cadastral Significance
\(\text{PQ}_i\) Participation Quota for section \(i\) Recorded to 4 decimal places (RoundingMode.HALF_UP).
\(\text{Floor Area}_i\) Floor area of section \(i\) (\(m^2\)) Extracted directly from SchemeSection.getFloorArea().
\(\sum_{k=1}^N \text{Floor Area}_k\) Aggregate floor area (\(m^2\)) Sum of all registered sections within the scheme.
Invariant Check \(\sum_{i=1}^N \text{PQ}_i = 100.0000\%\) Strict validation: if aggregate sum \(\ne 100.0000\%\), lodgement is blocked.
  • Residential Developments: The formula is evaluated strictly on relative floor area.
  • Mixed-Use Developments: The scheme defines a nonResidentialPercentage (e.g., 30% Commercial retail, 70% Residential apartments). PqCalculatorService apportionates the sub-quotas across residential and commercial sections independently so that the aggregate total strictly equals \(100.0000\%\).

3.4 Statutory Batch Issuance & SG Document Allocation Mechanics

When LodgementResource.issueBatch is executed, cis-api transitions transient draft structures into irrevocable statutory examination records:

sequenceDiagram
    autonumber
    actor PLS as Land Surveyor
    participant API as cis-api (:8089)
    participant Repo as LodgementBatchRepository
    participant DocRepo as LodgementBatchSgDocumentRepository
    participant DB as Oracle Database 23 (:1521)

    PLS->>API: POST /lodgement/issueBatch (draftId)
    API->>Repo: allocateNextBatchNumber(provinceId)
    Repo->>DB: Sequence Nextval for Province Batch Counter
    Repo-->>API: batchNo = 412
    API->>DB: INSERT INTO LodgementBatch (batchNumberText = '412/2026', isExamined = 0)

    loop For Each Lodged Document (Dsg, GP, Working Plan)
        API->>DocRepo: getMaxDocumentNumber(provinceId, docTypeItemId)
        DocRepo-->>API: maxDocNumber = 88
        API->>DB: INSERT INTO LodgementBatchSgDocument (docNumberText = 'Dsg 89/2026')
        API->>DB: UPDATE LodgementDraftDocument SET sgDocumentId = 89
    end

    API-->>PLS: Batch Issued (412/2026) & SG Document Numbers Assigned

3.5 Detailed Sequence Interaction Diagram

The sequence diagram below details the complete request-reply flow across all architectural tiers during survey lodgement:

sequenceDiagram
    autonumber
    actor PLS as Land Surveyor (PLS)
    participant BFF as cis-bff (:8080)
    participant API as cis-api (:8089)
    participant S3 as RustFS S3 (:9000)
    participant WF as cis-workflow (:8090)
    participant DB as Oracle Database 23 (:1521)
    participant Mail as Mailpit / SMTP (:1025)

    %% 1. Initiation
    PLS->>BFF: POST /api/lodgement/saveDraft
    BFF->>API: Forward with Bearer JWT
    API->>DB: Persist LodgementDraft
    API->>API: addStepsByReservationRef(refNo)
    API->>DB: Import ReservationOutcomes into LodgementDraftSteps
    API-->>PLS: Draft Initialized & Reserved Steps Linked

    %% 2. File Upload
    PLS->>BFF: POST /api/lodgement/uploadReservationRequestDoc (Multipart)
    BFF->>API: Stream Survey Plans & Shapefiles
    API->>S3: PutObject (RustFS S3 :9000)
    S3-->>API: Blob URI & Checksum
    API->>DB: Persist LodgementDraftDocument
    API-->>PLS: Document Upload Verified

    %% 3. Invoicing
    PLS->>BFF: POST /api/lodgement/processInvoice (draftId)
    BFF->>API: Fee Simulation Request
    API->>API: LodgementFeeSimulatorService.calculate()
    API->>DB: Persist InvoicePerforma
    API->>Mail: Dispatch Proforma Tax Invoice PDF
    API-->>PLS: Invoice Issued (INV-2026-0412)

    %% 4. Issue Batch
    PLS->>BFF: POST /api/lodgement/issueBatch (draftId)
    BFF->>API: Final Batch Promotion
    API->>DB: Commit LodgementBatch (412/2026) & SG Document Numbers
    API->>API: LodgementAcknowledgementLetterService.generatePdf()
    API->>S3: Upload Barcode Ack Letter PDF
    API->>WF: Initiate Examination Workflow Process
    WF-->>API: Workflow State = PENDING_LEVEL_1_EXAMINATION
    API-->>PLS: Lodgement Complete (Ack Letter Ready)

3.6 State Machine: Lodgement Batch & Document Progression

stateDiagram-v2
    [*] --> DRAFT_INTAKE: Surveyor creates lodgement draft
    DRAFT_INTAKE --> RESERVATION_LINKED: addStepsByReservationRef()
    RESERVATION_LINKED --> DOCUMENTS_STAGED: Upload diagrams, plans & shapefiles
    DOCUMENTS_STAGED --> SCHEME_MODELING: Sectional Title units & PQ calculated
    SCHEME_MODELING --> PROFORMA_ISSUED: Tariff computed & invoice dispatched
    PROFORMA_ISSUED --> SETTLED: Proof of payment / exemption uploaded
    SETTLED --> BATCH_ISSUED: issueBatch() assigns Batch No & SG Doc IDs
    BATCH_ISSUED --> PENDING_EXAMINATION: Ingested into cis-workflow queue
    PENDING_EXAMINATION --> [*]

3.7 Lodgement Engine REST API Reference Matrix

The table below catalogs primary REST endpoints exposed by LodgementResource and LodgementSchemeResource:

HTTP Verb Endpoint Handler Method Request Body / Parameters Statutory Function / Description
POST /api/lodgement/saveDraft saveLodgementDraft LodgementDraftDto Initializes or updates a survey lodgement application draft.
GET /api/lodgement/draft/{draftId} getLodgementDraft draftId Retrieves complete draft state, steps, and document summaries.
POST /api/lodgement/addStepsByResRef addStepsByReservationRef referenceNo, draftId Inherits pre-reserved outcomes from Module 2 into lodgement steps.
POST /api/lodgement/uploadReservationRequestDoc uploadReservationRequestDoc Multipart LodgementDraftDocumentDto Ingests survey diagrams, general plans, and coordinate tables to S3.
POST /api/lodgement/addAnnexure saveLodgementDocument Multipart LodgementDraftAnnexureDto Attaches town planning SPLUMA consents and legal affidavits.
POST /api/lodgement/scheme/saveScheme saveScheme SchemeSchemeDto Models Sectional Title master scheme, mother erf, and local authority.
POST /api/lodgement/scheme/saveBuilding saveSchemeBuilding SchemeBuildingDto Records architectural buildings, floor plans, and cross-sections.
POST /api/lodgement/scheme/saveSection saveSchemeSection SchemeSectionDto Ingests individual sectional units, floor areas (\(m^2\)), and unit types.
POST /api/lodgement/scheme/calculatePQ calculatePQ schemeId Invokes PqCalculatorService to apportion statutory participation quotas.
POST /api/lodgement/processInvoice processInvoice draftId Computes dynamic statutory examination tariffs.
GET /api/lodgement/generatePerformaInvoice generatePdf draftId Compiles official DALRRD Flying Saucer tax proforma invoice PDF.
POST /api/lodgement/addPayment addPayment LodgementDraftPaymentDto Records EFT settlement receipt or statutory exemption certificate.
POST /api/lodgement/issueBatch issueBatch LodgementBatchDto Assigns provincial batch number (batchNo/year), SG doc numbers, and triggers workflow.
GET /api/lodgement/getLdgDraftAcknowledement getLodgementDraftAcknowledgementLetter draftId Streams certified PDF acknowledgement letter with barcodes.

Module 4: Examination Engine — Technical Cadastral Scrutiny & Statutory Stamping

The Examination Engine is the core statutory quality assurance and legal verification bastion of the Cadastral Information System (CIS). Mandated by the Land Survey Act, no land parcel, sectional title scheme, or general plan can be registered in the Deeds Office without formal technical examination, coordinate verification, caveat clearance, and official digital stamping by the Surveyor-General (SG).

The engine operates a distributed two-tier examination workflow coordinated via ShedLock schedulers, executes automated mathematical coordinate consistency algorithms, checks legal caveats, and applies cryptographically verifiable digital approval seals.


4.1 Complete End-to-End Lifecycle Vector Architecture

Below is the verified end-to-end 6-stage lifecycle architecture of the Examination Engine, illustrating automated ShedLock queue allocation, Phase 1 mathematical coordinate scrutiny, Phase 2 senior quality review, caveat clearance, and digital stamping:

Module 4: Examination Engine Technical Cadastral Scrutiny & Statutory Stamping


4.2 Chronological Stage-by-Stage Lifecycle Walkthrough

%%{init: {'theme': 'base', 'themeVariables': { 'fontSize': '14px', 'fontFamily': 'Roboto', 'lineColor': '#7e22ce' }}}%%
flowchart LR
    classDef stage fill:#FAF5FF,stroke:#7E22CE,stroke-width:2px,color:#581C87;
    classDef math fill:#FEF3C7,stroke:#D97706,stroke-width:2px,color:#78350F;
    classDef query fill:#FFF7ED,stroke:#EA580C,stroke-width:2px,color:#9A3412;
    classDef complete fill:#ECFDF5,stroke:#047857,stroke-width:2px,color:#064E3B;

    S1["1. Automated Intake<br/>(ShedLock Scheduler)"]:::stage
    S2["2. Math Consistency<br/>(ΔY, ΔX & Gauss Area)"]:::math
    S3["3. Phase 1 Checklists<br/>(Docket Tree & QC)"]:::stage
    S4["4. Scrutiny Verdict<br/>(Query vs Phase 2)"]:::query
    S5["5. Phase 2 Senior Audit<br/>(Caveat & Legal Review)"]:::stage
    S6["6. SG Digital Stamping<br/>(Seal, Signature & S3)"]:::complete

    S1 --> S2 --> S3 --> S4 --> S5 --> S6
Stage 1: Automated Batch Intake & Distributed ShedLock Task Allocation
  • Objective: Automatically ingest pending survey batches emitted by Module 3 and allocate them across examination officers without race conditions.
  • Scheduling Mechanics (ExaminationFirstLavelScheduler, LodgementBatchRecordsHandler):
    • Utilizes distributed ShedLock locking (@SchedulerLock(name = "examination_first_label_scheduler")) across cluster nodes.
    • Scans LodgementBatch for records with isExamined = 0.
    • Allocates dossiers to first-level cadastral examiners based on provincial jurisdiction, workload balance, and survey complexity.
    • Marks batch records as under scrutiny and populates the Level 1 Examiner work queue (/examination/firstLevelListing).
Stage 2: Mathematical Coordinate Consistency Algorithm Scrutiny
  • Objective: Automate the mathematical verification of survey beacons, boundary lines, coordinate differences, polygon misclosures, and area tolerances.
  • Algorithm Mechanics (ConsistencyCheckAlgorithm):
    • Ingests beacon coordinates and line tables (SgdataParcelLineGranular) uploaded by the surveyor.
    • Evaluates coordinate deltas (\(\Delta Y, \Delta X\)), line lengths, and bearings against national coordinate reference systems (Lo meridians / WGS84).
    • Calculates Gauss polygon trapezoidal assessed area and verifies that the difference between surveyor-declared area and assessed area falls within Land Survey Act statutory limits.
    • Computes total perimeter and linear misclosure \(\sqrt{(\sum \Delta Y)^2 + (\sum \Delta X)^2}\). If misclosure exceeds Class A (Urban) or Class B (Rural) thresholds, emits ConsistencyCheckException.
Stage 3: Phase 1 Quality Control Checklists & Hierarchical Docket Scrutiny
  • Objective: Perform comprehensive technical scrutiny covering statutory boundary rules, beacon descriptions, and planning consents.
  • Scrutiny Capabilities (DocketTreeBuilderService, QcChecklistService):
    • Docket Tree Builder: Structures the multi-page submission into an interactive hierarchy (DocketTree \(\rightarrow\) DocketGroupNode \(\rightarrow\) DocketGroupRoleNode \(\rightarrow\) DocketAttributeNode).
    • Statutory Checklists: Examiners execute 40+ mandatory compliance checks covering beacon witness marks, road reserve alignments, servitude widths, and boundary continuity.
Stage 4: Phase 1 Examination Verdict — Formal Query vs Phase 2 Promotion
  • Objective: Issue statutory query notes to the land surveyor or promote technically sound batches to senior review.
  • Workflow Branching:
    • If Defects or Inconsistencies Detected:
      • Examiner issues formal Query Notes detailing mathematical or boundary discrepancies.
      • Compiles a Query Notice PDF via RelodgementLetterGenerationService.
      • Transitions batch state to QUERIED and routes into Module 5 (Relodgement Engine).
    • If Technical Scrutiny Passes:
      • Examiner endorses Phase 1 compliance.
      • Batch transitions to PHASE_1_APPROVED and is automatically promoted to the Senior Examiner Queue.
Stage 5: Phase 2 Senior Examiner Quality Assurance & Cadastral Caveats Scrutiny
  • Objective: Senior cadastral officer audit, legal conflict detection, and caveat clearance.
  • Senior Review Pipeline (ExaminationSecondLabelScheduler, SgCaveats):
    • Coordinated by distributed scheduler examination_second_label_scheduler.
    • Cadastral Caveat Verification: Queries SgCaveats to ensure that no pending land expropriations, court interdicts, boundary disputes, or restitution claims exist on the subject land.
    • Cross-Boundary Conflict Scans: Performs spatial collision scans against contiguous approved parcels in cis-search.
    • Senior examiner signs off on the quality review dossier.
Stage 6: Surveyor-General Digital Stamping, Statutory Sign-off & Cadastre Promotion
  • Objective: Apply official Surveyor-General approval seals, certify legal diagrams, and promote parcels to the master land registry.
  • Stamping & Master Promotion Mechanics (StampingService, ExaminationStamping):
    • Digital Stamping Microservice:
      • Calls the digital stamping service (Port 8000).
      • Embeds the official SG coat of arms seal, statutory approval text, approval date, and SG digital signature directly onto the approved diagram PDF.
    • Master Record Promotion:
      • Archives the digitally stamped PDF in RustFS S3 (Port 9000).
      • Promotes provisional parcel records in SgdataParcels from provisional to APPROVED / ACTIVE.
      • Updates parent property remainder balances in SgdataParentChild.
      • Dispatches completion notifications and certified docket download links to the surveyor via cis-emailer.

4.3 Deep Dive: Mathematical Consistency Algorithm (ConsistencyCheckAlgorithm)

ConsistencyCheckAlgorithm (com.dw.ngms.cis.service.examination.consistency.ConsistencyCheckAlgorithm) automates the statutory mathematical verification of cadastral boundary coordinates:

%%{init: {'theme': 'base', 'themeVariables': { 'fontSize': '13px', 'fontFamily': 'Roboto' }}}%%
flowchart TD
    classDef input fill:#EFF6FF,stroke:#2563EB,stroke-width:1.5px,color:#1E40AF;
    classDef calc fill:#FEF3C7,stroke:#D97706,stroke-width:2px,color:#78350F;
    classDef test fill:#F3E8FF,stroke:#7E22CE,stroke-width:2px,color:#581C87;
    classDef pass fill:#ECFDF5,stroke:#059669,stroke-width:2px,color:#065F46;
    classDef fail fill:#FEF2F2,stroke:#DC2626,stroke-width:2px,color:#991B1B;

    IN["Input: SgdataParcelLineGranular<br/>(Beacon Coordinates Y, X)"]:::input

    subgraph STEP1["1. Coordinate Difference & Bearing Calculus"]
        DYDX["calculateDyDx():<br/>ΔY = Y(to) - Y(from)<br/>ΔX = X(to) - X(from)"]:::calc
        DIST["Distance = √(ΔY² + ΔX²)<br/>Bearing = atan2(ΔY, ΔX)"]:::calc
        PERIM["calculatePerimeter():<br/>Perimeter = ∑ Distance"]:::calc
        DYDX --> DIST --> PERIM
    end

    subgraph STEP2["2. Assessed Area Calculus"]
        GAUSS["calculateAssessedArea():<br/>Area = 0.5 * |∑ (Yi + Yi+1) * (Xi+1 - Xi)|"]:::calc
        AREATOL["calculateAreaTolerance():<br/>Statutory tolerance based on parcel class"]:::calc
        GAUSS --> AREATOL
    end

    subgraph STEP3["3. Misclosure Calculus"]
        MISC["calculateClosureTolerance():<br/>Misclosure = √((∑ΔY)² + (∑ΔX)²)<br/>Allowable = K * √(Perimeter)"]:::calc
    end

    IN --> STEP1
    STEP1 --> STEP2
    STEP2 --> STEP3

    subgraph VERDICT["4. Statutory Verdict Determination"]
        CHECK{"Misclosure ≤ Tolerance<br/>AND<br/>|Declared - Assessed| ≤ AreaTol?"}:::test
        PASS["ConsistencyCheckStatus.SUCCESS<br/>(Coordinates Statutorily Valid)"]:::pass
        FAIL["ConsistencyCheckStatus.FAILED<br/>(Emits ConsistencyCheckException)"]:::fail
    end

    STEP3 --> CHECK
    CHECK -->|Yes| PASS
    CHECK -->|No| FAIL
Mathematical Formulation & Algorithmic Verification

ConsistencyCheckAlgorithm executes three sequential mathematical operations on surveyor-submitted beacon coordinates (SgdataParcelLineGranular):

1. Coordinate Differences, Line Distances & Bearings
\[ \Delta Y = Y_{\text{to}} - Y_{\text{from}}, \quad \Delta X = X_{\text{to}} - X_{\text{from}} \]
\[ \text{Distance} = \sqrt{\Delta Y^2 + \Delta X^2}, \quad \text{Bearing} = \operatorname{atan2}(\Delta Y, \Delta X) \]
\[ \text{Perimeter} = \sum_{k=1}^M \text{Distance}_k \]
Metric Programmatic Method Formula / Implementation Statutory Role
Coordinate Delta (\(\Delta Y, \Delta X\)) calculateDyDx() \(Y_{\text{to}} - Y_{\text{from}}\), \(X_{\text{to}} - X_{\text{from}}\) Evaluates easting/northing displacement per boundary segment.
Segment Length calculatePerimeter() \(\sqrt{\Delta Y^2 + \Delta X^2}\) Verifies physical boundary distance between consecutive beacons.
Line Bearing calculateAngle() \(\operatorname{atan2}(\Delta Y, \Delta X)\) Verifies statutory angular direction from true south.
Total Perimeter calculatePerimeter() \(\sum \text{Distance}\) Sum of all perimeter boundary segments for tolerance scaling.
2. Gauss Trapezoidal Polygon Area Formulation
\[ \text{Assessed Area} = \frac{1}{2} \left| \sum_{i=1}^n (Y_i + Y_{i+1}) (X_{i+1} - X_i) \right| \]
Variable / Function Definition Calculation Logic
calculateAssessedArea() Gauss coordinate polygon area (\(m^2\)) Computed mathematically from ordered \((Y, X)\) beacon coordinates.
inputArea Surveyor-declared diagram area Declared area extracted from uploaded survey diagram docket.
calculateAreaTolerance() Maximum permissible area error Land Survey Act statutory limit based on parcel size and class.
Area Verification Rule \|inputArea - assessedArea\| <= areaToleranceLimit If area discrepancy exceeds tolerance, ConsistencyOutcome fails.
3. Linear Coordinate Misclosure & Closure Tolerance
\[ \text{Misclosure} = \sqrt{\left(\sum \Delta Y\right)^2 + \left(\sum \Delta X\right)^2} \]
\[ \text{Allowable Closure Tolerance} = C \times \sqrt{\text{Perimeter}} \]
Cadastral Survey Class Tolerance Constant (\(C\)) Maximum Permissible Linear Misclosure Applicable Land Category
Class A (Urban Cadastre) \(C = 0.015\) \(0.015 \times \sqrt{\text{Perimeter}}\) meters Urban erven, township stands, commercial parcels.
Class B (Rural Cadastre) \(C = 0.030\) \(0.030 \times \sqrt{\text{Perimeter}}\) meters Agricultural holdings, rural farm portions, state land.
Verification Rule \(\text{Misclosure} \le \text{Closure Tolerance}\) Emits ConsistencyCheckStatus.SUCCESS if within limit, else FAILED.

4.4 Two-Tier Examination Workflows & ShedLock Schedulers

CIS enforces strict segregation of duties between initial technical examination and senior administrative quality approval:

Feature / Responsibility Phase 1: Technical Scrutiny Phase 2: Senior Quality Review
Scheduler Class ExaminationFirstLavelScheduler ExaminationSecondLabelScheduler
Distributed ShedLock Key examination_first_label_scheduler examination_second_label_scheduler
Queue Filter Criteria isExamined = 0 (Unexamined batches) isExamined = 1 AND isSecondLevel = 0
Target Role / Actor Cadastral Examination Officer Senior Examiner / Deputy Surveyor-General
Primary Scrutiny Focus Mathematical consistency, coordinate closure, beacon accuracy, docket completeness. Boundary disputes, caveat clearances, legal consistency, town planning authorizations.
Permitted Outcomes Technical Approval (promote to Phase 2) OR Query Notice (reject to PLS). Final Statutory SG Approval OR Query Escalation.

4.5 Digital Stamping Microservice & Statutory Seal Pipeline

Upon final Surveyor-General approval, cis-api invokes StampingService to transform the uncertified diagram PDF into a legally registered, sealed cadastral document:

sequenceDiagram
    autonumber
    actor SG as Surveyor-General Officer
    participant API as cis-api (:8089)
    participant StampSvc as Stamping Service (:8000)
    participant S3 as RustFS S3 (:9000)
    participant DB as Oracle Database 23 (:1521)
    participant Mail as Mailpit (:1025)

    SG->>API: POST /examination/docs/signed (batchId, workflowId)
    API->>DB: Query Approved LodgementBatchSgDocuments

    loop For Each Diagram PDF
        API->>S3: Retrieve Raw Diagram PDF
        S3-->>API: Raw PDF Binary Stream
        API->>StampSvc: POST /api/stamp (PDF + Stamp Metadata)
        Note over StampSvc: Embeds Official SG Coat of Arms Seal,<br/>Approval Date, SG Name & Digital Signature
        StampSvc-->>API: Digitally Stamped Diagram PDF
        API->>S3: PutObject (Overwrites with Stamped Diagram)
        API->>DB: Record ExaminationStamping Audit Log
    end

    API->>DB: Update SgdataParcels (Status = APPROVED)
    API->>Mail: Dispatch Approval Notice with Stamped Docket to PLS
    API-->>SG: Statutory Examination Complete & Parcels Registered

4.6 State Machine: Cadastral Examination Docket State Transitions

stateDiagram-v2
    [*] --> PENDING_ALLOCATION: Lodgement Batch Issued (isExamined = 0)
    PENDING_ALLOCATION --> LEVEL_1_ASSIGNED: ExaminationFirstLavelScheduler assigns examiner
    LEVEL_1_ASSIGNED --> MATH_CONSISTENCY_CHECK: ConsistencyCheckAlgorithm executed
    MATH_CONSISTENCY_CHECK --> LEVEL_1_SCRUTINY: Mathematical closures pass
    MATH_CONSISTENCY_CHECK --> QUERIED: Misclosure exceeds tolerance
    LEVEL_1_SCRUTINY --> LEVEL_1_APPROVED: Examiner verifies checklists & docket tree
    LEVEL_1_SCRUTINY --> QUERIED: Boundary or documentation defects detected
    QUERIED --> RELODGEMENT_QUEUE: Routed to Module 5 (Relodge)
    LEVEL_1_APPROVED --> LEVEL_2_ASSIGNED: ExaminationSecondLabelScheduler assigns Senior Officer
    LEVEL_2_ASSIGNED --> CAVEAT_SCRUTINY: SgCaveats & interdicts checked
    CAVEAT_SCRUTINY --> FINAL_APPROVED: Senior Officer endorses batch
    CAVEAT_SCRUTINY --> QUERIED: Legal conflict detected
    FINAL_APPROVED --> DIGITALLY_STAMPED: StampingService embeds SG seals & signs PDF
    DIGITALLY_STAMPED --> MASTER_CADASTRE_ACTIVE: SgdataParcels promoted to live registry
    MASTER_CADASTRE_ACTIVE --> [*]

4.7 Examination Engine REST API Reference Matrix

The table below catalogs primary REST endpoints exposed by ExaminationResource:

HTTP Verb Endpoint Handler Method Request Body / Parameters Statutory Function / Description
POST /api/examination/firstLevelListing getFirstLabelListing ExaminationListingVm Retrieves worklist queue for Phase 1 Technical Examiners.
POST /api/examination/triggerFirstLevel triggerManually ExaminationFirstLavelTriggerTaskVm Manually triggers Level 1 examiner task assignment.
POST /api/examination/secondLevelListing getSecondLabelListing ExaminationListingVm Retrieves worklist queue for Phase 2 Senior Examiners.
POST /api/examination/triggerSecondLevel triggerSecondLabel ExaminationSecondLavelTriggerTaskVm Manually triggers Level 2 senior examiner task assignment.
GET /api/examination/doc/consistencySummary consistencySummary sgDocumentId Executes ConsistencyCheckAlgorithm and returns \(\Delta Y, \Delta X\), closure and area analysis.
GET /api/examination/doc/areaDetails getAreaCalculatedDetails sgDocumentId Returns Gauss assessed area vs surveyor-declared diagram area.
POST /api/examination/doc/data/upload uploadCsvData Multipart CSV / ASCII Ingests raw coordinate beacon and parcel boundary line tables.
GET /api/examination/docket/getTreeConfig getConfiguration docketId Builds and returns interactive hierarchical DocketTree.
POST /api/examination/doc/stamp addStamp ExaminationStampingDto Applies digital SG approval seal and signature stamp to diagram PDF.
POST /api/examination/doc/outcome addExamOutcome ExaminationOutcomeDto Records Phase 1 or Phase 2 examiner verdict (Approve, Query, Reject).
GET /api/examination/docs/signed signedDocuments batchId, workflowId Promotes examined batch to master registry and finalizes SG sign-off.

Module 5: Relodgement Engine — Examiner Query Resolution & Differential Scrutiny

The Relodgement Engine governs the formal statutory defect resolution and resubmission workflow when a cadastral survey submission is queried or returned by a Surveyor-General examiner in Module 4.

Rather than forcing the surveyor to recreate a survey dossier from scratch, the engine establishes an immutable parent-child draft lineage (parentDraftId, firstParentDraftId), generates differential comparison trees (LodgementTree), executes targeted differential boundary coordinate re-scrutiny, and fast-tracks the amended batch directly back to the original assigned examiner in cis-workflow.


5.1 Complete End-to-End Lifecycle Vector Architecture

Below is the verified end-to-end 6-stage lifecycle architecture of the Relodgement Engine, detailing defect intake, parent-child draft lineage, differential tree modeling, fee adjustments, and fast-track examiner re-routing:

Module 5: Relodgement Engine Lifecycle & Query Resolution Architecture


5.2 Chronological Stage-by-Stage Lifecycle Walkthrough

%%{init: {'theme': 'base', 'themeVariables': { 'fontSize': '14px', 'fontFamily': 'Roboto', 'lineColor': '#d97706' }}}%%
flowchart LR
    classDef stage fill:#FEFCE8,stroke:#D97706,stroke-width:2px,color:#78350F;
    classDef action fill:#EFF6FF,stroke:#2563EB,stroke-width:2px,color:#1E40AF;
    classDef complete fill:#ECFDF5,stroke:#047857,stroke-width:2px,color:#064E3B;

    S1["1. Query Receipt & Notice<br/>(Examiner Query Notes PDF)"]:::stage
    S2["2. Relodge Docket Init<br/>(Child Draft & Lineage)"]:::action
    S3["3. Tree Diff & Rectification<br/>(LodgementTree & S3 Upload)"]:::stage
    S4["4. Differential Scrutiny<br/>(Math & Tariff Delta)"]:::stage
    S5["5. Relodge Batch Commit<br/>(Operations.RELODGE)"]:::complete
    S6["6. Fast-Track Examiner Sign<br/>(Original Examiner Worklist)"]:::complete

    S1 --> S2 --> S3 --> S4 --> S5 --> S6
Stage 1: Examiner Query Notice & Defect Citations Receipt
  • Objective: Ingest specific technical, mathematical, or procedural defects identified during Module 4 examination and place the survey batch in a legally governed query state.
  • Query Notice Pipeline (RelodgementLetterGenerationService, getRelodgementLetter):
    • When a Level 1 or Level 2 examiner rejects a batch, cis-workflow sets batch status to QUERIED (StatusItemId = 1528L).
    • Compiles an official Query Notes PDF containing itemized examiner comments (e.g., coordinate misclosure exceeding Class A limits, unclosed parcel lines, missing municipal consent endorsements).
    • Dispatches the query notice to the surveyor via cis-emailer and starts the statutory response SLA timer (e.g., 60 statutory days to rectify).
Stage 2: Child Relodgement Draft Docket Creation & Lineage Preservation
  • Objective: Initialize a child relodgement draft that inherits all approved historical context while preserving an unalterable audit trail.
  • Lineage Mechanics (RelodgementService.addRelodge):
    • Surveyor triggers POST /api/relodgement/addRelodge.
    • Creates a new LodgementDraft record with isActive = 1.
    • Links parentDraftId to the immediate queried submission and firstParentDraftId to the root lodgement, preserving complete submission genealogy across multiple query iterations.
    • Automatically copies applicant metadata, professional surveyor council numbers, delivery methods, and statutory file references.
Stage 3: Hierarchical LodgementTree Comparison & Rectification
  • Objective: Present the surveyor with an interactive differential tree comparing original documents against queried items, allowing targeted uploads of rectified files.
  • Tree Comparison Engine (RelodgementService.getLodgementTree):
    • Builds a hierarchical LodgementTree structured as: Root \(\rightarrow\) LodgementDraftStep \(\rightarrow\) LodgementSgNo \(\rightarrow\) Document.
    • Differentiates items by granular status:
      • Status 1528 (QUERIED): Original document flagged with examiner defects.
      • Status 1928 (LODGED): Newly uploaded replacement diagram, corrected coordinate table, or supplementary consent affidavit.
    • Streams rectified replacement files into RustFS S3 (Port 9000) and associates them with sgDocumentId.
Stage 4: Differential Boundary Validation & Tariff Re-Calculation
  • Objective: Validate only the modified boundary vectors without forcing re-examination of unchanged parcels, and compute fee deltas.
  • Differential Validation Mechanics:
    • Re-runs ConsistencyCheckAlgorithm specifically on amended polygon lines (SgdataParcelLineGranular).
    • Evaluates whether revised beacon coordinates resolve the original linear misclosure and polygon area discrepancies.
    • Fee Adjustments (LodgementFeeSimulatorService):
      • If the rectified plan alters parcel counts or portion boundaries, dynamically recalculates examination tariffs and issues a supplementary proforma invoice. Minor technical corrections incur no additional statutory fees.
Stage 5: Relodgement Batch Commitment & Lifecycle Event Dispatch
  • Objective: Seal the amended survey dossier, update document statuses, and dispatch legal acknowledgement dockets.
  • Batch Re-Submission (RelodgementService.relodgeBatch):
    • Surveyor submits LodgementOperations with action RELODGE.
    • Updates document statuses from QUERIED to active LODGED.
    • Generates an official Relodgement Acknowledgement Letter PDF (RelodgementAcknowledgementNotification) bearing barcodes and re-filing timestamps.
    • Dispatches process event to cis-workflow (Port 8090).
Stage 6: Fast-Track Routing to Original Examiner & Statutory Approval
  • Objective: Bypass initial triage queues and route the rectified batch directly back to the desk of the examiner who authored the original query.
  • Intelligent Workflow Routing:
    • cis-workflow uses the parent batch metadata to assign the task directly to the original examiner's active worklist.
    • The examiner reviews only the differential comparison diff (LodgementTree), verifying that each itemized query citation has been satisfied.
    • Upon endorsement, the batch bypasses Phase 1 triage and routes directly to statutory digital stamping (StampingService) and master cadastre promotion.

5.3 Detailed Sequence Interaction Diagram

sequenceDiagram
    autonumber
    actor PLS as Land Surveyor (PLS)
    participant BFF as cis-bff (:8080)
    participant API as cis-api (:8089)
    participant S3 as RustFS S3 (:9000)
    participant WF as cis-workflow (:8090)
    participant DB as Oracle Database 23 (:1521)
    participant Exam as Assigned SG Examiner

    %% 1. Query Notification
    WF->>API: Query Callback (Batch 412/2026 QUERIED)
    API->>DB: Set Status = 1528 (QUERIED)
    API-->>PLS: Examiner Query Notice PDF Issued

    %% 2. Relodge Creation
    PLS->>BFF: POST /api/relodgement/addRelodge (parentDraftId = 5041)
    BFF->>API: Initialize Child Relodgement Draft
    API->>DB: INSERT INTO LodgementDraft (parentDraftId, firstParentDraftId)
    DB-->>API: childDraftId = 5099
    API-->>PLS: Relodgement Draft Ready

    %% 3. Tree Diff & File Upload
    PLS->>BFF: GET /api/relodgement/getLodgementTree?draftId=5099
    API-->>PLS: Return LodgementTree (Itemized Defects)
    PLS->>BFF: POST /api/lodgement/updateDoc (Rectified Diagram PDF)
    BFF->>API: Upload Replacement File
    API->>S3: PutObject (RustFS S3 :9000)
    API->>DB: Link new document to sgDocumentId
    API-->>PLS: Document Replacement Staged

    %% 4. Re-Submission & Fast Track Routing
    PLS->>BFF: POST /api/relodgement/relodge (LodgementOperations.RELODGE)
    BFF->>API: Execute Batch Relodgement
    API->>DB: Update Status to 1928 (LODGED)
    API->>WF: Re-activate Workflow (Direct Route to Examiner)
    WF->>Exam: Push directly into Examiner's Assigned Queue
    API-->>PLS: Relodgement Acknowledgement Issued

5.4 State Machine: Relodgement Query & Re-Submission Progression

stateDiagram-v2
    [*] --> BATCH_QUERIED: Module 4 Examiner issues Query Notes
    BATCH_QUERIED --> CHILD_DRAFT_CREATED: PLS clicks 'Relodge' (addRelodge)
    CHILD_DRAFT_CREATED --> TREE_INSPECTION: getLodgementTree() builds diff
    TREE_INSPECTION --> DOCUMENTS_RECTIFIED: Corrected diagrams & tables uploaded
    DOCUMENTS_RECTIFIED --> DIFFERENTIAL_VALIDATION: ConsistencyCheckAlgorithm re-run
    DIFFERENTIAL_VALIDATION --> RELODGE_COMMITTED: relodgeBatch(RELODGE) executed
    DOCUMENTS_RECTIFIED --> ABANDONED: cancelBatch(CANCEL) executed
    ABANDONED --> CANCELLED_TERMINAL: Sequences freed & docket closed
    RELODGE_COMMITTED --> FAST_TRACK_EXAMINER: Directly assigned to original reviewer
    FAST_TRACK_EXAMINER --> APPROVED_STAMPED: Queries resolved & diagram signed
    FAST_TRACK_EXAMINER --> BATCH_QUERIED: Secondary query issued
    APPROVED_STAMPED --> [*]
    CANCELLED_TERMINAL --> [*]

5.5 Relodgement Engine REST API Reference Matrix

HTTP Verb Endpoint Handler Method Request Body / Parameters Statutory Function / Description
POST /api/relodgement/addRelodge addRelodgeEntity LodgementDraftDto Initializes child relodgement draft linked to parent draft ID.
POST /api/relodgement/updateRelodge updateRelodge LodgementDraftDto Updates child relodgement draft attributes and delivery options.
GET /api/relodgement/getLodgementTree getLodgementTree draftId Builds hierarchical differential tree contrasting queried vs amended records.
POST /api/relodgement/relodge relodgeBatch LodgementOperations Commits rectified submission and re-triggers workflow to original examiner.
POST /api/relodgement/cancel cancelBatch LodgementOperations Abandons queried survey application, deactivating draft and freeing numbers.
POST /api/relodgement/deleteStep deleteStep stepId Deletes a queried statutory step, recalculating survey topology and fees.

Module 6: Maintenance Engine — Statutory Cadastral Alterations & Outcome Notices

The Maintenance Engine governs post-approval statutory changes to already registered cadastral land parcels, general plans, and territorial boundaries. Unlike new land surveys (Modules 2, 3, and 4), maintenance actions represent statutory administrative proclamations under municipal planning legislation (e.g., SPLUMA), High Court interdicts, land restitution orders, and provincial gazettes.

The engine administers 12 statutory alteration categories (MaintenanceReason), manages multi-step maintenance drafts, enforces procedural compliance checklists, and generates certified Flying Saucer outcome notice PDFs dispatched directly to the Registrar of Deeds and municipal authorities.


6.1 Complete End-to-End Lifecycle Vector Architecture

Below is the verified end-to-end 6-stage lifecycle architecture of the Maintenance Engine, illustrating alteration initiation, gazette proclamation uploads, statutory checklists, SG officer scrutiny, and deeds outcome dockets:

Module 6: Maintenance Engine Lifecycle & Cadastral Alteration Architecture


6.2 Chronological Stage-by-Stage Lifecycle Walkthrough

%%{init: {'theme': 'base', 'themeVariables': { 'fontSize': '14px', 'fontFamily': 'Roboto', 'lineColor': '#0d9488' }}}%%
flowchart LR
    classDef stage fill:#F0FDFA,stroke:#0D9488,stroke-width:2px,color:#134E4A;
    classDef action fill:#EFF6FF,stroke:#2563EB,stroke-width:2px,color:#1E40AF;
    classDef complete fill:#ECFDF5,stroke:#047857,stroke-width:2px,color:#064E3B;

    S1["1. Alteration Initiation<br/>(MaintenanceReason)"]:::stage
    S2["2. Steps & Gazette Upload<br/>(Legal Evidence & Plans)"]:::action
    S3["3. Checklists & Tariffs<br/>(Procedural Audit & PDF)"]:::stage
    S4["4. Lodgement Checkout<br/>(Settlement & Workflow)"]:::stage
    S5["5. SG Officer Scrutiny<br/>(Statutory Examination)"]:::complete
    S6["6. Outcome Notice Issued<br/>(Deeds & Municipal Notice)"]:::complete

    S1 --> S2 --> S3 --> S4 --> S5 --> S6
Stage 1: Maintenance Application Initiation & Reason Selection
  • Objective: Initiate an official cadastral maintenance docket linked to a specific statutory legal trigger.
  • Core Capabilities (MaintenanceDraftService.saveDraft, MaintenanceReason):
    • Municipal town planners, conveyancers, or professional surveyors initiate a MaintenanceDraft.
    • Enforces selection of an authoritative statutory MaintenanceReason:
      • EXCISION (2486L): Carving agricultural holding land into urban township cadastre.
      • PUBLIC_PLACE_CLOSURE (2489L): Municipal closure of public parks, squares, or civic amenities.
      • STREET_CLOSURE (2490L): Permanent closure of road reserves, public lanes, or pedestrian ways.
      • STREET_NAME (2492L): Municipal proclamation altering public street names.
      • CANCELLATION_ALL_PARCELS (2487L): Complete cancellation of an approved General Plan or diagram.
      • TYPE_PARTIAL_CANCELLATION_GP (2827L): Partial cancellation of specific erven within an approved GP.
      • NOTARIAL_SERVITUDE (9907L): Registration of powerline, pipeline, or right-of-way notarial servitudes.
Stage 2: Steps Configuration & Gazette Proclamation Ingestion
  • Objective: Detail the cadastral units subject to alteration and attach certified legal proclamations.
  • Evidence Ingestion Mechanics (MaintenanceDraftSteps, MaintenanceDraftDocument):
    • Surveyors construct sequential MaintenanceDraftSteps detailing the mother parcel, child portions, and deeds registration division.
    • Uploads mandatory evidentiary dockets directly to RustFS S3 (Port 9000):
      • Official Provincial Gazette publication notices.
      • Certified Municipal Council resolution minutes.
      • High Court orders or land claims court restitution judgments.
      • Sketch plans illustrating affected road reserves or park perimeters.
Stage 3: Procedural Compliance Checklists & Tariff Simulation
  • Objective: Enforce procedural statutory compliance and compute administrative maintenance tariffs.
  • Scrutiny & Invoicing Mechanics (MaintenanceDraftChecklistDTO, MaintenancePerformaInvoiceService):
    • Evaluates statutory quality control responses (QcChecklistResponse) under list code 387, verifying public notice advertising dates, objection appeal window expiries, and municipal engineer consents.
    • Invokes fee simulation to compute statutory tariffs based on the category of alteration and parcel area.
    • Compiles and dispatches an official proforma tax invoice PDF to the applicant.
Stage 4: Lodgement Checkout & Workflow Submission
  • Objective: Confirm fee settlement (or institutional statutory fee waiver) and submit the docket for Surveyor-General scrutiny.
  • Checkout Pipeline (MaintenanceResource.submitDraft, MaintenanceDraftPayment):
    • Applicant records payment details or uploads municipal exemption dockets.
    • Locks the maintenance draft against further modification (status = SUBMITTED).
    • Dispatches process execution event to cis-workflow (Port 8090), placing the dossier in the Surveyor-General Maintenance Queue.
Stage 5: Surveyor-General Officer Scrutiny & Registry Alteration
  • Objective: Review legal authority, verify boundary continuity, and execute the physical cadastral alteration in the master registry.
  • Statutory Scrutiny Mechanics:
    • SG Cadastral Officer scrutinizes gazette notices against underlying registered parcels in cis-search.
    • Registry Mutation:
      • Updates parcel statuses in SgdataParcels (e.g., transitions park or street reserve to developable Erf, or marks cancelled general plan erven as CANCELLED, code 1529L).
      • Updates mother parcel remaining extent balances in SgdataParentChild.
      • Registers notarial servitudes as encumbrance child rights.
Stage 6: Statutory Outcome Certification & Deeds Office Dispatch
  • Objective: Compile legally certified outcome notice documentation and transmit to the Registrar of Deeds and municipality.
  • Outcome Notice Generation (MaintenanceOutcomeLetterService, Flying Saucer PDF):
    • Automatically compiles specialized, sealed statutory outcome notice PDFs:
      • MaintenanceOutcomeLetterNotification: Generic cadastral modification certificate.
      • MaintenancePPCOutcomeLetterNotification: Public Place Closure certificate required by conveyancers.
      • MaintenanceStreetRenameOutcomeLetterNotification: Official gazetted street renaming notices dispatched to municipal GIS and postal authorities.
    • Stores certified PDFs in RustFS S3 and hands the completed record over to Module 7 (Archival).

6.3 Detailed Sequence Interaction Diagram

sequenceDiagram
    autonumber
    actor Planner as Municipal Planner / PLS
    participant BFF as cis-bff (:8080)
    participant API as cis-api (:8089)
    participant S3 as RustFS S3 (:9000)
    participant WF as cis-workflow (:8090)
    participant DB as Oracle Database 23 (:1521)
    participant Deeds as Registrar of Deeds

    %% 1. Initiation
    Planner->>BFF: POST /api/maintenance/saveDraft (EXCISION / PPC)
    BFF->>API: Forward with Bearer JWT
    API->>DB: Persist MaintenanceDraft & Steps
    API-->>Planner: Maintenance Draft Initialized

    %% 2. Gazette Upload
    Planner->>BFF: POST /api/maintenance/saveAnnexure (Provincial Gazette PDF)
    BFF->>API: Stream Gazette Proclamation
    API->>S3: PutObject (RustFS S3 :9000)
    API->>DB: Persist MaintenanceDraftDocument
    API-->>Planner: Gazette Document Staged

    %% 3. Invoicing & Submit
    Planner->>BFF: POST /api/maintenance/processInvoice
    API->>API: MaintenancePerformaInvoiceService.calculate()
    API-->>Planner: Proforma Tax Invoice Issued
    Planner->>BFF: POST /api/maintenance/submitDraft (Payment Receipt)
    API->>WF: Initiate Maintenance Workflow Process
    WF-->>API: Status = UNDER_SG_SCRUTINY
    API-->>Planner: Application Submitted

    %% 4. SG Officer Endorsement & Deeds Notice
    Note over WF,API: SG Cadastral Officer Scrutinizes Proclamation & Boundary
    WF->>API: Trigger Endorsement Callback
    API->>DB: Update SgdataParcels (Set Status = CANCELLED / EXCISED)
    API->>API: MaintenanceOutcomeLetterService.generatePdf()
    API->>S3: Upload Sealed Outcome Letter PDF
    API->>Deeds: Transmit Statutory Notice for Title Deed Endorsement
    API-->>Planner: Statutory Alteration Registered & Outcome Docket Issued

6.4 State Machine: Cadastral Maintenance Lifecycle

stateDiagram-v2
    [*] --> DRAFT_CREATED: User initiates maintenance application
    DRAFT_CREATED --> STEPS_CONFIGURED: Add parcels, steps & MaintenanceReason
    STEPS_CONFIGURED --> GAZETTES_UPLOADED: Attach provincial gazette notices & council minutes
    GAZETTES_UPLOADED --> CHECKLIST_VERIFIED: Complete procedural compliance checklist
    CHECKLIST_VERIFIED --> INVOICED: Tariff computed & proforma invoice issued
    INVOICED --> SUBMITTED: Payment settled & submitted to cis-workflow
    SUBMITTED --> UNDER_EXAMINATION: Ingested into SG Maintenance queue
    UNDER_EXAMINATION --> QUERIED: Procedural defect or gazette ambiguity
    QUERIED --> UNDER_EXAMINATION: Rectified gazette notice uploaded
    UNDER_EXAMINATION --> APPROVED: SG Officer endorses alteration
    APPROVED --> REGISTRY_MUTATED: SgdataParcels status updated (Cancelled/Excised)
    REGISTRY_MUTATED --> OUTCOME_ISSUED: Sealed Outcome Notice generated & sent to Deeds
    OUTCOME_ISSUED --> ARCHIVED: Handed over to Module 7 Archival
    ARCHIVED --> [*]

6.5 Maintenance Engine REST API Reference Matrix

HTTP Verb Endpoint Handler Method Request Body / Parameters Statutory Function / Description
POST /api/maintenance/saveDraft saveMaintenanceDraft MaintenanceDraftDto Initializes or updates a cadastral maintenance application draft.
GET /api/maintenance/draft/{draftId} getMaintenanceDraft draftId Retrieves complete draft state, steps, and gazette attachments.
POST /api/maintenance/saveSteps saveMaintenanceDraftStep MaintenanceDraftStepsDto Adds a statutory alteration step linked to a MaintenanceReason.
POST /api/maintenance/saveDraftRequest saveMaintenanceDraftRequest MaintenanceDraftRequestDto Links affected cadastral parcels to the maintenance step.
POST /api/maintenance/saveAnnexure saveMaintenanceDocument Multipart MaintenanceDraftAnnexureDto Ingests provincial gazette notices and municipal resolutions.
POST /api/maintenance/processInvoice processInvoice draftId Computes dynamic statutory maintenance alteration tariffs.
GET /api/maintenance/generatePerformaInvoice generatePdf draftId Compiles official DALRRD Flying Saucer tax proforma invoice PDF.
POST /api/maintenance/addPayment addPayment MaintenanceDraftPaymentDto Records EFT settlement receipt or municipal fee waiver certificate.
POST /api/maintenance/submitDraft submitDraft draftId Locks maintenance draft and transitions workflow to SG examination.
GET /api/maintenance/getOutcomeLetter getOutcomeLetter draftId Streams certified PDF outcome letter (Excision, PPC, Street Rename).

Module 7: Archival & Historical Records Archive (HRA / PlanSafe)

The Archival & Historical Records Archive (HRA / PlanSafe) module ensures the permanent legal preservation, physical strongroom security, high-resolution scanning, and spatial discovery of cadastral records spanning more than a century of national land registration.

It operates two complementary preservation tracks: 1. Digital HRA Pipeline (HistoricalRecordsArchiveService, HraScanDocumentService): High-throughput scanning, image quality auditing (DPI, skew, legibility), attribute OCR extraction, and Lucene spatial search index synchronization in cis-search. 2. PlanSafe Physical Strongroom Governance (PlanSafeDocTrackingService): Barcode-driven physical custody tracking of irreplaceable historical linen and paper dockets inside fireproof Surveyor-General vaults (Cabinet, Drawer, Box, and Folio coordinates).


7.1 Complete End-to-End Lifecycle Vector Architecture

Below is the verified end-to-end 6-stage lifecycle architecture of the Archival Engine, illustrating post-approval ingestion from Module 4, physical packet bundling, scanning quality checklists, metadata indexing, PlanSafe vault tracking, and search enablement:

Module 7: Archival Engine Lifecycle & PlanSafe Architecture


7.2 Chronological Stage-by-Stage Lifecycle Walkthrough

%%{init: {'theme': 'base', 'themeVariables': { 'fontSize': '14px', 'fontFamily': 'Roboto', 'lineColor': '#e11d48' }}}%%
flowchart LR
    classDef stage fill:#FFF1F2,stroke:#E11D48,stroke-width:2px,color:#881337;
    classDef action fill:#EFF6FF,stroke:#2563EB,stroke-width:2px,color:#1E40AF;
    classDef complete fill:#ECFDF5,stroke:#047857,stroke-width:2px,color:#064E3B;

    S1["1. Post-Approval Ingest<br/>(ArchiveScheduler ShedLock)"]:::stage
    S2["2. Packet Bundling<br/>(ArcPacket & Barcodes)"]:::action
    S3["3. Scanning & QC<br/>(HraScanningChecklist)"]:::stage
    S4["4. Metadata Indexing<br/>(ArcMetaData & Lucene)"]:::stage
    S5["5. PlanSafe Strongroom<br/>(Vault Physical Custody)"]:::complete
    S6["6. Discovery & Procurement<br/>(Module 1 Feeder)"]:::complete

    S1 --> S2 --> S3 --> S4 --> S5 --> S6
Stage 1: Post-Approval Handover & Automated Ingestion
  • Objective: Ingest approved survey batches immediately following Surveyor-General digital stamping in Module 4.
  • Automated Ingestion Pipeline (ArchiveScheduler, HistoricalRecordsArchiveService):
    • Coordinated via distributed ShedLock (@SchedulerLock(name = "archive_scheduler_task")).
    • Periodically scans LodgementBatch for newly approved submissions (isExamined = 1).
    • Ingests PostApprovalDTO containing stamped diagram PDFs, general plans, and coordinate tables.
    • Creates master HistoricalRecordsArchive records linking the statutory SG Diagram number, approval year, and provincial registry.
Stage 2: Archival Packet Bundling & Barcode Generation
  • Objective: Organize disparate survey diagrams, title deeds, and working plans into coherent legal archival packets.
  • Packet Architecture (PacketService, ArcPacket, ArcPacketDocument):
    • Groups related records into an ArcPacket representing a physical or digital archival envelope.
    • Generates a unique, high-entropy Code128 barcode docket (e.g., ARC-PKT-2026-0089).
    • Links all constituent documents into ArcPacketDocument with verified page counts and file format classifications.
    • Governs packet lifecycle progression: DRAFT \(\rightarrow\) DISPATCHED \(\rightarrow\) ARCHIVED.
Stage 3: Scanning Bureau Digitization & Image Quality Auditing
  • Objective: Digitize historical paper archives at high throughput while strictly enforcing image legibility standards.
  • Scanning Quality Pipeline (HraScanDocumentService, HraScanningChecklist):
    • Ingests scanned image streams (600 DPI uncompressed TIFF and PDF/A) directly from scanning bureau hardware.
    • Quality Checklists (HraScanningChecklistService):
      • Image Resolution: Verifies minimum 300–600 DPI optical scan quality.
      • Skew & Alignment: Automated detection of rotated or skewed diagram scans.
      • Seal & Signature Clarity: Verifies that historic red wax seals, embossed Surveyor-General stamps, and surveyor signatures remain clearly legible.
      • Promotes approved scans to SCANNED_QC_OK status.
Stage 4: Automated Metadata Extraction & Lucene Search Indexing
  • Objective: Extract alphanumeric cadastral attributes and synchronize them with cis-search for sub-second spatial discovery.
  • Metadata Extraction Engine (MetaDataService, AttributeDataService):
    • Populates ArcMetaData and granular attribute tables (HraScanAttributeData, ArcAttributeData).
    • Tags each archival document with:
      • Administrative Hierarchy: Province -> Municipality -> Township / Registration Division.
      • Parcel Identifiers: Erf Number, Portion Number, Farm Name, Sectional Scheme Name.
      • Survey Details: Original Land Surveyor Name, Survey Completion Date, General Plan Reference.
    • Feeds extracted metadata directly into the embedded cis-search Lucene index under SearchContext.PARCEL and SearchContext.FARM.
Stage 5: PlanSafe Physical Strongroom Custody Governance
  • Objective: Track the precise physical custody of original paper diagrams and field books inside fireproof Surveyor-General strongrooms.
  • PlanSafe Tracking Architecture (PlanSafeDocTrackingService, PlanSafeDetails):
    • Records exact strongroom coordinates: Strongroom Name \(\rightarrow\) Cabinet Number \(\rightarrow\) Drawer Number \(\rightarrow\) Box ID \(\rightarrow\) Folio Index.
    • Barcode Check-In / Check-Out:
      • When an examination officer, historical researcher, or state attorney requests physical access to an original diagram, the system logs officer identity, borrower reason, and sign-out timestamp.
      • Enforces maximum retention windows and issues automated overdue return notifications.
Stage 6: Public Discovery & Information System Procurement Enablement
  • Objective: Make archived cadastral documents authoritative, searchable, and purchasable by registered surveyors, conveyancers, and citizens.
  • Full Cadastral Loop Closure:
    • Once indexed in HRA, the diagram PDF in RustFS S3 becomes instantly discoverable in Module 1 (Information System & Data Viewer).
    • Surveyors preparing new subdivisions in Module 2 (Reservation Engine) query these archived parent records to initiate the next generation of land parcels.

7.3 Detailed Sequence Interaction Diagram

sequenceDiagram
    autonumber
    actor Officer as Archive Officer / Scanning Operator
    participant BFF as cis-bff (:8080)
    participant API as cis-api (:8089)
    participant S3 as RustFS S3 (:9000)
    participant Search as cis-search (In-Memory Lucene)
    participant DB as Oracle Database 23 (:1521)
    participant Vault as PlanSafe Physical Vault

    %% 1. Ingestion
    API->>API: ArchiveScheduler.performTask()
    API->>DB: Ingest Stamped Documents into HistoricalRecordsArchive
    DB-->>API: Master Archive ID = 8841

    %% 2. Packet Bundling
    Officer->>BFF: POST /api/archive/packet (Create ArcPacket)
    BFF->>API: Group Diagrams & Deeds into Packet
    API->>DB: INSERT INTO ArcPacket & ArcPacketDocument
    API-->>Officer: Packet Barcode Docket Issued (ARC-PKT-2026-0089)

    %% 3. Scan & Metadata
    Officer->>BFF: POST /api/archive/scanDoc (Multipart 600 DPI TIFF/PDF)
    BFF->>API: Upload Scanned Document
    API->>S3: PutObject (RustFS S3 :9000)
    API->>DB: Persist HraScanDocument
    API->>API: MetaDataService.extractAttributes()
    API->>Search: Synchronize Lucene Search Index (SearchContext.PARCEL)
    API-->>Officer: Scan & Metadata Indexed Successfully

    %% 4. PlanSafe Physical Strongroom Check-in
    Officer->>BFF: POST /api/archive/plansafedoctracking (Barcode Scan)
    BFF->>API: Register Physical Custody Coordinates
    API->>DB: Record Strongroom, Cabinet, Drawer, Box
    API->>Vault: Physical File Placed in Fireproof Strongroom
    API-->>Officer: PlanSafe Custody Confirmed (File Available for Search)

7.4 State Machine: Cadastral Archival Docket & Physical Custody Lifecycle

stateDiagram-v2
    [*] --> POST_EXAMINATION_PENDING: Approved in Module 4 Examination
    POST_EXAMINATION_PENDING --> HRA_INGESTED: ArchiveScheduler ingests stamped docket
    HRA_INGESTED --> PACKET_BUNDLED: PacketService creates ArcPacket & barcode
    PACKET_BUNDLED --> SCANNING_BUREAU: Physical packet routed to scanners
    SCANNING_BUREAU --> SCANNED_QC_PENDING: High-resolution images ingested
    SCANNED_QC_PENDING --> SCAN_REJECTED: Skewed, illegible or low DPI
    SCAN_REJECTED --> SCANNING_BUREAU: Re-scanned at correct settings
    SCANNED_QC_PENDING --> SCANNED_QC_APPROVED: HraScanningChecklist verified
    SCANNED_QC_APPROVED --> METADATA_INDEXED: MetaDataService tags parcels & feeds Lucene
    METADATA_INDEXED --> PLANSAFE_FILED: Filed in fireproof strongroom (Cabinet/Drawer)
    PLANSAFE_FILED --> CHECKED_OUT: Borrowed for court litigation or inquiry
    CHECKED_OUT --> PLANSAFE_FILED: Returned to strongroom & barcode scanned
    PLANSAFE_FILED --> DISCOVERY_ACTIVE: Live & purchasable in Module 1 Search
    DISCOVERY_ACTIVE --> [*]

7.5 Archival Engine REST API Reference Matrix

The table below catalogs primary REST endpoints exposed by ArchiveResource:

HTTP Verb Endpoint Handler Method Request Body / Parameters Statutory Function / Description
POST /api/archive/processApproval processApproval PostApprovalDTO Ingests approved survey records into long-term historical archive.
GET /api/archive/getApprovedBatches getApprovedBatches Pageable Queries batches approved in examination ready for archival ingestion.
POST /api/archive/packet savePacket ArcPacketDTO Creates or updates an archival envelope packet docket.
GET /api/archive/packet/{packetId} getPacket packetId Retrieves packet metadata and constituent ArcPacketDocument list.
POST /api/archive/scanDoc saveScanDocument HraScanDocumentDTO Ingests high-resolution scanned survey diagrams and deeds.
POST /api/archive/checklist saveChecklist HraScanningChecklistDTO Records scanning bureau quality verification audit checklist.
POST /api/archive/metadata saveMetaData ArcMetaDataDTO Extracts and indexes cadastral search metadata into cis-search.
POST /api/archive/plansafedoctracking savePlanSafeDocTracking PlanSafeDocTrackingDTO Records physical strongroom cabinet, drawer, and box custody coordinates.
GET /api/archive/plansafedoctracking/register getRegister Pageable Queries PlanSafe physical document custody register and borrower logs.
POST /api/archive/triggerArchive triggerManually ArchiveTriggerTaskVm Manually triggers scheduled archival ingestion tasks.

3. Embedded Submodules

cis-api incorporates two specialized library modules compiled directly into its JAR (cis-api/build.gradle):

cis-search (Spatial & Text Query Provider)

  • Embedded query layer optimizing spatial lookups and text searches across massive land registries.
  • Shares the synchronized SearchContext enum with cis-api (NGI, PARCEL, FARM, LUR, etc.) to guarantee seamless search indexing without RPC overhead.

cis-emailer (Document & Notification Engine)

  • Formats dynamic HTML notifications using Thymeleaf templates.
  • Generates official PDF letters, acknowledgements, and receipts using Flying Saucer XHTML-to-PDF engine.
  • Automatically prepends active environment banners (e.g., [DEV], [UAT]) to avoid confusing recipients during test runs.

4. Storage & Runtime Integration

Persistence & Object Storage

  • Relational Data: Connects to Oracle Database 23 (:1521) via HikariCP and Spring Data JPA.
  • Object / Blob Storage: Connects to RustFS (:9000) using S3-compatible APIs for all document uploads, scan packets, and generated docket PDFs.
  • Distributed Cache & Locking: Connects to Redis 7.4 (:6379) for caching frequently queried cadastral layers and coordinating ShedLock scheduled background tasks.

Container Runtime Specifications

  • Base Image: Eclipse Temurin OpenJDK 25
  • Internal Listen Port: 8089 (Host mapped to HOST_API_PORT=8089)
  • Health Check Endpoint: GET http://localhost:8089/management/health
  • Volume Mounts:
  • /data/uploads (APP_STORAGE_LOCATION)
  • /app/logs (Application Logback logs)