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:
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.
- Parcel Search (
- Query Acceleration with
cis-search:- Utilizes embedded Lucene indices synchronized with the
SearchContextenum (PARCEL,FARM,SECTIONAL_TITLE,NGI) to achieve sub-second response times without cross-network RPC latency.
- Utilizes embedded Lucene indices synchronized with the
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.
- Layer Configuration (
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.
- AlphaNumeric Data (
- Quota & Staging Engine (
CartStage,CartStageData):- Items are staged in transient
CartStagerecords. - 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.
- Items are staged in transient
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
InvoiceItemCostProjectionbased 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.
- Resolves item costs dynamically via
- Proforma Invoice Compilation (
InvoiceResource,InvoiceService):- Creates an official
InvoicePerformaentity associated with a unique transaction reference andworkflowId. - Flying Saucer (XHTML-to-PDF) compiles a formal tax invoice document featuring statutory headers, breakdowns, and payment EFT reference codes.
- Triggers
InvoiceNotificationviacis-emailerto dispatch the proforma invoice directly to the customer's email.
- Creates an official
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
CheckoutVmcarrying the payment confirmation token, credit card gateway receipt, or official statutory fee waiver certificate. - Invokes
CartResource.addToFinalCart(addCartHook):- Migrates items from
CartStageto permanentCartandCartItemstables. - Assigns a formal tracking number (
CIS-INF-YYYY-NNNNNN). - Cleans up transient staging tables (
/api/cart/empty).
- Migrates items from
- Promotes the
cis-workflowbusiness process state toPAID/DISPATCH_READY.
- Ingests
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
ZipOutputStreamto stream the compresseddocs.ziparchive 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.
- Object Storage Retrieval: Fetches raw diagram PDFs and shapefiles directly from RustFS S3 (
- Multi-Channel Fulfillment:
- Email Delivery:
cis-emailerdispatches completion notifications with secure download links via Mailpit / SMTP (Port 1025). - SFTP Push: For bulk corporate orders or external data partners,
uploadDocsOnFtpautomatically 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.
- Email Delivery:
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:
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) viaaddDraftStepByOutcomeIdsandaddDraftRequestByOutcomeIds.
- Draft Persistence: Surveyors initiate a reservation docket (
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
ACTIVEun-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).
- Queries the core land registry to ensure the parent Erf or Farm portion is currently in an
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
processReservationDraftAlgois called withAlgoOutputType.STAGING:- The factory resolves the concrete algorithm corresponding to the statutory
ReservationReason. - The algorithm computes provisional numbers, remaining balances, and parent-child linkages in memory.
- Transient records are written to
ReservationDraftOutcomemarked asSTAGED. - Crucially, the persistent global parcel sequence counters in the database are not incremented, preventing sequence gaps if the surveyor modifies the proposal.
- The factory resolves the concrete algorithm corresponding to the statutory
- When
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
saveDraftCheckoutto 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.
- Transitions draft state to
- Evaluates mandatory statutory questions (
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 triggersProcessReservationAlgowithAlgoOutputType.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
ReservationDraftOutcomeand 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).
- Upon examination officer sign-off in
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
EXPIREDstatus, 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.
- Automated Expiry Scheduler (
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¶
ReservationDraftSteps: Each step in the wizard has an integerstepNoand a designatedReservationReason.- Outcome Staging: When Step 1 runs,
ProcessReservationAlgoinserts staged records intoReservationDraftOutcomewithstepNo = 1. - Automated Inheritance (
isCopyOutcomeOfPrevious): - When Step 2 is configured with
isCopyOutcomeOfPrevious = true,ReservationDraftService.addDraftStepByOutcomeIdscopies the outcome identifiers from Step 1 directly into the inputReservationDraftRequestlist for Step 2. - 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-workflowupon 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:
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
LodgementDraftrecord 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
ReservationOutcomerecords (reserved parcel numbers, LPI strings, parent designations). - Automatically populates sequential
LodgementDraftSteprecords withstepType = LODGEDand creates correspondingLodgementDraftRequestentities. - Validates that the reservation reference has not expired according to statutory SLA timers.
- Ingests the Surveyor-General approved reservation reference (e.g.,
- Draft Docket Creation: Surveyors initiate a
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.
- Streams files directly into RustFS S3 (
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\%\).
- If the survey represents a Sectional Title development under the Sectional Titles Act, the surveyor models:
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-emailerto 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.
- Surveyors record payment details via
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
LodgementBatchwithisExamined = 0.
- Invokes
- 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.
- Iterates through all lodged documents and allocates sequential document numbers via
- 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).
- Generates an official Barcode Acknowledgement Letter PDF (
- Provincial Batch Numbering:
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:
| 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).PqCalculatorServiceapportionates 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:
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
LodgementBatchfor records withisExamined = 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).
- Utilizes distributed ShedLock locking (
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.
- Ingests beacon coordinates and line tables (
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.
- Docket Tree Builder: Structures the multi-page submission into an interactive hierarchy (
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
QUERIEDand routes into Module 5 (Relodgement Engine).
- If Technical Scrutiny Passes:
- Examiner endorses Phase 1 compliance.
- Batch transitions to
PHASE_1_APPROVEDand is automatically promoted to the Senior Examiner Queue.
- If Defects or Inconsistencies Detected:
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
SgCaveatsto 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.
- Coordinated by distributed scheduler
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.
- Calls the digital stamping service (
- Master Record Promotion:
- Archives the digitally stamped PDF in RustFS S3 (
Port 9000). - Promotes provisional parcel records in
SgdataParcelsfrom provisional toAPPROVED/ACTIVE. - Updates parent property remainder balances in
SgdataParentChild. - Dispatches completion notifications and certified docket download links to the surveyor via
cis-emailer.
- Archives the digitally stamped PDF in RustFS S3 (
- Digital Stamping Microservice:
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¶
| 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¶
| 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¶
| 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:
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-workflowsets batch status toQUERIED(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-emailerand starts the statutory response SLA timer (e.g., 60 statutory days to rectify).
- When a Level 1 or Level 2 examiner rejects a batch,
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
LodgementDraftrecord withisActive = 1. - Links
parentDraftIdto the immediate queried submission andfirstParentDraftIdto 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.
- Surveyor triggers
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
LodgementTreestructured 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.
- Status 1528 (
- Streams rectified replacement files into RustFS S3 (
Port 9000) and associates them withsgDocumentId.
- Builds a hierarchical
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
ConsistencyCheckAlgorithmspecifically 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.
- Re-runs
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
LodgementOperationswith actionRELODGE. - Updates document statuses from
QUERIEDto activeLODGED. - Generates an official Relodgement Acknowledgement Letter PDF (
RelodgementAcknowledgementNotification) bearing barcodes and re-filing timestamps. - Dispatches process event to
cis-workflow(Port 8090).
- Surveyor submits
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-workflowuses 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:
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.
- Municipal town planners, conveyancers, or professional surveyors initiate a
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
MaintenanceDraftStepsdetailing 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.
- Surveyors construct sequential
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.
- Evaluates statutory quality control responses (
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 asCANCELLED, code1529L). - Updates mother parcel remaining extent balances in
SgdataParentChild. - Registers notarial servitudes as encumbrance child rights.
- Updates parcel statuses in
- SG Cadastral Officer scrutinizes gazette notices against underlying registered parcels in
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).
- Automatically compiles specialized, sealed statutory outcome notice PDFs:
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:
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
LodgementBatchfor newly approved submissions (isExamined = 1). - Ingests
PostApprovalDTOcontaining stamped diagram PDFs, general plans, and coordinate tables. - Creates master
HistoricalRecordsArchiverecords linking the statutory SG Diagram number, approval year, and provincial registry.
- Coordinated via distributed ShedLock (
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
ArcPacketrepresenting 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
ArcPacketDocumentwith verified page counts and file format classifications. - Governs packet lifecycle progression:
DRAFT\(\rightarrow\)DISPATCHED\(\rightarrow\)ARCHIVED.
- Groups related records into an
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_OKstatus.
Stage 4: Automated Metadata Extraction & Lucene Search Indexing¶
- Objective: Extract alphanumeric cadastral attributes and synchronize them with
cis-searchfor sub-second spatial discovery. - Metadata Extraction Engine (
MetaDataService,AttributeDataService):- Populates
ArcMetaDataand 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-searchLucene index underSearchContext.PARCELandSearchContext.FARM.
- Populates
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.
- Records exact strongroom coordinates:
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
SearchContextenum withcis-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 toHOST_API_PORT=8089) - Health Check Endpoint:
GET http://localhost:8089/management/health - Volume Mounts:
/data/uploads(APP_STORAGE_LOCATION)/app/logs(Application Logback logs)