1. Architecture Overview

Architecture Type: Three-tier (Controller → Service → Repository)
Multi-Tenant Isolation: providerServiceMapID scoping ensures data separation between providers and states
Session Management: Redis with JWT authentication
Soft Deletion Pattern: deleted flags used across entities for safe deletion
Current System ER Diagram: 

2. Core Entity Relationships

2.1 User Management Structure

Primary User Entity: M_User1

User-Service-Role Mapping: M_UserServiceRoleMapping2

2.2 Multi-Tenant Provider Structure

Provider Service Mapping: M_ProviderServiceMapping

• Maps healthcare providers to states and services

• Creates unique providerServiceMapID per provider-state-service

• Supports geographic and service-line isolation

Geographic Hierarchy

State → District → Block → Village

• Users assigned to blocks/villages via role mapping

• Facilities linked to geographic addresses

3. User Creation and Management Flow

Creation Hierarchy:

1. Provider Creation – Setup healthcare organization

2. Provider-Service-State Mapping – Define operational scope

3. User Creation – Basic profile in M_User1

4. Role Assignment – Map users to services and facilities

Step-by-Step Process:

4. Facility Management

4.1 Facility Structure

Entity: M_Facility

4.2 Main/Sub Store Logic

UI Implications:

• Radio buttons for Main vs Sub Store

• Conditional dropdown for parent store (only Sub Store)

• Mapping via /mapStore endpoint

4.3 Healthcare Facility Hierarchy Integration

• Existing Main/Sub Store logic remains

• New healthcare hierarchy: District Hospital → CHC → PHC → Subcenter

• Both hierarchies coexist:

• storeType used for inventory logic

• healthcareLevel used for healthcare logic

• Note: Existing /mapStore logic unchanged

5. Geographic & Village Management

• Multi-village assignments stored in villageidDb

• Supports field workers (ASHA/ANM) covering multiple villages

• Subcenter assignment via workingLocationID

• Organized at block level

6. Role and Permission System

• Flat role model: M_Role

• Screen-level permissions: RoleScreenMapping

• Multi-role assignments supported

• Role updates/deletions supported

• Optional CTI integration for call centers

7. Services and UI Components NOT Affected

7.1 MMU/Van Services:

• Van-facility mapping: M_VanSpokeMapping

• Van service point mapping: M_VanServicePointMap

• Parking place & van master repositories unaffected

7.2 Inventory Management:

• Main/Sub Store hierarchy maintained

• Item-facility mapping (M_itemfacilitymapping) unchanged

• Stock entry/allocation unaffected

7.3 User Management:

• /m/AddEmployee and role assignments unchanged

• ASHA worker village assignments preserved

7.4 Facility Types:

• M_facilitytype remains

• Store controller endpoints unchanged

7.5 File Upload Systems:

• Facility upload (/saveFacility) continues

• Existing file processing maintained

Note: Healthcare fields are additive and nullable; zero disruption to current system.

8. User & Entity Mapping Architecture

Central Junction Table: M_UserServiceRoleMapping2

Connection Examples:

• ASHA Worker “Sunita”: providerServiceMapID=123, workingLocationID=456, blockID=78, villages=101–105, roleID=5

• MMU Driver “Ramesh”: parkingPlaceID=789, vanID=45, multiple districts, roleID=12

Data Flow Summary:

• Hub-and-spoke model: Provider → State → District → Block → Villages

• Supports static facility and mobile unit assignments

• Scoped by providerServiceMapID for multi-tenancy

9. Multi-Role Assignment Architecture

Key Features:

• Flexible multi-role assignment

• Geographic context for field roles

• Service line isolation via providerServiceMapID

• Screen-based access control

Note: Junction table pattern enables complex multi-role assignments; audit trails and soft deletion supported

10. Summary

The PSMRI/Admin-API provides: Comprehensive user and role management Geographic and service-line isolation Support for multi-village field workers and MMU operations Scalable three-tier architecture with audit trails Additive healthcare facility hierarchy without affecting existing systems

11. Proposed New Implementation – Healthcare Facility Hierarchy (To-Be)

11.1 Purpose of the New Implementation

The existing facility model is optimized for inventory and MMU operations using a Main Store / Sub Store structure.
However, healthcare delivery requires a clinical hierarchy aligned with public health systems.

This new implementation introduces a healthcare-focused hierarchy to support:

• Referral pathways

• Clinical reporting

• ABDM (HFR) compliance

• State-level healthcare structuring
  
  
  
  
  

11.2 Design Principle

Separation of Concerns

11.3 Enhanced M_Facility Entity (Additive Only)

The existing M_Facility table is extended, not modified.

Newly Added Nullable Fields

• stateID

• districtID

• blockID

• hfrID

• healthcareLevel (DH, CHC, PHC, SC)

Why This Works

• Existing records remain valid

• No migration risk

• Inventory logic continues using storeType

• Healthcare logic uses healthcareLevel

storeType and healthcareLevel operate independently

11.4 New M_HealthcareFacilityHierarchy Table

A new dedicated table is introduced to model healthcare relationships.

Purpose

• Represent clinical hierarchy:
  District Hospital → CHC → PHC → Subcenter

• Enable structured referrals and reporting

• Keep healthcare logic separate from store logic

Key Characteristics

• Self-referencing parent–child relationship

• Healthcare-level validation rules

• HFR ID mapping for ABDM

• Audit fields and soft deletion

This table does not replace mapStore or Main/Sub Store logic.

11.5 Hierarchy Coexistence Model

Both hierarchies exist in parallel, serving different purposes.

11.6 API Enhancements (Non-Breaking)

Extended / New APIs

• /createStore – accepts optional healthcare fields

• /editStore – updates healthcare attributes

• /getFacilityHierarchy – returns healthcare tree

• /validateFacilityHierarchy – validates DH→CHC→PHC→SC rules

Important Note

• Existing API consumers do not need changes

• Healthcare parameters are optional

• Current flows remain intact

11.7 UI Enhancements (Proposed)

Facility Creation Screen

Current UI

• Radio buttons: Main Store / Sub Store

New UI (Additive)

• Dropdown: Facility Type

  • District Hospital (DH)

  • CHC / Block

  • PHC / UPHC

  • Subcenter (SC)

Inventory UI behavior remains unchanged.

11.8 What Is NOT Changing (Reconfirmed)

The following remain 100% untouched:

• Main/Sub Store mapping

• MMU, Van, and parking logic

• Inventory & stock management

• User creation and role assignment

• Village coverage logic

• File upload and bulk import processes