Differences

This shows you the differences between two versions of the page.

--- reference:system-architecture [2025/08/27 06:33] – [7.3 Sign maintenance REST API methods] runarbe
+++ reference:system-architecture [2025/09/09 22:03] (current) – [7. API layer] runarbe
@@ Line 3: / Line 3: @@
 This document provides an overview of all the elements that are required to operate the addressing system data infrastructure.
-===== 1. Scope of the System Architecture Specification =====
+===== 1. Scope of the Specification =====
 The scope of this document encompasses the essential requirements for the creation, maintenance, and dissemination of addresses within the National Addressing System project in Oman. It provides a detailed exploration of the necessary components and methodologies for effective addressing.
@@ Line 15: / Line 15: @@
 High-value integrations with government and private sector entities are proposed. Such integrations would allow for improved service delivery in the public sector, such as in emergency response and utility management. In the private sector, it could enhance commercial operations, logistics, and customer service practices by providing accurate and reliable address information. These partnerships are vital for maximizing the benefits of the National Addressing System, promoting efficiency, and facilitating economic and infrastructural development.
-===== 2. The Purpose of Integrating Addresses =====
+=====   =====
-The integration of addresses into other systems serves several essential purposes, primarily aimed at creating value for individuals, businesses, organisations and government bodies. Address systems become meaningful only when they actively contribute to achieving specific objectives, thereby justifying the considerable effort and expense involved in their implementation.
-The concept of "value" within the context of address integration encompasses several aspects. Firstly, it provides ease in locating items or places, making navigation and discovery more straightforward. It also contributes to speed by enabling the faster delivery of people, goods, and services. Moreover, it can reduce costs associated with tasks such as locating customers – or even absconding taxpayers. An integrated address system enhances safety by minimising risks during emergency situations, such as reducing the likelihood of injury due to timely assistance.
-In addition to tangible measures, the notion of an improved addressing system further extends to being just, fair, and equitable, providing benefits across various sectors. The system should also be accessible, facilitating easier operations, and its visual presentation should be designed for aesthetic appeal, or at the very least not to scare off users.
-To illustrate the value added by integrated address systems, consider several examples. They allow for precise specification of delivery locations, ensuring parcels reach their intended destinations efficiently. The system also aids in identifying the location of individuals or entities, such as querying the whereabouts of "Krookie XYZ". Furthermore, during urgent scenarios, such as calling for an ambulance, verbal communication of locations becomes clearer and more reliable.
-Additionally, integrated address systems enable users to conveniently identify and associate multiple personal assets with specific locations. This includes one's land, house, telecom subscriptions, electricity meters, vehicles, and other property. An address acts as an efficient key that links and organises various belongings, simplifying management and oversight. For a person wishing to access a public service, it is necessary to identify him or herself by some means known to both parties. Successful and widespread adoption of addresses will often make it possible to identify the objects or assets under discussion out of hand.
 ===== 3. Systems Needed to Manage and Use NAS Data =====
@@ Line 47: / Line 37: @@
 The business of street addressing is a complex set of interrelated managerial, planning, technical and engineering/civil works tasks that involves a broad range of distinctive end-users. The diagram below provides an overview of all the components that are required for the efficient operation and flow of data in the addressing system.
-{{  :wiki:reference:system:addressing-system-integration-architecture.png?direct&800  |Click on image to view or download in full resolution}}
+{{  :wiki:reference:system:addressing-system-integration-architecturev003_1.png?direct&800x444  }}
 The diagram can be read both bottom up and top down. From the point of view of technical resources, the preferred reading direction is bottom up, for people who find themselves in end-user roles, it is more easily read from top to bottom.
@@ Line 68: / Line 58: @@
   * Documentation for the [[:reference:system-architecture:signage-data-model|sign management data model]] (to be supplied by future appointed vendor)
