[Social Work] Support single and multi-state license types

.github/workflows/check-for-external-state-api-spec-update.yml

@@ -4,6 +4,8 @@ on:
   pull_request:
     paths:
       - backend/compact-connect/stacks/state_api_stack/v1_api/**
+      - backend/cosmetology-app/stacks/state_api_stack/v1_api/**
+      - backend/social-work-app/stacks/state_api_stack/v1_api/**
 
 env:
   AWS_REGION : "us-east-1"
@@ -30,30 +32,61 @@ jobs:
 
       - name: Check for API spec update
         run: |
-          echo "Checking if OpenAPI specification has been updated..."
-          echo "Since API stack files were modified (trigger condition), verifying spec file was also updated."
+          set -euo pipefail
+
+          echo "Checking if state OpenAPI specification has been updated..."
+          echo "Verifying each project whose state API stack changed also updated its spec file."
 
-          # Get the base branch from GitHub context
           BASE_BRANCH="${{ github.event.pull_request.base.ref }}"
           echo "Base branch: $BASE_BRANCH"
 
-          # Check if the OpenAPI spec file was updated using the suggested git diff command
-          SPEC_FILE_PATH="backend/compact-connect/docs/api-specification/latest-oas30.json"
-          echo "Checking for changes to: $SPEC_FILE_PATH"
+          PROJECTS=(
+            compact-connect
+            cosmetology-app
+            social-work-app
+          )
 
-          CHANGED_SPEC_FILE=$(git diff origin/$BASE_BRANCH..HEAD --name-only -- '**/docs/api-specification/latest-oas30.json')
+          FAILED=0
+          CHECKED=0
 
-          if [ -n "$CHANGED_SPEC_FILE" ]; then
-            echo "✅ SUCCESS: State OpenAPI spec file was updated: $SPEC_FILE_PATH"
-          else
-            echo ""
-            echo "🚨 ERROR: State API stack files were modified but the State OpenAPI specification was not updated!"
+          check_project() {
+            local project="$1"
+            local api_path="backend/${project}/stacks/state_api_stack/v1_api"
+            local spec_path="backend/${project}/docs/api-specification/latest-oas30.json"
+
+            if ! git diff "origin/${BASE_BRANCH}..HEAD" --name-only -- "$api_path" | grep -q .; then
+              return 0
+            fi
+
+            CHECKED=$((CHECKED + 1))
             echo ""
-            echo "When you modify API stack files, you must also update the OpenAPI specification at:"
-            echo "  $SPEC_FILE_PATH"
+            echo "Detected changes under: ${api_path}"
+
+            if git diff "origin/${BASE_BRANCH}..HEAD" --name-only -- "$spec_path" | grep -q .; then
+              echo "✅ ${project}: state OpenAPI spec updated at ${spec_path}"
+            else
+              echo "🚨 ${project}: state API stack changed but state OpenAPI spec was not updated!"
+              echo "   Update: ${spec_path}"
+              FAILED=1
+            fi
+          }
+
+          for project in "${PROJECTS[@]}"; do
+            check_project "$project"
+          done
+
+          if [ "$CHECKED" -eq 0 ]; then
             echo ""
-            echo "This ensures that the API documentation stays in sync with the implementation."
+            echo "No state API stack changes detected for monitored projects; nothing to verify."
+            exit 0
+          fi
+
+          if [ "$FAILED" -ne 0 ]; then
             echo ""
-            echo "Please update the OpenAPI spec file and commit it to this PR."
+            echo "When you modify state API stack files, you must also update that project's OpenAPI specification."
+            echo "This ensures API documentation stays in sync with the implementation."
             exit 1
           fi
+
+          echo ""
+          echo "✅ SUCCESS: All projects with state API stack changes also updated their OpenAPI spec."

.github/workflows/check-for-internal-api-spec-update.yml

