Issue #4: Make some updates/corrections to Identity Mapper design doc; a… (#15)

groybal · web-flow · commit 0817e19f157a · 2025-12-04T13:33:57.000-07:00
…dd README files
diff --git a/cspell.json b/cspell.json
@@ -81,7 +81,9 @@
         "marimo",
         "mkdocs",
         "mongoimport",
+        "mypass",
         "mypy",
+        "myuser",
         "ndarray",
         "NOJIRA",
         "nosetests",
diff --git a/docs/LIF_Component_Design_Document-Identity_Mapper.md b/docs/LIF_Component_Design_Document-Identity_Mapper.md
@@ -30,80 +30,6 @@ Version 1.0.0
 
 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[Identity Mapper Service](#identity-mapper-service)
 
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[Design Requirements](#design-requirements-1)
-
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[Performance](#performance-1)
-
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[Concurrency](#concurrency-1)
-
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[Dependencies](#dependencies)
-
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[Exceptions and Errors](#exceptions-and-errors)
-
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[Data validation exception](#data-validation-exception)
-
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[Mapping exception](#_Toc198241137)
-
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[Example Usage](#example-usage)
-
-[Detailed Design](#detailed-design)
-
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[Implementation Model](#implementation-model)
-
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[Tools and Technologies](#tools-and-technologies)
-
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[Implementation Requirements](#implementation-requirements)
-
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[Data Storage](#data-storage)
-
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[State](#state)
-
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[Concurrency](#concurrency-2)
-
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[Sync/Async](#syncasync)
-
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[External Services](#external-services)
-
-[Deployment Design](#deployment-design)
-
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[Deployment Environment](#deployment-environment)
-
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[Deployment Model](#deployment-model)
-
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[Deployment Requirements](#deployment-requirements)
-
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[Dependencies](#dependencies-1)
-
-[Motivation](#motivation)
-
-[Design Proposal](#design-proposal)
-
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[Key Concept](#key-concept)
-
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[Functional Requirements](#functional-requirements)
-
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[Interaction with Other LIF Components](#interaction-with-other-lif-components)
-
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[Design Assumptions](#design-assumptions)
-
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[Design Requirements](#design-requirements)
-
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[Performance](#performance)
-
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[Concurrency](#concurrency)
-
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[High Level Design](#high-level-design)
-
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[Identity Mapper Storage](#identity-mapper-storage)
-
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[Identity Mapper Service](#identity-mapper-service)
-
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[Design Requirements](#design-requirements-1)
-
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[Performance](#performance-1)
-
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[Concurrency](#concurrency-1)
-
 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[Dependencies](#dependencies)
 
 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[Exceptions and Errors](#exceptions-and-errors)
@@ -114,33 +40,7 @@ Version 1.0.0
 
 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[Example Usage](#example-usage)
 
-[Detailed Design](#detailed-design)
-
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[Implementation Model](#implementation-model)
-
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[Tools and Technologies](#tools-and-technologies)
-
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[Implementation Requirements](#implementation-requirements)
-
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[Data Storage](#data-storage)
-
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[State](#state)
-
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[Concurrency](#concurrency-2)
-
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[Sync/Async](#syncasync)
-
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[External Services](#external-services)
-
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[Deployment Design](#deployment-design)
-
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[Deployment Environment](#deployment-environment)
-
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[Deployment Model](#deployment-model)
-
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[Deployment Requirements](#deployment-requirements)
-
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[Dependencies](#dependencies-1)
+[Possible Future Roadmap Items](#possible-future-roadmap-items)
 
 # Overview
 
@@ -158,7 +58,7 @@ The **Identity Mapper** component addresses this need by resolving person identi
 
 The **Identity Mapper** is a standalone component that maps person identifiers of two organizations. The **Identity Mapper** is intended to be populated by an internal system having knowledge of the relationship between identifiers used by two organizations. It is invoked by the **Query Planner** when there is a need to translate an external person identifier into an internal identifier.
 
-![](media/image_identityMapper_1.png)
+![](media/image_identityMapper_4.png)
 
 *Image 1: A simple diagram depicting how the Identity Mapper functions at a high-level*
 
@@ -173,7 +73,7 @@ This component has the following specific requirements:
     via an API
 
 3.  Ability to populate identity mapping database through a bulk upload
-    process
+    process (Possible Future Roadmap Item)
 
 ## Interaction with Other LIF Components
 
@@ -197,7 +97,7 @@ This component primarily interacts with the **Query Planner**, which invokes it
 
 ### Performance
 
-The component should provide consistent performance irrespective of the volume of the requests and number of identity mapping records.
+(Possible Future Roadmap Item) The component should provide consistent performance irrespective of the volume of the requests and number of identity mapping records.
 
 ### Concurrency
 
@@ -207,7 +107,7 @@ Concurrent endpoint requests are addressed through parallel threads implemented
 
 The **Identity Mapper** is a standalone component that enables the conversion of a person identifier from an external organization to an internal identifier. As depicted below, the proposed design envisions Identity Mapper storage, along with an Identity Mapper service that provides CRUD operation endpoints.
 
-![](media/image_identityMapper_2.png)
+![](media/image_identityMapper_5.png)
 
 *Image 2: Simple diagram depicting the relationship between the ID Mapper Service and ID Mapper Storage*
 
@@ -233,37 +133,37 @@ A uniqueness constraint should be enforced on the combination of LIF Organizatio
 
 The following methods should be implemented in the Identity Mapper Service to save, retrieve, and delete mappings:
 
-1.  **Save Mappings:** POST Organizations/{Org id}/Persons/{Person id}/mappings
+1.  **Save Mappings:** POST organizations/{org_id}/persons/{person_id}/mappings
 
-2.  **List Mappings:** GET Organizations/{Org id}/Persons/{Person id}/
+2.  **List Mappings:** GET organizations/{org_id}/persons/{person_id}/mappings
 
-3.  **Delete Mappings:** DELETE Organizations/{Org id}/Persons/{Person id}/mappings/{mapping id}
+3.  **Delete Mappings:** DELETE organizations/{org_id}/persons/{person_id}/mappings/{mapping_id}
 
 The diagrams in the following section illustrate the internal steps the service should implement to enable the above methods.
 
 1.  **Save Mappings:** A collection of mappings should be passed to the method for saving the mappings in the storage.
 
-![](media/image_identityMapper_3.pdf)
+![](media/image_identityMapper_3.png)
 
 *Image 3: Workflow diagram for the Save Mappings method*
 
 2.  **List Mappings:** The workflow below illustrates the steps the service should implement to list the mappings for a given organization and person.
 
-![](media/image_identityMapper_4.png)
+![](media/image_identityMapper_2.png)
 
 *Image 4: Workflow diagram for the List Mappings method*
 
 3.  **Delete Mappings:** The workflow below illustrates the steps the service should implement to delete the mapping for a given organization and person.
 
-![](media/image_identityMapper_5.png)
+![](media/image_identityMapper_1.png)
 
 *Image 5: Workflow diagram for the Delete Mappings method*
 
 ## Design Requirements
 
 ### Performance
 
-The component should provide consistent performance irrespective of the volume of the requests and number of identity mapping records.
+(Possible Future Roadmap Item) The component should provide consistent performance irrespective of the volume of the requests and number of identity mapping records.
 
 ### Concurrency
 
@@ -283,54 +183,7 @@ This exception occurs when uniqueness constrains for External and Internal Ident
 
 TBD
 
-# Detailed Design
-
-This component is designed to be implemented as a serverless component that can be scaled on demand.
-
-## Implementation Model
-
-TBD
-
-## Tools and Technologies
-
-The component is implemented using Python.
-
-## Implementation Requirements
-
-### Data Storage
-
-This component stores data in a SQL database.
-
-### State
-
-This component is stateless and does not maintain any information about any run.
-
-### Concurrency
-
-Being a stateless component, it should be able to scale on demand to address multiple concurrent requests.
-
-### Sync/Async
-
-This component operates in sync mode and the client waits for it to return the result before performing any other activity.
-
-### External Services
-
-This component does not call any external services.
-
-# Deployment Design
-
-## Deployment Environment
-
-The component can be deployed in the cloud using serverless infrastructure such as AWS Step Function or Azure Function. In the on-prem deployment environment, the component can be deployed in a docker container running the data pipeline.
-
-## Deployment Model
-
-TBD
-
-## Deployment Requirements
-
-TBD
-
-## Dependencies
+## Possible Future Roadmap Items
 
-TBD 
+- [Issue #12: Add Identity Mapper Support for Bulk Upload Process](https://github.com/LIF-Initiative/lif-core/issues/12)
+- [Issue #13: Investigate and Improve Identity Mapper Performance](https://github.com/LIF-Initiative/lif-core/issues/13)
diff --git a/projects/lif_identity_mapper_api/README.md b/projects/lif_identity_mapper_api/README.md
@@ -0,0 +1,54 @@
+# LIF Identity Mapper API
+
+The **Identity Mapper API** facilitates the resolution of person identifiers from external partner organizations to the internal identifiers utilized within the organization. It enables cross-organizational sharing of LIF records for individuals using the respective identifiers from each organization.  The API provides simple CRUD operations for managing the mappings.
+
+# Example Usage
+
+## Build the project
+
+Navigate to this folder (where the `pyproject.toml` file is)
+
+``` shell
+./build.sh
+
+```
+
+## Build a docker image from root
+
+``` shell
+./build-docker.sh
+```
+
+## Run the image
+
+``` shell
+docker run --rm --name lif_identity_mapper_api -p 8006:8006 lif-identity-mapper-api
+```
+
+The OpenAPI specification of this FastAPI app can now be accessed at http://localhost:8006/docs#
+
+# Example API Usage
+
+## List
+
+GET http://localhost:8006/organizations/Org1/persons/100075/mappings/
+
+## Save
+
+POST http://localhost:8006/organizations/Org1/persons/100075/mappings/
+with body:
+```json
+[
+  {
+    "lif_organization_id": "Org1",
+    "lif_organization_person_id": "100075",
+    "target_system_id": "Org2",
+    "target_system_person_id_type": "SCHOOL_ASSIGNED_NUMBER",
+    "target_system_person_id": "1234567"
+  }
+]
+```
+
+## Delete
+
+DELETE http://localhost:8006/organizations/Org1/persons/100075/mappings/84d1f9c8-8cc8-11f0-976c-06ae7a452344
diff --git a/projects/lif_identity_mapper_mariadb/README.md b/projects/lif_identity_mapper_mariadb/README.md
@@ -0,0 +1,27 @@
+# LIF Identity Mapper MariaDB
+
+The **Identity Mapper MariaDB** project provides a docker-based MariaDB database for storing the identity mappings for the Identity Mapper.
+
+# Example Usage
+
+## Build a docker image from root
+
+``` shell
+./build-docker.sh
+```
+
+## Run the image
+
+``` shell
+docker run --rm --name lif_identity_mapper_mariadb -p 3306:3306 lif-identity-mapper-mariadb
+```
+
+# Connect to the Database
+
+Use these connection parameters:
+
+- host: localhost (or 127.0.0.1)
+- port: 3306
+- schema: lif
+- user: myuser (default) or value for MARIADB_USER environment variable
+- password: mypass (default) or value for MARIADB_PASSWORD environment variable