-==== 5.3 Naming data model ====
+==== 5.3 Name collection data model ====
+  * Documentation for the [[:reference:system-architecture:name-collection-data-model|naming data model]] (to be supplied by existing vendor)
+==== 5.4 Name allocation data model ====
+  * Documentation for the [[:reference:system-architecture:naming-allocation-data-model|naming data model]] (to be supplied by existing vendor)
+==== 5.5 Field verification application data model ====
+  * Documentation for the [[:reference:system-architecture:field-verification-data-model|naming data model]] (to be supplied by existing vendor)
-  * Documentation for the [[:reference:system-architecture:naming-data-model|naming data model]] (to be supplied by existing vendor)
 ===== 6. Data Layer =====
@@ Line 107: / Line 106: @@
 The Application Programming Interface (API) layer serves as a conduit for data exchange with the database. It facilitates data retrieval and submission, ensuring seamless interaction with stored information.
-==== 7.1. Authentication API ====
 All applications provided by the NAS eco-system of software applications and services must be accessible through a shared user account.
   * [[:reference:system-architecture:authentication-api|Authentication API]]
+  * [[:reference:system-architecture:address-editing-and-query-api|Address editing API]]
-==== 7.1 Addressing Editing and Query API ====
+  * [[:reference:system-architecture:address-integration-api|Address Integration API]] (vendor to be appointed by by competitive tender)
-  * [[:reference:system-architecture:address-editing-and-query-api|Address Editing and Query API]]
-==== 7.2 Naming application REST API methods ====
   * [[:reference:system-architecture:naming-api|Naming API]] (to be supplied by existing vendor)
+  * [[:reference:system-architecture:signage-api|Signage API]] (vendor to be appointed by by competitive tender)
-====   Sign API  (implemenation to be determined through competitive tender)  ====
@@ Line 131: / Line 120: @@
 Below, you will find technical and functional requirements for the following applications
-  * [[:reference:system-architecture:address-editing-application|Web based data creation and editing client]]
+  * [[:reference:system-architecture:address-editing-application|Address editing application]]
   * [[:reference:system-architecture:street-naming-application|Street naming application]]
   * [[:reference:system-architecture:mobile-field-verification-application|Mobile field verification application]]
@@ Line 138: / Line 127: @@
   * [[:reference:system-architecture:addressing-viewer-and-search-application|Addressing viewer and search application]]
   * [[:reference:system-architecture:addressing-wiki|Addressing WIKI]]
 ===== 9. Infrastructure layer =====
@@ Line 146: / Line 136: @@
   * [[:reference:system-architecture:infrastructure|Technical infrastructure specification]]
 ===== 10. Emerging technologies and future proofing =====
@@ Line 217: / Line 206: @@
 Integration refers to the incorporation of addressing systems into various operational, security, and convenience-oriented applications for both residents and visitors in the Sultanate of Oman. It involves embedding addressing as an element within a database table or an object model in business applications. This enables effective indexing and geocoding of records and subsequent location of assets and/or delivery locations for goods services and people.