@@ -4,6 +4,8 @@ on:
   pull_request:
     paths:
       - backend/compact-connect/stacks/api_stack/v1_api/**
+      - backend/cosmetology-app/stacks/api_stack/v1_api/**
+      - backend/social-work-app/stacks/api_stack/v1_api/**
 
 env:
   AWS_REGION : "us-east-1"
@@ -30,30 +32,62 @@ jobs:
 
       - name: Check for API spec update
         run: |
+          set -euo pipefail
+
           echo "Checking if OpenAPI specification has been updated..."
-          echo "Since API stack files were modified (trigger condition), verifying spec file was also updated."
+          echo "Verifying each project whose internal API stack changed also updated its spec file."
 
           # Get the base branch from GitHub context
           BASE_BRANCH="${{ github.event.pull_request.base.ref }}"
           echo "Base branch: $BASE_BRANCH"
 
-          # Check if the OpenAPI spec file was updated
-          SPEC_FILE_PATH="backend/compact-connect/docs/internal/api-specification/latest-oas30.json"
-          echo "Checking for changes to: $SPEC_FILE_PATH"
+          PROJECTS=(
+            compact-connect
+            cosmetology-app
+            social-work-app
+          )
 
-          CHANGED_SPEC_FILE=$(git diff origin/$BASE_BRANCH..HEAD --name-only -- '**/internal/api-specification/latest-oas30.json')
+          FAILED=0
+          CHECKED=0
 
-          if [ -n "$CHANGED_SPEC_FILE" ]; then
-            echo "✅ SUCCESS: OpenAPI spec file was updated: $SPEC_FILE_PATH"
-          else
-            echo ""
-            echo "🚨 ERROR: API stack files were modified but the OpenAPI specification was not updated!"
+          check_project() {
+            local project="$1"
+            local api_path="backend/${project}/stacks/api_stack/v1_api"
+            local spec_path="backend/${project}/docs/internal/api-specification/latest-oas30.json"
+
+            if ! git diff "origin/${BASE_BRANCH}..HEAD" --name-only -- "$api_path" | grep -q .; then
+              return 0
+            fi
+
+            CHECKED=$((CHECKED + 1))
             echo ""
-            echo "When you modify API stack files, you must also update the OpenAPI specification at:"
-            echo "  $SPEC_FILE_PATH"
+            echo "Detected changes under: ${api_path}"
+
+            if git diff "origin/${BASE_BRANCH}..HEAD" --name-only -- "$spec_path" | grep -q .; then
+              echo "✅ ${project}: internal OpenAPI spec updated at ${spec_path}"
+            else
+              echo "🚨 ${project}: API stack changed but internal OpenAPI spec was not updated!"
+              echo "   Update: ${spec_path}"
+              FAILED=1
+            fi
+          }
+
+          for project in "${PROJECTS[@]}"; do
+            check_project "$project"
+          done
+
+          if [ "$CHECKED" -eq 0 ]; then
             echo ""
-            echo "This ensures that the API documentation stays in sync with the implementation."
+            echo "No internal API stack changes detected for monitored projects; nothing to verify."
+            exit 0
+          fi
+
+          if [ "$FAILED" -ne 0 ]; then
             echo ""
-            echo "Please update the OpenAPI spec file and commit it to this PR."
+            echo "When you modify API stack files, you must also update that project's OpenAPI specification."
+            echo "This ensures API documentation stays in sync with the implementation."
             exit 1
           fi
+
+          echo ""
+          echo "✅ SUCCESS: All projects with internal API stack changes also updated their OpenAPI spec."

backend/compact-connect/lambdas/python/common/cc_common/data_model/provider_record_util.py

