====== Address Data Editing and Quality Assurance Application ======

The Addressing Tool is designed to facilitate the creation and management of addressing data for the national addressing system of the Sultanate of Oman. This application aims to provide a comprehensive platform for editing, managing, and visualizing geographic information related to streets and address units. The tool's primary objectives include ensuring fast and efficient editing processes, supporting web-based access, integrating with various data sources, and enabling systematic data management and quality control.

This is the __only__ end user interface where streets, street segments and address units are created, edited or modified.
===== Technical Requirements =====

  * Operating System: Linux is preferred for the deployment of the Addressing Tool.
  * Deployment as Containers: Utilize Docker and Docker Compose for application deployment.
  * Database Server: PostGIS is the preferred database as per analysis provided in system architecture document.
  * Web Server: NGINX is the preferred choice for web server deployment.
  * Identity Server: Implement the shared authentication with all other addressing applications.
  * Map Server: Preferably use GeoServer with pg_tileserv or alternatively, ArcGIS Enterprise Server.
  * API Server: Employ Python FastAPI along with Uvicorn to serve the API. The API must expose an OpenAPI end-point.
  * Servers: The system should be deployed on two virtual servers - one for the Database and another for Applications.

===== Functional Requirements =====

  * Editing Efficiency: The tool must ensure fast and instantaneous editing processes, allowing for easy modifications of multiple features.
  * Web Application: The tool should be developed as a web application to support widespread access.
  * Map Display and Navigation: Include functionalities for map display and navigation, such as zoom, pan, and toggling layers on/off.
  * User Data Upload: Enable users to upload their data for processing.
  * Data Sources Integration: Incorporate multiple data sources such as Google imagery, satellite imagery (2016-18), and a basemap service.
  * Thematic Data Handling: Manage thematic data involving road centerlines, parcels, buildings, and municipal entrance/sub address data.
  * Street Definition: Offer comprehensive street management functionalities, including modifying, deleting, and transferring street segments, editing attributes, and drawing street segments.
  * Address Unit Definition: Facilitate creation, editing, selection, and movement of address units along with setting tool settings.
  * Data Management: Provide tools for checking out areas for editing, submitting data for quality control, viewing QC queues, and exporting/importing data in geojson/json formats.
  * Issue Management: Enable the creation, editing, selection, and deletion of issues, along with exporting issues to GeoJSON format.
  * Sub Address Management: Allow users to create sub addresses within the system.

===== Data editing process =====

The following workflow is to be implemented in the tool:

  * Users must be assigned roles and rights for different areas
      * Roles: superadmin, superuser, editor, user
      * Example: User A has access to check out addresses for streets in al Qabil in Al Sharqiyah North (typically for a municipality level user)
      * Example: User B has rights to check out and approve addresses for streets in all of Al Sharquiya (typically for a governorate level user)
      * Question: **It is necessary to establish a user hierarchy**
  * When editing, users must checks out data to work on
      * Data can be checked out by drawing a rectangle in map
      * All intersected streets within the area the user has rights to work on will be checked out
      * The data will be exported to the local machine and be edited there
      * Data can be saved back to the application without being checked back in
      * Data can be passed on to another user for QC so taht they may be checked back into the system (see below)
      * When sent back, the data are deleted from the local client.
      * Question: **what about streets that cross borders?**
  * When data has been checked out, the concerned streets must be locked for checkout so that multiple people can not edit them simultaneously
      * Nobody else can check out this area until lock has been deleted
      * The lock will be deleted after checkin
      * The lock can also be deleted by a superuser in case the user who checked out data is not available/indisposed
  * The actual editing takes place in the application as it is today,
      * User works locally in office
      * Creates, updates, deletes streets, address units
      * Creates, updates, deletes issues
      * Largely, the functionality in the app covers most needs - however, from experience using it, there may be things that could be tweaked or adjusted to make it easier to use
  * When the user has identified a number of issues that require field verification, she can export data for field verification (optional)
      * The data can be all data within the area being edited
      * The data can be only data within issue areas
      * The data should be exported to a format suitable for import and use in the mobile field verification application
      * Alternatively, the data can be posted to a web service provided by the mobile field-verification app and it will autoamatically be allocated to a user as per processes there
      * Question: **It is necessary to establish a format for data exchange between the field-verification application and the address editor application**
      * Question: It is necessary to establish a clear boundary between what the **mobile**  field-verification application does and what the **desktop **address editing application does. These two applications must be used in symbiosi <font inherit/inherit;;inherit;;inherit></font>
  * When field verification is done data should be handed back to the editing application
      * Any observations made in the field should be edited and dealt with
      * The status of addresses and streets should be updated accordingly
  * Prior to submitting data for QI, an auto-validation processs that checks exactly three things will be implemented
      * Check that all address unit numbers that are assigned to streets in the dataset are unique, i.e. only one number #1
      * Check that all streets have addresses and names
      * Check that all address unit numbers linked to a street are within a reasonable distance away from the street they are linked to
      * Question: **What is a reasonable distance?**
  * When automatic validation has passed, the user can submit the data for QC
      * The data are sent on to another user who can look at them in the address editing tools as well as statistics about each street
      * The QC user can choose to approve all or street by street
      * The QC user can reject all or street by street
      * If rejected, the concerned parts go back to the editing step
      * If all or a selection of streets are approved - those data are checked in, unlocked and removed from the checked out set
      * Question: **Who does the QC, is it anyone - just peer review - or is it someone on Governorate level? A thorough review requires detailed local knowledge**
  * Data are checked back into the addressing database


===== Status =====

Upon the completion of the 2024/25 National Addressing System project, a tool consisting of 43 245 code lines has been provided by NorthSys free of charge. In a normal estimation process

  * This tool includes all editing functions and integration with underlying data services
  * The tool does not include functionality to check-in/check-out data from the database, nor a web enabled database infrastructure
  * The implementation of remaining features will be done through a variation order
  * The variation order has been approved on the 1st of September 2025