-Integration processes will be executed by business owners, not by the Ministry of Housing, Urban Planning. MoHUP will support by providing data access, adapting services, and facilitating systems. While MoHUP may promote integration and encourage business owners to recognise its benefits, ultimate responsibility rests on the business owners. Given the sensitivity of critical systems, business owners must perceive the value of integration for it to proceed independently.
+==== 13.1 The Purpose of Integrating Addressing into other systems ====
-Many business systems are already structured to accommodate addressing, particularly the newly implemented international formats. MoHUP's primary responsibility will be to ensure stakeholders are informed about, and have access to, necessary data and systems, thereby enabling seamless integration.
+The integration of addresses into other systems serves several essential purposes, primarily aimed at creating value for individuals, businesses, organisations and government bodies. Address systems become meaningful only when they actively contribute to achieving specific objectives, thereby justifying the considerable effort and expense involved in their implementation.
-  * [[:reference:system-architecture:integrations|Categorised list of value-added integrations of addressing data]]
+The concept of "value" within the context of address integration encompasses several aspects. Firstly, it provides ease in locating items or places, making navigation and discovery more straightforward. It also contributes to speed by enabling the faster delivery of people, goods, and services. Moreover, it can reduce costs associated with tasks such as locating customers – or even absconding taxpayers. An integrated address system enhances safety by minimising risks during emergency situations, such as reducing the likelihood of injury due to timely assistance.
+In addition to tangible measures, the notion of an improved addressing system further extends to being just, fair, and equitable, providing benefits across various sectors. The system should also be accessible, facilitating easier operations, and its visual presentation should be designed for aesthetic appeal, or at the very least not to scare off users.
-===== 14. Data Quality Framework =====
+To illustrate the value added by integrated address systems, consider several examples. They allow for precise specification of delivery locations, ensuring parcels reach their intended destinations efficiently. The system also aids in identifying the location of individuals or entities, such as querying the whereabouts of "Krookie XYZ". Furthermore, during urgent scenarios, such as calling for an ambulance, verbal communication of locations becomes clearer and more reliable.
-High-quality address data is fundamental to the effectiveness, reliability, and public trust in the NAS. A robust data quality framework is therefore required, spanning initial collection, ongoing maintenance, and all migration processes. Data quality is the matter for other deliverables in this project, but a brief outline of key elements of the framework is cited below.
+Additionally, integrated address systems enable users to conveniently identify and associate multiple personal assets with specific locations. This includes one's land, house, telecom subscriptions, electricity meters, vehicles, and other property. An address acts as an efficient key that links and organises various belongings, simplifying management and oversight. For a person wishing to access a public service, it is necessary to identify him or herself by some means known to both parties. Successful and widespread adoption of addresses will often make it possible to identify the objects or assets under discussion out of hand.
-=== Data governance and quality assurance ===
+==== 13.2 How integrations will be done ====
-A formal data governance model will be established, assigning clear roles and responsibilities for data stewardship, oversight, and access control. Data integrity will be protected through audit logging, versioning, and rollback mechanisms, enabling transparent tracking of changes and rapid correction of errors. This is handled in the data model section above.
+Integration processes will be executed by business owners, not by the Ministry of Housing, Urban Planning. MoHUP will support by providing data access, adapting services, and facilitating systems. While MoHUP may promote integration and encourage business owners to recognise its benefits, ultimate responsibility rests on the business owners. Given the sensitivity of critical systems, business owners must perceive the value of integration for it to proceed independently.
-=== Automated validation and error handling ===
+Many business systems are already structured to accommodate addressing, particularly the newly implemented international formats. MoHUP's primary responsibility will be to ensure stakeholders are informed about, and have access to, necessary data and systems, thereby enabling seamless integration.
-Automated validation rules will be implemented at all data entry points—both in the field and during integration—to enforce mandatory attributes, valid ranges, permitted formats, and spatial consistency. Error handling procedures will flag inconsistencies, missing values, or suspected duplicates for immediate review by data managers. This is handled in the data capturing specifications and addressing standard.
+==== 13.3 Proposed integrations ====
-=== Periodic audits and quality monitoring ===
+  * [[:reference:system-architecture:integrations|Categorised list of value-added integrations of addressing data]]
-Regular data quality audits will be scheduled to assess completeness, accuracy, and conformity to the data model. Automated tools and manual sampling will be used to monitor address coverage, detect anomalies, and measure adherence to standards. Audit results will inform continuous improvement efforts and staff training needs.
+===== 14. Data Quality Framework =====
-=== Reconciliation during migration ===
-For system migrations, a structured reconciliation process will compare legacy data with NAS records, identify discrepancies, and enable targeted correction. Scripts will be developed for data matching, and all changes will be logged for traceability.
-=== Phased rollout and pilot testing ===
+High-quality address data is fundamental to the effectiveness, reliability, and public trust in the NAS. A robust data quality framework is therefore required, spanning initial collection, ongoing maintenance, and all migration processes. Data quality is the matter for other deliverables in this project, but a brief outline of key elements of the framework is cited below.
-To minimize risks, data migration and system deployment will follow a phased approach, starting with pilot testing in selected wilayats. Lessons learned from these pilots will guide process refinement before scaling to a national rollout.
-=== Continuous improvement ===
-Feedback mechanisms will allow users and integrators to report suspected data issues, which will be triaged and resolved according to documented protocols. The framework will be reviewed and updated regularly to reflect evolving best practices and technology advancements.
+  * [[:reference:system-architecture:data-quality|Data quality]]
 ===== 15. Transitional Arrangements =====