@@ -402,8 +402,35 @@ def construct_simplified_privilege_history_object(
 
 class ProviderUserRecords:
     """
-    A collection of provider records for a single provider.
-    This class is used to get all records for a single provider and provide utilities for getting specific records
+    Canonical read-side abstraction for how a single provider's data is stored in DynamoDB.
+
+    In storage, a provider is represented by many separate DynamoDB items (provider
+    profile, licenses, updates, adverse actions, investigations, and related types).
+    This class treats those items as one logical collection for a single provider and
+    exposes a simplified, provider-centric interface for querying and deriving views
+    of that data.
+
+    Cross-record business rules belong here so they are not duplicated elsewhere.
+    That includes how privileges are derived, how OpenSearch index documents are
+    built, and other provider-wide behavior (i.e. API response shaping). Do not
+    reimplement that logic in handlers, Lambdas, or background jobs; extend this
+    class when those rules change so APIs, search indexing, and downstream consumers
+    stay consistent.
+
+    Any code that needs to read or derive provider-scoped data should use
+    this class rather than querying individual DynamoDB records directly.
+    Obtain instances via ``DataClient.get_provider_user_records`` in
+    ``data_client.py``: it queries the provider's DynamoDB partition, paginates
+    until all matching items are collected, and passes them to ``ProviderUserRecords``.
+    By default only main records are loaded (``sk`` values beginning with
+    ``{compact}#PROVIDER``); pass ``include_update_tier`` when update or history
+    records up to a given tier are required. Raises ``CCNotFoundException`` when the
+    provider has no items.
+
+    On initialization, raw dict records are categorized by type and converted to
+    typed data classes for efficient access. The ``provider_records`` attribute
+    retains the original dicts for code paths that have not migrated to the
+    data-class pattern.
     """
 
     def __init__(self, provider_records: Iterable[dict]):

backend/cosmetology-app/docs/devops/STAFF_USER_MFA_RECOVERY.md

@@ -9,7 +9,7 @@ users DynamoDB table to track permissions and other account data about the user.
 
 Unfortunately, AWS Cognito does not provide a way to reset or recover a user’s MFA configuration. If a staff user loses access to their MFA device, the Cognito user account must be deleted and recreated in order to enroll a new MFA device. In CompactConnect, the DynamoDB staff-user record is keyed by the Cognito user ID (sub), and that identifier is referenced by system audit events (for example, when a staff user deactivates or encumbers a privilege). 
 
-Recreating a Cognito user always generates a new sub. Reusing or mutating the existing DynamoDB staff-user record would retroactively change the meaning of historical audit events. To preserve audit integrity and traceability, the DynamoDB record with the original sub must therefore be archived, and a new staff-user record must be created for the newly recreated Cognito user. In the future, staff-user records should be decoupled from Cognito sub values (for example, by referencing email). Until that migration is completed and the process is automated, support staff must assist with deleting Cognito accounts and archiving staff-user records when a staff user loses access to their MFA device.
+Recreating a Cognito user always generates a new sub. Reusing or mutating the existing DynamoDB staff-user record would retroactively change the meaning of historical audit events. To preserve audit integrity and traceability, the DynamoDB record with the original sub must therefore be archived, and a new staff-user record must be created for the newly recreated Cognito user. Support staff must assist with deleting Cognito accounts and archiving staff-user records when a staff user loses access to their MFA device.
 
 This document provides step-by-step instructions to recover the user's access while preserving their historical record for audit and traceability purposes.
 
@@ -41,18 +41,15 @@ Before beginning this procedure, ensure you have:
 
 ### Step 2: Archive the DynamoDB Record
 
-In the DynamoDB console, if you change the partition key (pk) value of a existing DynamoDB item, it automatically deletes the old record with the old pk and creates a new one with the new pk, effectively archiving the user record. Perform the following steps:
+In the DynamoDB console, perform the following steps:
 
-1. **Create the Archived Record**
    - In the DynamoDB table, find the existing staff user record and select it to open the 'Edit item' view.
-   - Update the item pk with the following structure:
-     - `pk` = `ARCHIVED_USER#{staff user email}`
-     - **Add a new field**: `archivedDate` = current date (yyyy-mm-dd format)
-     - **Add a new field**: `archivedReason` = "MFA recovery - user lost access to MFA device"
-     - A box should appear at the bottom that states the item will be deleted and recreated, click the box.
-     - Click the 'Recreate item' button to create the archived record, this will delete the old record and create a new archived record
-     - Verify the archived record was created successfully
-     - Note the permissions of the archived user for when the user is re-invited into the system.
+   - **Add a new field**: `archivedDate` = current date (yyyy-mm-dd format)
+   - **Add a new field**: `archivedReason` = "MFA recovery - user lost access to MFA device"
+   - **Remove field**: `famGiv`. If this field is not removed from the record, the user will continue to show up in the list of staff users in the UI, since we use this field in the index used to lookup the list of staff users (the first and last name of the staff user are still recorded under the `attributes` field, so no data is lost by removing the `famGiv` index field).
+   - Click the 'Save and close' button to archive the record
+   - Verify the archived record was updated successfully
+   - Note the permissions of the archived user for when the user is re-invited into the system.
 
 ### Step 3: Delete the Cognito User Account
 

backend/cosmetology-app/lambdas/python/common/cc_common/data_model/provider_record_util.py

@@ -139,8 +139,35 @@ def populate_provider_record(current_provider_record: ProviderData | None, licen
 
 class ProviderUserRecords:
     """
-    A collection of provider records for a single provider.
-    This class is used to get all records for a single provider and provide utilities for getting specific records
+    Canonical read-side abstraction for how a single provider's data is stored in DynamoDB.
+
+    In storage, a provider is represented by many separate DynamoDB items (provider
+    profile, licenses, updates, adverse actions, investigations, and related types).
+    This class treats those items as one logical collection for a single provider and
+    exposes a simplified, provider-centric interface for querying and deriving views
+    of that data.
+
+    Cross-record business rules belong here so they are not duplicated elsewhere.
+    That includes how privileges are derived, how OpenSearch index documents are
+    built, and other provider-wide behavior (i.e. API response shaping). Do not
+    reimplement that logic in handlers, Lambdas, or background jobs; extend this
+    class when those rules change so APIs, search indexing, and downstream consumers
+    stay consistent.
+
+    Any code that needs to read or derive provider-scoped data should use
+    this class rather than querying individual DynamoDB records directly.
+    Obtain instances via ``DataClient.get_provider_user_records`` in
+    ``data_client.py``: it queries the provider's DynamoDB partition, paginates
+    until all matching items are collected, and passes them to ``ProviderUserRecords``.
+    By default only main records are loaded (``sk`` values beginning with
+    ``{compact}#PROVIDER``); pass ``include_update_tier`` when update or history
+    records up to a given tier are required. Raises ``CCNotFoundException`` when the
+    provider has no items.
+
+    On initialization, raw dict records are categorized by type and converted to
+    typed data classes for efficient access. The ``provider_records`` attribute
+    retains the original dicts for code paths that have not migrated to the
+    data-class pattern.
     """
 
     def __init__(self, provider_records: Iterable[dict]):

backend/cosmetology-app/lambdas/python/common/cc_common/feature_flag_enum.py

@@ -10,5 +10,3 @@ class FeatureFlagEnum(StrEnum):
 
     # flag used by internal testing
     TEST_FLAG = 'test-flag'
-    # runtime flags
-    DUPLICATE_SSN_UPLOAD_CHECK_FLAG = 'duplicate-ssn-upload-check-flag'

backend/cosmetology-app/lambdas/python/provider-data-v1/handlers/bulk_upload.py

@@ -13,9 +13,6 @@
 )
 from cc_common.event_batch_writer import EventBatchWriter
 from cc_common.exceptions import CCInternalException
-
-# initialize flag outside of handler so the flag is cached for the lifecycle of the lambda execution environment
-from cc_common.feature_flag_client import FeatureFlagEnum, is_feature_enabled  # noqa: E402
 from cc_common.utils import (
     ResponseEncoder,
     api_handler,
@@ -26,10 +23,6 @@
 from marshmallow import ValidationError
 from marshmallow.exceptions import SCHEMA
 
-duplicate_ssn_check_flag_enabled = is_feature_enabled(
-    FeatureFlagEnum.DUPLICATE_SSN_UPLOAD_CHECK_FLAG, fail_default=True
-)
-
 
 @api_handler
 @authorize_compact_jurisdiction(action='write')
@@ -162,21 +155,20 @@ def process_bulk_upload_file(
                     validated_license = schema.load(dict(compact=compact, jurisdiction=jurisdiction, **raw_license))
                     # verify that this ssn/licenseType combination has not been used previously in the same batch
                     ssn_key = (validated_license['ssn'], validated_license['licenseType'])
-                    if duplicate_ssn_check_flag_enabled:
-                        matched_ssn_index = ssns_in_file_upload.get(ssn_key)
-                        if matched_ssn_index:
-                            # format the validation error as dict so it can be processed by email handler downstream
-                            raise ValidationError(
-                                {
-                                    SCHEMA: [
-                                        f'Duplicate License SSN detected for license type '
-                                        f'{validated_license["licenseType"]}. SSN matches with record '
-                                        f'{matched_ssn_index}. Every record must have a unique SSN per license type '
-                                        f'within the same file.'
-                                    ]
-                                }
-                            )
-                        ssns_in_file_upload.update({ssn_key: i + 1})
+                    matched_ssn_index = ssns_in_file_upload.get(ssn_key)
+                    if matched_ssn_index:
+                        # format the validation error as dict so it can be processed by email handler downstream
+                        raise ValidationError(
+                            {
+                                SCHEMA: [
+                                    f'Duplicate License SSN detected for license type '
+                                    f'{validated_license["licenseType"]}. SSN matches with record '
+                                    f'{matched_ssn_index}. Every record must have a unique SSN per license type '
+                                    f'within the same file.'
+                                ]
+                            }
+                        )
+                    ssns_in_file_upload.update({ssn_key: i + 1})
                 except TypeError as e:
                     # This will be raised, if `raw_license` includes compact and/or jurisdiction fields
                     logger.error('License contains unsupported fields', fields=list(raw_license.keys()), exc_info=e)