Client-stepper: pre-fill existing KYC/address proofs in edit, fix identifier saves

Edit-mode now shows the previously selected KYC document type + uploaded file thumbnail
(loads from /clients/{id}/identifiers + /client_identifiers/{id}/documents). Same for
address proof on the India address step. Closes the gap where editing a client showed
an empty file picker even when proof had been uploaded on create.

Identifier-save hardened across all three callsites (create-client, edit-client,
identities-tab.createIdentifierWithDocs) - the KYC chip picker proofId is a CODE
string ('AADHAAR'), but backend ClientIdentifierRequest.documentTypeId is Long, which
Spring rejects with HttpMessageNotReadableException -> 400. resolveDocumentTypeId
helper looks up the code against /kyc/proof-types?type=id and substitutes the numeric
CodeValue id before posting. Skips silently for constitution-specific non-individual
docs that have no CodeValue mapping.

KYC payload normalises panNumber / enterprisePan / gstinNumber / cinNumber via
toUpperCase + whitespace strip so user-typed lowercase or trailing spaces don't trip
the backend regex (validation.msg.CLIENTKYC.panNumber.does.not.match.regexp).

State name match in client-address save now normalises both sides (lowercase, collapse
underscores + spaces) so legacy MADHYA_PRADESH resolves to 'Madhya Pradesh' returned
by api.postalpincode.in. Backed by tenant migration 0297.

Identities-tab resolver flattened - was returning identifiers before the per-row
forkJoin(getClientIdentificationDocuments) completed, so the view rendered empty
documents arrays. Now uses switchMap + forkJoin so the resolver awaits completion.

Also bundles concurrent work-in-progress on letter-mgmt, organization, users,
bank-calendar, shell, nominee/notes/identifier dialogs, and theming.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

src/app/clients/client-stepper/_stepper-readonly-overrides.scss

@@ -0,0 +1,186 @@
+/**
+ * Copyright since 2025 Mifos Initiative
+ *
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ */
+
+/**
+ * Shared mixin for the client stepper steps.
+ *
+ * When the per-step `readOnly` flag is on, the host calls `form.disable()` which
+ * cascades Material's default `~0.38 opacity` onto every outlined input,
+ * select, checkbox and label. Visually it reads as "blurry". This mixin keeps
+ * the disabled affordances (no caret, no border highlight on focus, no
+ * pointer cursor on selects) but restores crisp colour + weight so the saved
+ * values stay legible.
+ *
+ * Usage in a step component's .scss:
+ *
+ *   @use '../stepper-readonly-overrides' as readonly;
+ *
+ *   :host {
+ *     @include readonly.readonly-form-overrides;
+ *   }
+ */
+@mixin readonly-form-overrides {
+  /* ─── MDC design-token overrides ───
+     These CSS custom properties feed Material's disabled-state colors at the
+     token level — higher in the cascade than any rule selector — so they win
+     even against Material's own !important declarations baked into MDC styles. */
+  --mdc-outlined-text-field-disabled-input-text-color: #0f172a;
+  --mdc-outlined-text-field-disabled-label-text-color: #64748b;
+  --mdc-outlined-text-field-disabled-outline-color: #cbd5e1;
+  --mdc-outlined-text-field-disabled-supporting-text-color: #64748b;
+  --mdc-outlined-text-field-disabled-leading-icon-color: #475569;
+  --mdc-outlined-text-field-disabled-trailing-icon-color: #475569;
+  --mdc-filled-text-field-disabled-input-text-color: #0f172a;
+  --mdc-filled-text-field-disabled-label-text-color: #64748b;
+  --mat-select-disabled-trigger-text-color: #0f172a;
+  --mat-form-field-disabled-input-text-color: #0f172a;
+  --mat-form-field-disabled-input-text-placeholder-color: #64748b;
+  --mdc-checkbox-disabled-selected-icon-color: #059669;
+  --mdc-checkbox-disabled-unselected-icon-color: #94a3b8;
+
+  ::ng-deep {
+    /* Outlined form fields in disabled state */
+    .mat-mdc-form-field.mat-form-field-appearance-outline.mat-form-field-disabled {
+      opacity: 1;
+
+      /* Input value */
+      .mat-mdc-input-element,
+      input.mat-mdc-input-element,
+      textarea.mat-mdc-input-element {
+        color: #0f172a !important;
+        -webkit-text-fill-color: #0f172a !important;
+        font-weight: 600;
+        caret-color: transparent;
+      }
+
+      /* Floating label */
+      .mat-mdc-floating-label,
+      .mdc-floating-label {
+        color: #64748b !important;
+        opacity: 1 !important;
+      }
+
+      /* Outline border */
+      .mdc-notched-outline__leading,
+      .mdc-notched-outline__notch,
+      .mdc-notched-outline__trailing {
+        border-color: #cbd5e1 !important;
+        border-width: 1px !important;
+      }
+
+      /* matPrefix / matSuffix icons */
+      .field-prefix-icon mat-icon,
+      .mat-mdc-form-field-icon-prefix mat-icon,
+      .mat-mdc-form-field-icon-suffix mat-icon {
+        color: #475569 !important;
+        opacity: 1;
+      }
+
+      /* Hint text */
+      .mat-mdc-form-field-hint {
+        color: #64748b !important;
+        opacity: 1;
+      }
+
+      /* mat-select value + arrow.
+         MDC nests the visible text deeper than `.mat-mdc-select-value` — the
+         actual `<span>` that renders the chosen option is `.mat-mdc-select-min-line`.
+         Without explicitly forcing it, MDC's disabled-state CSS wins and the
+         text reads as washed-out grey. */
+      .mat-mdc-select-value-text,
+      .mat-mdc-select-value,
+      .mat-mdc-select-min-line,
+      .mat-mdc-select-placeholder {
+        color: #0f172a !important;
+        -webkit-text-fill-color: #0f172a !important;
+        font-weight: 600;
+        opacity: 1 !important;
+      }
+
+      .mat-mdc-select-arrow {
+        color: #94a3b8 !important;
+      }
+
+      /* The disabled select wrapper itself drops opacity in MDC — undo that. */
+      .mat-mdc-select-disabled,
+      .mat-mdc-select-disabled .mat-mdc-select-trigger {
+        opacity: 1 !important;
+      }
+
+      /* The MDC text-field root (parent of input + outline) also gets a
+         disabled modifier. Strip any opacity it applies. */
+      .mdc-text-field--disabled {
+        opacity: 1 !important;
+
+        .mdc-text-field__input,
+        input,
+        textarea {
+          color: #0f172a !important;
+          -webkit-text-fill-color: #0f172a !important;
+          opacity: 1 !important;
+        }
+      }
+
+      /* Native suffix icon buttons (e.g. eye-toggle) */
+      .toggle-vis-btn,
+      .mat-mdc-icon-button {
+        color: #64748b !important;
+        opacity: 1;
+      }
+    }
+
+    /* Disabled checkboxes — keep the check + label crisp */
+    .mat-mdc-checkbox-disabled {
+      opacity: 1 !important;
+
+      .mdc-form-field > label,
+      .mat-mdc-checkbox-label,
+      .mdc-label {
+        color: #0f172a !important;
+        opacity: 1 !important;
+        font-weight: 500;
+      }
+
+      .mdc-checkbox__background {
+        background-color: #059669 !important;
+        border-color: #059669 !important;
+      }
+
+      .mdc-checkbox__checkmark {
+        color: #fff !important;
+      }
+    }
+
+    /* Disabled mat-radio */
+    .mat-mdc-radio-button.mat-mdc-radio-disabled {
+      opacity: 1 !important;
+
+      .mdc-form-field > label,
+      .mdc-label {
+        color: #0f172a !important;
+        opacity: 1 !important;
+        font-weight: 500;
+      }
+    }
+
+    /* Disabled mat-slide-toggle */
+    .mat-mdc-slide-toggle.mat-mdc-slide-toggle-disabled {
+      opacity: 1 !important;
+    }
+
+    /* Native UA override — Chrome/Safari force their own grey on disabled
+       form controls via `-webkit-text-fill-color`, which beats `color`. */
+    input:disabled,
+    select:disabled,
+    textarea:disabled {
+      color: #0f172a !important;
+      -webkit-text-fill-color: #0f172a !important;
+      opacity: 1 !important;
+    }
+  }
+}

src/app/clients/client-stepper/client-address-step/client-address-step.component.scss

@@ -105,3 +105,59 @@
     grid-template-columns: 1fr;
   }
 }
+
+/* ═══════════════════════════════════════════════════════════════
+   Read-only / disabled form-field overrides
+   ─── Mirrors the India-address step so view-mode addresses stay
+        legible instead of looking ghosted at 0.38 opacity.
+   ═══════════════════════════════════════════════════════════════ */
+:host ::ng-deep {
+  .mat-mdc-form-field.mat-form-field-appearance-outline.mat-form-field-disabled {
+    opacity: 1;
+
+    .mat-mdc-input-element,
+    input.mat-mdc-input-element,
+    textarea.mat-mdc-input-element {
+      color: #0f172a !important;
+      -webkit-text-fill-color: #0f172a !important;
+      font-weight: 600;
+      caret-color: transparent;
+    }
+
+    .mat-mdc-floating-label,
+    .mdc-floating-label {
+      color: #64748b !important;
+      opacity: 1 !important;
+    }
+
+    .mdc-notched-outline__leading,
+    .mdc-notched-outline__notch,
+    .mdc-notched-outline__trailing {
+      border-color: #cbd5e1 !important;
+      border-width: 1px !important;
+    }
+
+    .field-prefix-icon mat-icon,
+    .mat-mdc-form-field-icon-prefix mat-icon,
+    .mat-mdc-form-field-icon-suffix mat-icon {
+      color: #475569 !important;
+      opacity: 1;
+    }
+
+    .mat-mdc-form-field-hint {
+      color: #64748b !important;
+      opacity: 1;
+    }
+
+    .mat-mdc-select-value-text,
+    .mat-mdc-select-value {
+      color: #0f172a !important;
+      -webkit-text-fill-color: #0f172a !important;
+      font-weight: 600;
+    }
+
+    .mat-mdc-select-arrow {
+      color: #94a3b8 !important;
+    }
+  }
+}

src/app/clients/client-stepper/client-datatable-step/client-datatable-step.component.scss

@@ -6,6 +6,12 @@
  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
  */
 
+@use '../stepper-readonly-overrides' as readonly;
+
+:host {
+  @include readonly.readonly-form-overrides;
+}
+
 .date-picker {
   width: 92%;
 }

src/app/clients/client-stepper/client-entity-kyc-step/client-entity-kyc-step.component.scss

@@ -6,6 +6,12 @@
  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
  */
 
+@use '../stepper-readonly-overrides' as readonly;
+
+:host {
+  @include readonly.readonly-form-overrides;
+}
+
 /**
  * Entity Classification — Scheme & Sector Classification
  */

src/app/clients/client-stepper/client-family-members-step/client-family-member-dialog/client-family-member-dialog.component.ts

@@ -259,7 +259,10 @@ export class ClientFamilyMemberDialogComponent implements OnInit {
       // non-individuals (companies / trusts) have no person-to-person relationship to model here.
       this.clientsService.searchByText(text, 0, 8, '', '', true, 'INDIVIDUAL').subscribe({
         next: (data: any) => {
-          this.searchResults = data?.content || [];
+          // Filter the host client out of results so they can't even appear as
+          // a candidate. The dialog also blocks selection defensively in case
+          // the host slips through (e.g. via a paged search).
+          this.searchResults = (data?.content || []).filter((c: any) => !this.isSelfClient(c?.id));
           this.searching = false;
           this.clientsService.enrichSearchResults(this.searchResults);
         },
@@ -278,6 +281,17 @@ export class ClientFamilyMemberDialogComponent implements OnInit {
    */
   linkedSelectError = '';
 
+  /**
+   * Self-check: prevent a client from being added as their own family member.
+   * The host client's id is passed in via dialog data — comparing as strings
+   * because the search API uses numbers but route params are strings.
+   */
+  isSelfClient(clientId: number | string): boolean {
+    const host = this.data?.hostClientId;
+    if (host == null || clientId == null) return false;
+    return String(host) === String(clientId);
+  }
+
   /**
    * True if the given client id is already linked as a family member of
    * this client. The member currently being edited is excluded so its own
@@ -298,6 +312,10 @@ export class ClientFamilyMemberDialogComponent implements OnInit {
 
   /** Select a client from search results and fetch full details */
   selectClient(client: any): void {
+    if (this.isSelfClient(client?.id)) {
+      this.linkedSelectError = `You can't add this client to their own family. Please pick a different person.`;
+      return;
+    }
     if (this.isClientAlreadyLinked(client?.id)) {
       this.linkedSelectError = `${client?.displayName || 'This client'} is already linked as a family member.`;
       return;

src/app/clients/client-stepper/client-family-members-step/client-family-members-step.component.scss

@@ -6,6 +6,12 @@
  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
  */
 
+@use '../stepper-readonly-overrides' as readonly;
+
+:host {
+  @include readonly.readonly-form-overrides;
+}
+
 .zoomable {
   cursor: zoom-in;
   transition:

src/app/clients/client-stepper/client-family-members-step/client-family-members-step.component.ts

@@ -135,7 +135,8 @@ export class ClientFamilyMembersStepComponent implements OnInit {
       data: {
         context: 'Add',
         options: this.clientTemplate.familyMemberOptions,
-        existingMembers: this.clientFamilyMembers
+        existingMembers: this.clientFamilyMembers,
+        hostClientId: this.clientId
       },
       width: '640px',
       maxWidth: '95vw',
@@ -154,7 +155,8 @@ export class ClientFamilyMembersStepComponent implements OnInit {
         context: 'View',
         member,
         options: this.clientTemplate.familyMemberOptions,
-        existingMembers: this.clientFamilyMembers
+        existingMembers: this.clientFamilyMembers,
+        hostClientId: this.clientId
       },
       width: '640px',
       maxWidth: '95vw',
@@ -168,7 +170,8 @@ export class ClientFamilyMembersStepComponent implements OnInit {
         context: 'Edit',
         member,
         options: this.clientTemplate.familyMemberOptions,
-        existingMembers: this.clientFamilyMembers
+        existingMembers: this.clientFamilyMembers,
+        hostClientId: this.clientId
       },
       width: '640px',
       maxWidth: '95vw',

src/app/clients/client-stepper/client-general-step/client-general-step.component.scss

@@ -6,6 +6,12 @@
  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
  */
 
+@use '../stepper-readonly-overrides' as readonly;
+
+:host {
+  @include readonly.readonly-form-overrides;
+}
+
 form {
   padding: 0;
 }

src/app/clients/client-stepper/client-india-address-step/client-india-address-step.component.html

@@ -123,7 +123,7 @@
 
         <div class="addr-proof-field">
           <label class="addr-proof-label"><mat-icon>description</mat-icon> Document type</label>
-          <div class="addr-chip-wrap">
+          <div class="addr-chip-wrap" [class.addr-chip-wrap--locked]="readOnly">
             @for (group of addressGroups; track group.label; let last = $last) {
               <div class="addr-chip-group-label"><mat-icon>folder_open</mat-icon> {{ group.label }}</div>
               <div class="addr-chip-grid">
@@ -131,9 +131,11 @@
                   <span
                     class="addr-chip"
                     [class.addr-chip--sel]="isAddrProofSelected(p)"
-                    (click)="selectAddrProof(p)"
-                    (keydown.enter)="selectAddrProof(p)"
-                    tabindex="0"
+                    [class.addr-chip--locked]="readOnly && !isAddrProofSelected(p)"
+                    [attr.aria-disabled]="readOnly ? 'true' : null"
+                    (click)="readOnly ? null : selectAddrProof(p)"
+                    (keydown.enter)="readOnly ? null : selectAddrProof(p)"
+                    [attr.tabindex]="readOnly ? -1 : 0"
                     role="button"
                   >
                     <mat-icon class="addr-chip__icon">
@@ -186,59 +188,78 @@
                 </span>
                 <span class="addr-upload-req">Required</span>
               </div>
-              <label
-                class="addr-dropzone"
-                [class.addr-dropzone--has]="addrFiles.front"
-                [class.addr-dropzone--req]="!addrFiles.front"
-              >
-                <input type="file" accept=".jpg,.jpeg,.png,.pdf" hidden (change)="onAddrFile($event, 'front')" />
-                @if (addrFiles.front) {
-                  <div class="addr-dropzone__file">
-                    <mat-icon>insert_drive_file</mat-icon>
-                    <span class="addr-dropzone__name">{{ addrFiles.front.name }}</span>
-                    <button
-                      type="button"
-                      mat-icon-button
-                      class="addr-dropzone__remove"
-                      (click)="$event.preventDefault(); removeAddrFile('front')"
-                    >
-                      <mat-icon>close</mat-icon>
-                    </button>
+              <!-- Existing saved document — locked by default. Replace flow
+                   unlocks automatically when the section's top-level Edit
+                   button toggles `readOnly` off. -->
+              @if (existingAddressProofDocuments.length > 0 && !addrFiles.front && readOnly) {
+                <div class="addr-dropzone addr-dropzone--has addr-dropzone--locked">
+                  <div class="addr-dropzone__existing">
+                    @if (addrMergedPreview) {
+                      <img [src]="addrMergedPreview" alt="Saved address proof" class="addr-dropzone__thumb" />
+                    } @else {
+                      <mat-icon class="addr-dropzone__doc-ic">description</mat-icon>
+                    }
+                    <div class="addr-dropzone__existing-meta">
+                      <span class="addr-dropzone__existing-name">
+                        {{ existingAddressProofDocuments[0].fileName || existingAddressProofDocuments[0].name }}
+                      </span>
+                      <button type="button" class="addr-dropzone__view" (click)="viewExistingAddressProof()">
+                        <mat-icon>visibility</mat-icon>
+                        Click here to view
+                      </button>
+                    </div>
                   </div>
-                } @else {
-                  <div class="addr-dropzone__hint">
-                    <mat-icon>cloud_upload</mat-icon>
-                    <span>Click to upload (JPG / PNG / PDF · max 5 MB)</span>
-                  </div>
-                }
-              </label>
-            </div>
-
-            @if (selectedAddrProof.sides === 2) {
-              <div class="addr-upload-slot">
-                <div class="addr-upload-head">
-                  <span class="addr-upload-title"> <mat-icon>image</mat-icon> Back side </span>
-                  <span class="addr-upload-req">Required</span>
                 </div>
+              } @else {
                 <label
                   class="addr-dropzone"
-                  [class.addr-dropzone--has]="addrFiles.back"
-                  [class.addr-dropzone--req]="!addrFiles.back"
+                  [class.addr-dropzone--has]="addrFiles.front || existingAddressProofDocuments.length > 0"
+                  [class.addr-dropzone--req]="!addrFiles.front && existingAddressProofDocuments.length === 0"
                 >
-                  <input type="file" accept=".jpg,.jpeg,.png,.pdf" hidden (change)="onAddrFile($event, 'back')" />
-                  @if (addrFiles.back) {
+                  <input type="file" accept=".jpg,.jpeg,.png,.pdf" hidden (change)="onAddrFile($event, 'front')" />
+                  @if (addrFiles.front) {
                     <div class="addr-dropzone__file">
                       <mat-icon>insert_drive_file</mat-icon>
-                      <span class="addr-dropzone__name">{{ addrFiles.back.name }}</span>
+                      <span class="addr-dropzone__name">{{ addrFiles.front.name }}</span>
                       <button
                         type="button"
                         mat-icon-button
                         class="addr-dropzone__remove"
-                        (click)="$event.preventDefault(); removeAddrFile('back')"
+                        (click)="$event.preventDefault(); removeAddrFile('front')"
                       >
                         <mat-icon>close</mat-icon>
                       </button>
                     </div>
+                  } @else if (existingAddressProofDocuments.length > 0) {
+                    <!-- Edit mode WITH existing doc — let the user view it OR
+                         click anywhere to replace. -->
+                    <div class="addr-dropzone__existing">
+                      @if (addrMergedPreview) {
+                        <img [src]="addrMergedPreview" alt="Saved address proof" class="addr-dropzone__thumb" />
+                      } @else {
+                        <mat-icon class="addr-dropzone__doc-ic">description</mat-icon>
+                      }
+                      <div class="addr-dropzone__existing-meta">
+                        <span class="addr-dropzone__existing-name">
+                          {{ existingAddressProofDocuments[0].fileName || existingAddressProofDocuments[0].name }}
+                        </span>
+                        <div class="addr-dropzone__existing-actions">
+                          <button
+                            type="button"
+                            class="addr-dropzone__view"
+                            (click)="$event.preventDefault(); $event.stopPropagation(); viewExistingAddressProof()"
+                          >
+                            <mat-icon>visibility</mat-icon>
+                            View
+                          </button>
+                          <span class="addr-dropzone__sep">·</span>
+                          <span class="addr-dropzone__existing-hint">
+                            <mat-icon>cloud_upload</mat-icon>
+                            Click here to replace
+                          </span>
+                        </div>
+                      </div>
+                    </div>
                   } @else {
                     <div class="addr-dropzone__hint">
                       <mat-icon>cloud_upload</mat-icon>
@@ -246,11 +267,104 @@
                     </div>
                   }
                 </label>
+              }
+            </div>
+
+            @if (selectedAddrProof.sides === 2) {
+              <div class="addr-upload-slot">
+                <div class="addr-upload-head">
+                  <span class="addr-upload-title"> <mat-icon>image</mat-icon> Back side </span>
+                  <!-- "Required" pill is hidden when a saved combined doc covers both sides -->
+                  @if (!(existingAddressProofDocuments.length > 0 && !addrFiles.back)) {
+                    <span class="addr-upload-req">Required</span>
+                  }
+                </div>
+                <!-- Locked view: saved combined doc covers the back side too. -->
+                @if (existingAddressProofDocuments.length > 0 && !addrFiles.back && readOnly) {
+                  <div class="addr-dropzone addr-dropzone--has addr-dropzone--locked">
+                    <div class="addr-dropzone__existing">
+                      @if (addrMergedPreview) {
+                        <img [src]="addrMergedPreview" alt="Saved address proof" class="addr-dropzone__thumb" />
+                      } @else {
+                        <mat-icon class="addr-dropzone__doc-ic">description</mat-icon>
+                      }
+                      <div class="addr-dropzone__existing-meta">
+                        <span class="addr-dropzone__existing-name">
+                          {{ existingAddressProofDocuments[0].fileName || existingAddressProofDocuments[0].name }}
+                        </span>
+                        <button type="button" class="addr-dropzone__view" (click)="viewExistingAddressProof()">
+                          <mat-icon>visibility</mat-icon>
+                          Click here to view
+                        </button>
+                      </div>
+                    </div>
+                  </div>
+                } @else {
+                  <label
+                    class="addr-dropzone"
+                    [class.addr-dropzone--has]="addrFiles.back || existingAddressProofDocuments.length > 0"
+                    [class.addr-dropzone--req]="!addrFiles.back && existingAddressProofDocuments.length === 0"
+                  >
+                    <input type="file" accept=".jpg,.jpeg,.png,.pdf" hidden (change)="onAddrFile($event, 'back')" />
+                    @if (addrFiles.back) {
+                      <div class="addr-dropzone__file">
+                        <mat-icon>insert_drive_file</mat-icon>
+                        <span class="addr-dropzone__name">{{ addrFiles.back.name }}</span>
+                        <button
+                          type="button"
+                          mat-icon-button
+                          class="addr-dropzone__remove"
+                          (click)="$event.preventDefault(); removeAddrFile('back')"
+                        >
+                          <mat-icon>close</mat-icon>
+                        </button>
+                      </div>
+                    } @else if (existingAddressProofDocuments.length > 0) {
+                      <!-- Edit mode WITH existing combined doc — same view + replace
+                           pattern as the front slot, anchored to the saved file. -->
+                      <div class="addr-dropzone__existing">
+                        @if (addrMergedPreview) {
+                          <img [src]="addrMergedPreview" alt="Saved address proof" class="addr-dropzone__thumb" />
+                        } @else {
+                          <mat-icon class="addr-dropzone__doc-ic">description</mat-icon>
+                        }
+                        <div class="addr-dropzone__existing-meta">
+                          <span class="addr-dropzone__existing-name">
+                            {{ existingAddressProofDocuments[0].fileName || existingAddressProofDocuments[0].name }}
+                          </span>
+                          <div class="addr-dropzone__existing-actions">
+                            <button
+                              type="button"
+                              class="addr-dropzone__view"
+                              (click)="$event.preventDefault(); $event.stopPropagation(); viewExistingAddressProof()"
+                            >
+                              <mat-icon>visibility</mat-icon>
+                              View
+                            </button>
+                            <span class="addr-dropzone__sep">·</span>
+                            <span class="addr-dropzone__existing-hint">
+                              <mat-icon>cloud_upload</mat-icon>
+                              Click here to replace
+                            </span>
+                          </div>
+                        </div>
+                      </div>
+                    } @else {
+                      <div class="addr-dropzone__hint">
+                        <mat-icon>cloud_upload</mat-icon>
+                        <span>Click to upload (JPG / PNG / PDF · max 5 MB)</span>
+                      </div>
+                    }
+                  </label>
+                }
               </div>
             }
           </div>
 
-          @if (selectedAddrProof.sides === 2 && addrMergedPreview) {
+          <!-- Combined preview + re-crop buttons are an edit-mode tool; hide in read-only.
+               Also hide when the saved combined PNG is already visible as the thumbnail
+               inside both slot tiles (no value in repeating the same image below). -->
+          @if (selectedAddrProof.sides === 2 && addrMergedPreview && !readOnly && (addrFiles.front || addrFiles.back)) {
             <div class="addr-merged">
               <div class="addr-merged__head">
                 <span class="addr-merged__title">

src/app/clients/client-stepper/client-india-address-step/client-india-address-step.component.scss

@@ -333,12 +333,35 @@ $muted: #64748b;
     }
   }
 
+  /* Non-selected chip in read-only mode — visible but visibly unclickable.
+     The selected chip keeps its full highlight (no `--locked` class). */
+  &--locked {
+    cursor: default;
+    background: #f8fafc;
+    border-color: #e2e8f0;
+    color: #94a3b8;
+
+    .addr-chip__icon {
+      color: #cbd5e1;
+    }
+
+    &:hover {
+      border-color: #e2e8f0;
+      color: #94a3b8;
+    }
+  }
+
   &:focus-visible {
     outline: 2px solid #1976d2;
     outline-offset: 2px;
   }
 }
 
+/* When the wrap is locked, the selected chip shouldn't show a pointer cursor either. */
+.addr-chip-wrap--locked .addr-chip--sel {
+  cursor: default;
+}
+
 .addr-proof-banner {
   display: flex;
   align-items: center;
@@ -559,4 +582,201 @@ $muted: #64748b;
   &__remove {
     flex-shrink: 0;
   }
+
+  /* Locked variant — used when an existing saved doc is shown but the user
+     hasn't clicked "Edit" yet. Removes the hand-cursor and the green hover. */
+  &--locked {
+    cursor: default;
+
+    &:hover {
+      background: #f0fdf4;
+      border-color: #86efac;
+    }
+  }
+
+  /* Existing saved document (edit mode) — thumbnail + filename + actions. */
+  &__existing {
+    display: flex;
+    align-items: center;
+    gap: 14px;
+    min-width: 0;
+  }
+
+  &__thumb {
+    width: 56px;
+    height: 56px;
+    object-fit: cover;
+    border-radius: 8px;
+    background: #e2e8f0;
+    border: 1px solid #cbd5e1;
+    flex-shrink: 0;
+  }
+
+  &__doc-ic {
+    width: 40px;
+    height: 40px;
+    font-size: 32px;
+    color: #1e88e5;
+    flex-shrink: 0;
+  }
+
+  &__existing-meta {
+    display: flex;
+    flex-direction: column;
+    gap: 6px;
+    min-width: 0;
+    flex: 1;
+  }
+
+  &__existing-name {
+    font-size: 13px;
+    font-weight: 700;
+    color: #0f172a;
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
+  }
+
+  &__existing-actions {
+    display: inline-flex;
+    align-items: center;
+    gap: 4px;
+    flex-wrap: wrap;
+  }
+
+  &__view,
+  &__edit {
+    display: inline-flex;
+    align-items: center;
+    gap: 5px;
+    padding: 4px 10px;
+    border-radius: 6px;
+    font-size: 11.5px;
+    font-weight: 700;
+    cursor: pointer;
+    border: 1px solid transparent;
+    transition: all 0.12s;
+
+    mat-icon {
+      font-size: 14px;
+      width: 14px;
+      height: 14px;
+    }
+  }
+
+  &__view {
+    background: #eff6ff;
+    color: #1e40af;
+    border-color: #bfdbfe;
+
+    &:hover {
+      background: #dbeafe;
+      border-color: #1e40af;
+    }
+  }
+
+  &__edit {
+    background: #fef3c7;
+    color: #92400e;
+    border-color: #fde68a;
+
+    &:hover {
+      background: #fde68a;
+      border-color: #92400e;
+    }
+  }
+
+  &__existing-hint {
+    display: inline-flex;
+    align-items: center;
+    gap: 6px;
+    font-size: 11.5px;
+    color: #1e40af;
+    font-weight: 600;
+
+    mat-icon {
+      font-size: 14px;
+      width: 14px;
+      height: 14px;
+    }
+  }
+}
+
+/* ═══════════════════════════════════════════════════════════════
+   Read-only / disabled form-field overrides
+   ─── When the stepper is in view mode the form is .disable()'d.
+        Material drops opacity to ~0.38 which reads as "blurry". Restore
+        proper contrast so disabled values are still clearly legible.
+   ═══════════════════════════════════════════════════════════════ */
+:host ::ng-deep {
+  .mat-mdc-form-field.mat-form-field-appearance-outline.mat-form-field-disabled {
+    opacity: 1;
+
+    .mat-mdc-input-element,
+    input.mat-mdc-input-element,
+    textarea.mat-mdc-input-element {
+      color: #0f172a !important;
+      -webkit-text-fill-color: #0f172a !important;
+      font-weight: 600;
+      caret-color: transparent;
+    }
+
+    .mat-mdc-floating-label,
+    .mdc-floating-label {
+      color: #64748b !important;
+      opacity: 1 !important;
+    }
+
+    .mdc-notched-outline__leading,
+    .mdc-notched-outline__notch,
+    .mdc-notched-outline__trailing {
+      border-color: #cbd5e1 !important;
+      border-width: 1px !important;
+    }
+
+    .field-prefix-icon mat-icon,
+    .mat-mdc-form-field-icon-prefix mat-icon,
+    .mat-mdc-form-field-icon-suffix mat-icon {
+      color: #475569 !important;
+      opacity: 1;
+    }
+
+    .mat-mdc-form-field-hint {
+      color: #64748b !important;
+      opacity: 1;
+    }
+
+    .mat-mdc-select-value-text,
+    .mat-mdc-select-value {
+      color: #0f172a !important;
+      -webkit-text-fill-color: #0f172a !important;
+      font-weight: 600;
+    }
+
+    .mat-mdc-select-arrow {
+      color: #94a3b8 !important;
+    }
+  }
+
+  /* Disabled checkbox — keep visuals crisp */
+  .mat-mdc-checkbox-disabled {
+    opacity: 1 !important;
+
+    .mdc-form-field > label,
+    .mat-mdc-checkbox-label,
+    .mdc-label {
+      color: #0f172a !important;
+      opacity: 1 !important;
+      font-weight: 500;
+    }
+
+    .mdc-checkbox__background {
+      background-color: #059669 !important;
+      border-color: #059669 !important;
+    }
+
+    .mdc-checkbox__checkmark {
+      color: #fff !important;
+    }
+  }
 }

src/app/clients/client-stepper/client-india-address-step/client-india-address-step.component.ts

@@ -183,6 +183,21 @@ export class ClientIndiaAddressStepComponent implements OnInit, OnChanges {
   addrMergedFile: File | null = null;
   addrMergedPreview: string | null = null;
 
+  /**
+   * Identifier row + attached documents that back the address proof on the server (edit
+   * mode). Populated by loadExistingAddressProof() so the UI can show the file the user
+   * uploaded last time instead of an empty picker.
+   */
+  existingAddressProofIdentifierId: string | null = null;
+  existingAddressProofDocuments: {
+    id: string;
+    name: string;
+    fileName: string;
+    type: string;
+    size: number;
+    previewUrl: string | null;
+  }[] = [];
+
   residenceTypes = [
     'Owned',
     'Rented',
@@ -386,7 +401,18 @@ export class ClientIndiaAddressStepComponent implements OnInit, OnChanges {
             state: addr.stateName || '',
             landmark: addr.street || ''
           });
+
+          // Saved address payloads don't include the PIN's full locality list
+          // or the "verified" status — so the dropdown shows only the saved
+          // value and the green "PIN verified" chip never appears. Re-run the
+          // lookup silently to repopulate options and confirm the PIN, without
+          // overwriting what the user already had on record.
+          if ((addr.postalCode || '').toString().length === 6) {
+            this.silentlyHydratePin(tab);
+          }
         }
+        // Surface the address proof file the user uploaded previously.
+        this.loadExistingAddressProof();
       },
       error: () => {
         this.addressLoaded = true;
@@ -394,6 +420,95 @@ export class ClientIndiaAddressStepComponent implements OnInit, OnChanges {
     });
   }
 
+  /**
+   * Address proof on this UI is persisted as a client_identifier row whose documentType
+   * is one of the address-proof types (see create-client.saveAddressProof). To restore
+   * the picker state and show the existing file in edit mode we:
+   *   1. List the client's identifiers
+   *   2. Find the one whose documentType matches an entry in `addressProofs`
+   *   3. Patch the permanent-form proofId / documentKey from it
+   *   4. Fetch its attached documents and render the first image as a preview
+   */
+  private loadExistingAddressProof(): void {
+    if (!this.clientId) return;
+    // Wait briefly for proof types to load if they're still in flight — they're needed
+    // to filter identifiers down to "address proofs" only.
+    if (this.loadingProofs || this.addressProofs.length === 0) {
+      setTimeout(() => this.loadExistingAddressProof(), 200);
+      return;
+    }
+    this.clientsService.getClientIdentifiers(this.clientId).subscribe({
+      next: (identifiers: any[]) => {
+        if (!identifiers || identifiers.length === 0) return;
+        const proofNames = new Set(this.addressProofs.map((p) => p.name?.toLowerCase()).filter(Boolean));
+        const identifier = identifiers.find((i: any) => {
+          const n = i?.documentType?.name?.toLowerCase();
+          return n && proofNames.has(n);
+        });
+        if (!identifier?.id) return;
+
+        this.existingAddressProofIdentifierId = identifier.id.toString();
+        // Restore selected chip + form values
+        const matchedProof = this.addressProofs.find(
+          (p) => p.name?.toLowerCase() === identifier.documentType?.name?.toLowerCase()
+        );
+        if (matchedProof) {
+          this.selectedAddrProof = matchedProof;
+          this.permanentForm.patchValue({
+            proofId: matchedProof.id,
+            documentKey: identifier.documentKey || ''
+          });
+          // The description carries `Issue date: dd/mm/yyyy` when set on create (see
+          // create-client.saveAddressProof) — pull it out so the form's issueDate field
+          // shows what was previously entered.
+          const desc: string = identifier.description || '';
+          const issueMatch = desc.match(/Issue date:\s*(.+)$/i);
+          if (issueMatch) {
+            this.permanentForm.patchValue({ issueDate: issueMatch[1].trim() });
+          }
+        }
+
+        this.clientsService.getClientIdentificationDocuments(this.existingAddressProofIdentifierId).subscribe({
+          next: (docs: any[]) => {
+            if (!docs || docs.length === 0) return;
+            this.existingAddressProofDocuments = docs.map((d: any) => ({
+              id: d.id?.toString() || '',
+              name: d.name || '',
+              fileName: d.fileName || '',
+              type: d.type || '',
+              size: d.size || 0,
+              previewUrl: null as string | null
+            }));
+            const firstImage = this.existingAddressProofDocuments.find((d) =>
+              (d.type || '').toLowerCase().startsWith('image/')
+            );
+            if (firstImage) {
+              this.clientsService
+                .downloadClientIdentificationDocument(this.existingAddressProofIdentifierId!, firstImage.id)
+                .subscribe({
+                  next: async (blob: any) => {
+                    const buffer = await blob.arrayBuffer();
+                    const bytes = new Uint8Array(buffer);
+                    let binary = '';
+                    for (let i = 0; i < bytes.length; i++) {
+                      binary += String.fromCharCode(bytes[i]);
+                    }
+                    firstImage.previewUrl = 'data:' + blob.type + ';base64,' + btoa(binary);
+                    if (!this.addrMergedPreview) {
+                      this.addrMergedPreview = firstImage.previewUrl;
+                    }
+                  },
+                  error: () => {}
+                });
+            }
+          },
+          error: () => {}
+        });
+      },
+      error: () => {}
+    });
+  }
+
   onPinInput(tab: string) {
     const form = this.getForm(tab);
     const pin = form.get('pinCode')?.value?.replace(/\D/g, '') || '';
@@ -451,12 +566,121 @@ export class ClientIndiaAddressStepComponent implements OnInit, OnChanges {
     });
   }
 
+  /**
+   * Open the saved address proof in a new browser tab.
+   *
+   * For images we already hold a base64 data URL in `previewUrl` from
+   * `loadExistingAddressProof`, so we can hand it straight to `window.open`.
+   * For PDFs / other types we need to fetch the binary blob and create a
+   * temporary object URL so the browser's PDF viewer can render it.
+   */
+  viewExistingAddressProof(): void {
+    if (!this.existingAddressProofIdentifierId || this.existingAddressProofDocuments.length === 0) {
+      return;
+    }
+    const doc = this.existingAddressProofDocuments[0];
+    if (doc.previewUrl) {
+      window.open(doc.previewUrl, '_blank', 'noopener');
+      return;
+    }
+    this.clientsService.downloadClientIdentificationDocument(this.existingAddressProofIdentifierId, doc.id).subscribe({
+      next: (blob: Blob) => {
+        const url = URL.createObjectURL(blob);
+        const w = window.open(url, '_blank', 'noopener');
+        // Revoke after the tab has had time to load — browsers vary, so
+        // err on the side of a generous wait.
+        if (w) {
+          setTimeout(() => URL.revokeObjectURL(url), 60_000);
+        }
+      },
+      error: () => {
+        // Silent fail — UI shows the saved name so user knows it exists.
+      }
+    });
+  }
+
   private clearPinFields(tab: string) {
     this.localityOptions[tab] = [];
     const form = this.getForm(tab);
     form.patchValue({ locality: '', city: '', district: '', state: '' });
   }
 
+  /**
+   * Re-hydrate the PIN lookup for an already-loaded address.
+   *
+   * Used when an existing client opens in edit mode — the form values are
+   * patched from the server, but the locality dropdown options and the
+   * "PIN verified" status are derived state that only `onPinInput` produces.
+   * This variant populates that derived state WITHOUT clobbering the saved
+   * locality / city / district / state the user originally chose.
+   */
+  private silentlyHydratePin(tab: string): void {
+    const form = this.getForm(tab);
+    const pin = (form.get('pinCode')?.value || '').toString().replace(/\D/g, '');
+    if (pin.length !== 6) return;
+
+    const applyOptions = (offices: any[]) => {
+      const seen = new Set<string>();
+      const opts = (offices || [])
+        .filter((o) => {
+          if (!o?.Name || seen.has(o.Name)) return false;
+          seen.add(o.Name);
+          return true;
+        })
+        .map((o) => o.Name);
+      this.localityOptions[tab] = opts;
+      this.pinStatus[tab] = { loading: false, found: true, error: false, message: 'Verified' };
+
+      // If the saved locality isn't part of the options (rare — e.g. spelling
+      // mismatch), prepend it so the bound `<mat-option>` still resolves.
+      const savedLocality = form.get('locality')?.value;
+      if (savedLocality && !opts.includes(savedLocality)) {
+        this.localityOptions[tab] = [
+          savedLocality,
+          ...opts
+        ];
+      }
+
+      // Fineract's address payload returns `stateProvinceId` (numeric) rather
+      // than `stateName`, so the State field arrives empty after load.
+      // Fill state / city / district from the PIN lookup ONLY when they're
+      // currently empty — preserves anything the user has actually saved.
+      const first = (offices || [])[0];
+      if (first) {
+        const patch: Record<string, string> = {};
+        if (!form.get('state')?.value && first.State) patch['state'] = first.State;
+        if (!form.get('city')?.value && (first.Block || first.Division || first.District)) {
+          patch['city'] = first.Block || first.Division || first.District;
+        }
+        if (!form.get('district')?.value && first.District) patch['district'] = first.District;
+        if (Object.keys(patch).length > 0) {
+          form.patchValue(patch);
+        }
+      }
+    };
+
+    if (this.pinCache[pin]) {
+      applyOptions(this.pinCache[pin]);
+      return;
+    }
+
+    this.pinStatus[tab] = { loading: true, found: false, error: false, message: 'Looking up...' };
+    this.http.get<any[]>(`https://api.postalpincode.in/pincode/${pin}`).subscribe({
+      next: (data: any) => {
+        if (data?.[0]?.Status === 'Success') {
+          this.pinCache[pin] = data[0].PostOffice;
+          applyOptions(data[0].PostOffice);
+        } else {
+          // Couldn't confirm — keep the saved value visible but flag it.
+          this.pinStatus[tab] = { loading: false, found: false, error: false, message: '' };
+        }
+      },
+      error: () => {
+        this.pinStatus[tab] = { loading: false, found: false, error: false, message: '' };
+      }
+    });
+  }
+
   getForm(tab: string): UntypedFormGroup {
     switch (tab) {
       case 'permanent':

src/app/clients/client-stepper/client-kyc-step/client-kyc-step.component.html

@@ -28,9 +28,30 @@
     <div class="form-grid">
       <!-- ══ INDIVIDUAL KYC ══ -->
       @if (!isNonIndividual) {
-        <div class="form-field checkbox-field full-width">
-          <mat-checkbox formControlName="hasPan">Client has PAN Card</mat-checkbox>
-        </div>
+        @if (readOnly) {
+          <!-- In view mode the mat-checkbox renders as a faded grey square
+               that reads as "blurry". Show a clean Yes/No pill instead. -->
+          <div class="form-field checkbox-field full-width">
+            <div class="ro-flag">
+              <span class="ro-flag__label">Client has PAN Card</span>
+              @if (kycForm.get('hasPan')?.value) {
+                <span class="ro-flag__chip ro-flag__chip--yes">
+                  <mat-icon>check_circle</mat-icon>
+                  Yes
+                </span>
+              } @else {
+                <span class="ro-flag__chip ro-flag__chip--no">
+                  <mat-icon>cancel</mat-icon>
+                  No
+                </span>
+              }
+            </div>
+          </div>
+        } @else {
+          <div class="form-field checkbox-field full-width">
+            <mat-checkbox formControlName="hasPan">Client has PAN Card</mat-checkbox>
+          </div>
+        }
 
         <!-- Individual PAN with inline verify -->
         @if (kycForm.get('hasPan')?.value) {
@@ -83,40 +104,6 @@
               }
             </div>
           </div>
-          @if (panVerifyStatus === 'VERIFIED') {
-            <div class="pan-result-card full-width">
-              <div class="pan-result-header">
-                <fa-icon icon="check-circle" class="pan-result-ok-icon"></fa-icon>
-                <span>PAN Verified Successfully</span>
-              </div>
-              <div class="pan-result-body">
-                <div class="pan-result-row">
-                  <span class="pan-result-label">Full Name (as per PAN)</span>
-                  <span class="pan-result-value name">{{ panVerifyName }}</span>
-                </div>
-                <div class="pan-result-row">
-                  <span class="pan-result-label">PAN–Aadhaar Link Status</span>
-                  <span
-                    class="pan-result-value"
-                    [class.seeded]="panAadhaarSeedingStatus?.toUpperCase() === 'Y'"
-                    [class.not-seeded]="panAadhaarSeedingStatus?.toUpperCase() === 'N'"
-                  >
-                    @if (panAadhaarSeedingStatus?.toUpperCase() === 'Y') {
-                      Linked
-                    } @else if (panAadhaarSeedingStatus?.toUpperCase() === 'N') {
-                      Not Linked
-                    } @else {
-                      —
-                    }
-                  </span>
-                </div>
-                <div class="pan-result-row">
-                  <span class="pan-result-label">Verified On</span>
-                  <span class="pan-result-value date">{{ panVerifiedOn }}</span>
-                </div>
-              </div>
-            </div>
-          }
         }
 
         <!-- Aadhaar with independent verify (Individual only) -->
@@ -251,45 +238,140 @@
             <fa-icon icon="exclamation-circle"></fa-icon> {{ aadhaarVerifyError }}
           </div>
         }
-        @if (aadhaarVerifyStatus === 'VERIFIED' && aadhaarVerifyName) {
-          <div class="aadhaar-result-card full-width">
-            <div class="aadhaar-result-card__header">
-              <fa-icon icon="check-circle" class="aadhaar-result-card__icon"></fa-icon>
-              <span>Aadhaar Verified Successfully</span>
-            </div>
-            <div class="aadhaar-result-card__body">
-              <span class="aadhaar-result-card__label">Name as per Aadhaar</span>
-              <span class="aadhaar-result-card__name">{{ aadhaarVerifyName }}</span>
-            </div>
-          </div>
-        }
-
-        <!-- PAN-Aadhaar Seeding Status -->
-        @if (kycForm.get('hasPan')?.value && panAadhaarSeedingStatus) {
-          <div class="form-field pan-link-status full-width">
-            <div
-              class="pan-link-box"
-              [class.linked]="panAadhaarSeedingStatus === 'Y'"
-              [class.not-linked]="panAadhaarSeedingStatus === 'N'"
-              [class.exempt]="panAadhaarSeedingStatus === 'E'"
-            >
-              <fa-icon icon="link" class="pan-link-icon"></fa-icon>
-              <div class="pan-link-info">
-                <span class="pan-link-label">PAN–Aadhaar Link Status</span>
-                <span class="pan-link-value">
-                  @if (panAadhaarSeedingStatus === 'Y') {
-                    Linked (Seeded)
+        <!-- ─── Unified Identity Verification Summary ─── -->
+        <!-- One polished card that consolidates PAN result, Aadhaar result, and -->
+        <!-- the PAN–Aadhaar link status into a single, scannable panel.         -->
+        @if (panVerifyStatus === 'VERIFIED' || aadhaarVerifyStatus === 'VERIFIED') {
+          <div
+            class="idv-summary full-width"
+            [class.both]="panVerifyStatus === 'VERIFIED' && aadhaarVerifyStatus === 'VERIFIED'"
+            [class.partial]="
+              !(panVerifyStatus === 'VERIFIED' && aadhaarVerifyStatus === 'VERIFIED') &&
+              (panVerifyStatus === 'VERIFIED' || aadhaarVerifyStatus === 'VERIFIED')
+            "
+          >
+            <!-- Hero strip -->
+            <div class="idv-hero">
+              <div class="idv-hero__ic"><fa-icon icon="shield-alt"></fa-icon></div>
+              <div class="idv-hero__txt">
+                <div class="idv-hero__title">
+                  @if (panVerifyStatus === 'VERIFIED' && aadhaarVerifyStatus === 'VERIFIED') {
+                    Identity Verified
+                  } @else if (panVerifyStatus === 'VERIFIED') {
+                    PAN Verified
+                  } @else {
+                    Aadhaar Verified
                   }
-                  @if (panAadhaarSeedingStatus === 'N') {
-                    Not Linked
+                </div>
+                <div class="idv-hero__sub">
+                  @if (panVerifyStatus === 'VERIFIED' && aadhaarVerifyStatus === 'VERIFIED') {
+                    Both PAN &amp; Aadhaar confirmed against NSDL &amp; UIDAI records.
+                  } @else if (panVerifyStatus === 'VERIFIED') {
+                    PAN confirmed against NSDL records. Aadhaar verification pending.
+                  } @else {
+                    Aadhaar confirmed via UIDAI OTP. PAN verification pending.
                   }
-                  @if (panAadhaarSeedingStatus === 'E') {
-                    Exempt
-                  }
+                </div>
+              </div>
+              <div class="idv-hero__count">
+                <span class="idv-hero__count-num">
+                  {{ (panVerifyStatus === 'VERIFIED' ? 1 : 0) + (aadhaarVerifyStatus === 'VERIFIED' ? 1 : 0) }}
                 </span>
+                <span class="idv-hero__count-of">/ 2</span>
               </div>
-              <span class="pan-link-hint">As per Income Tax Portal — Section 139AA</span>
             </div>
+
+            <!-- Two-column body: PAN | Aadhaar -->
+            <div class="idv-body">
+              <!-- PAN column -->
+              <div class="idv-col" [class.muted]="panVerifyStatus !== 'VERIFIED'">
+                <div class="idv-col__head">
+                  <fa-icon icon="id-card" class="idv-col__ic"></fa-icon>
+                  <span class="idv-col__label">PAN</span>
+                  @if (panVerifyStatus === 'VERIFIED') {
+                    <span class="idv-chip ok"> <fa-icon icon="check-circle"></fa-icon> Verified </span>
+                  } @else {
+                    <span class="idv-chip pending">Pending</span>
+                  }
+                </div>
+                @if (panVerifyStatus === 'VERIFIED') {
+                  <div class="idv-col__rows">
+                    <div class="idv-row">
+                      <span class="idv-row__k">Name on PAN</span>
+                      <span class="idv-row__v name">{{ panVerifyName }}</span>
+                    </div>
+                    <div class="idv-row">
+                      <span class="idv-row__k">PAN Number</span>
+                      <span class="idv-row__v mono">{{ kycForm.get('panNumber')?.value }}</span>
+                    </div>
+                    <div class="idv-row">
+                      <span class="idv-row__k">Verified On</span>
+                      <span class="idv-row__v">{{ panVerifiedOn }}</span>
+                    </div>
+                  </div>
+                } @else {
+                  <div class="idv-col__empty">Enter PAN above and click <strong>Verify PAN</strong>.</div>
+                }
+              </div>
+
+              <!-- Aadhaar column -->
+              <div class="idv-col" [class.muted]="aadhaarVerifyStatus !== 'VERIFIED'">
+                <div class="idv-col__head">
+                  <fa-icon icon="fingerprint" class="idv-col__ic"></fa-icon>
+                  <span class="idv-col__label">Aadhaar</span>
+                  @if (aadhaarVerifyStatus === 'VERIFIED') {
+                    <span class="idv-chip ok"> <fa-icon icon="check-circle"></fa-icon> Verified </span>
+                  } @else {
+                    <span class="idv-chip pending">Pending</span>
+                  }
+                </div>
+                @if (aadhaarVerifyStatus === 'VERIFIED') {
+                  <div class="idv-col__rows">
+                    <div class="idv-row">
+                      <span class="idv-row__k">Name on Aadhaar</span>
+                      <span class="idv-row__v name">{{ aadhaarVerifyName }}</span>
+                    </div>
+                    <div class="idv-row">
+                      <span class="idv-row__k">Aadhaar Number</span>
+                      <span class="idv-row__v mono"
+                        >XXXX XXXX {{ (kycForm.get('aadhaarNumber')?.value || '').slice(-4) }}</span
+                      >
+                    </div>
+                    <div class="idv-row">
+                      <span class="idv-row__k">Channel</span>
+                      <span class="idv-row__v">UIDAI OTP</span>
+                    </div>
+                  </div>
+                } @else {
+                  <div class="idv-col__empty">Enter Aadhaar above and click <strong>Verify Aadhaar</strong>.</div>
+                }
+              </div>
+            </div>
+
+            <!-- PAN ↔ Aadhaar link footer -->
+            @if (panAadhaarSeedingStatus) {
+              <div
+                class="idv-link"
+                [class.linked]="panAadhaarSeedingStatus === 'Y'"
+                [class.not-linked]="panAadhaarSeedingStatus === 'N'"
+                [class.exempt]="panAadhaarSeedingStatus === 'E'"
+              >
+                <fa-icon icon="link" class="idv-link__ic"></fa-icon>
+                <div class="idv-link__txt">
+                  <span class="idv-link__label">PAN &mdash; Aadhaar Link</span>
+                  <span class="idv-link__value">
+                    @if (panAadhaarSeedingStatus === 'Y') {
+                      Linked (Seeded)
+                    } @else if (panAadhaarSeedingStatus === 'N') {
+                      Not Linked
+                    } @else if (panAadhaarSeedingStatus === 'E') {
+                      Exempt
+                    }
+                  </span>
+                </div>
+                <span class="idv-link__hint">Income Tax Portal &mdash; Section 139AA</span>
+              </div>
+            }
           </div>
         }
       }
@@ -652,7 +734,7 @@
 
       <div class="kyc-doc-field">
         <label class="kyc-doc-label"><mat-icon>description</mat-icon> Document type</label>
-        <div class="kyc-doc-chip-wrap">
+        <div class="kyc-doc-chip-wrap" [class.kyc-doc-chip-wrap--locked]="readOnly">
           @for (group of kycDocGroups; track group.label; let last = $last) {
             <div class="kyc-doc-chip-group-label"><mat-icon>folder_open</mat-icon> {{ group.label }}</div>
             <div class="kyc-doc-chip-grid">
@@ -660,9 +742,11 @@
                 <span
                   class="kyc-doc-chip"
                   [class.kyc-doc-chip--sel]="isKycDocSelected(p)"
-                  (click)="selectKycDoc(p)"
-                  (keydown.enter)="selectKycDoc(p)"
-                  tabindex="0"
+                  [class.kyc-doc-chip--locked]="readOnly && !isKycDocSelected(p)"
+                  [attr.aria-disabled]="readOnly ? 'true' : null"
+                  (click)="readOnly ? null : selectKycDoc(p)"
+                  (keydown.enter)="readOnly ? null : selectKycDoc(p)"
+                  [attr.tabindex]="readOnly ? -1 : 0"
                   role="button"
                 >
                   <mat-icon class="kyc-doc-chip__icon">
@@ -699,59 +783,78 @@
               </span>
               <span class="kyc-doc-upload-req">Required</span>
             </div>
-            <label
-              class="kyc-doc-dropzone"
-              [class.kyc-doc-dropzone--has]="kycDocFiles.front"
-              [class.kyc-doc-dropzone--req]="!kycDocFiles.front"
-            >
-              <input type="file" accept=".jpg,.jpeg,.png,.pdf" hidden (change)="onKycDocFile($event, 'front')" />
-              @if (kycDocFiles.front) {
-                <div class="kyc-doc-dropzone__file">
-                  <mat-icon>insert_drive_file</mat-icon>
-                  <span class="kyc-doc-dropzone__name">{{ kycDocFiles.front.name }}</span>
-                  <button
-                    type="button"
-                    mat-icon-button
-                    class="kyc-doc-dropzone__remove"
-                    (click)="$event.preventDefault(); removeKycDocFile('front')"
-                  >
-                    <mat-icon>close</mat-icon>
-                  </button>
+            <!-- Existing saved ID-proof doc — locked by default. Replace flow
+                 unlocks automatically when the section-level Edit button toggles
+                 `readOnly` off. -->
+            @if (existingKycDocuments.length > 0 && !kycDocFiles.front && readOnly) {
+              <div class="kyc-doc-dropzone kyc-doc-dropzone--has kyc-doc-dropzone--locked">
+                <div class="kyc-doc-dropzone__existing">
+                  @if (kycDocMergedPreview) {
+                    <img [src]="kycDocMergedPreview" alt="Saved KYC document" class="kyc-doc-dropzone__thumb" />
+                  } @else {
+                    <mat-icon class="kyc-doc-dropzone__doc-ic">description</mat-icon>
+                  }
+                  <div class="kyc-doc-dropzone__existing-meta">
+                    <span class="kyc-doc-dropzone__existing-name">
+                      {{ existingKycDocuments[0].fileName || existingKycDocuments[0].name }}
+                    </span>
+                    <button type="button" class="kyc-doc-dropzone__view" (click)="viewExistingKycDoc()">
+                      <mat-icon>visibility</mat-icon>
+                      Click here to view
+                    </button>
+                  </div>
                 </div>
-              } @else {
-                <div class="kyc-doc-dropzone__hint">
-                  <mat-icon>cloud_upload</mat-icon>
-                  <span>Click to upload (JPG / PNG / PDF · max 5 MB)</span>
-                </div>
-              }
-            </label>
-          </div>
-
-          @if (selectedKycDoc.sides === 2) {
-            <div class="kyc-doc-upload-slot">
-              <div class="kyc-doc-upload-head">
-                <span class="kyc-doc-upload-title"> <mat-icon>image</mat-icon> Back side </span>
-                <span class="kyc-doc-upload-req">Required</span>
               </div>
+            } @else {
               <label
                 class="kyc-doc-dropzone"
-                [class.kyc-doc-dropzone--has]="kycDocFiles.back"
-                [class.kyc-doc-dropzone--req]="!kycDocFiles.back"
+                [class.kyc-doc-dropzone--has]="kycDocFiles.front || existingKycDocuments.length > 0"
+                [class.kyc-doc-dropzone--req]="!kycDocFiles.front && existingKycDocuments.length === 0"
               >
-                <input type="file" accept=".jpg,.jpeg,.png,.pdf" hidden (change)="onKycDocFile($event, 'back')" />
-                @if (kycDocFiles.back) {
+                <input type="file" accept=".jpg,.jpeg,.png,.pdf" hidden (change)="onKycDocFile($event, 'front')" />
+                @if (kycDocFiles.front) {
                   <div class="kyc-doc-dropzone__file">
                     <mat-icon>insert_drive_file</mat-icon>
-                    <span class="kyc-doc-dropzone__name">{{ kycDocFiles.back.name }}</span>
+                    <span class="kyc-doc-dropzone__name">{{ kycDocFiles.front.name }}</span>
                     <button
                       type="button"
                       mat-icon-button
                       class="kyc-doc-dropzone__remove"
-                      (click)="$event.preventDefault(); removeKycDocFile('back')"
+                      (click)="$event.preventDefault(); removeKycDocFile('front')"
                     >
                       <mat-icon>close</mat-icon>
                     </button>
                   </div>
+                } @else if (existingKycDocuments.length > 0) {
+                  <!-- Edit mode WITH existing doc — let the user view it OR
+                       click anywhere to replace. -->
+                  <div class="kyc-doc-dropzone__existing">
+                    @if (kycDocMergedPreview) {
+                      <img [src]="kycDocMergedPreview" alt="Saved KYC document" class="kyc-doc-dropzone__thumb" />
+                    } @else {
+                      <mat-icon class="kyc-doc-dropzone__doc-ic">description</mat-icon>
+                    }
+                    <div class="kyc-doc-dropzone__existing-meta">
+                      <span class="kyc-doc-dropzone__existing-name">
+                        {{ existingKycDocuments[0].fileName || existingKycDocuments[0].name }}
+                      </span>
+                      <div class="kyc-doc-dropzone__existing-actions">
+                        <button
+                          type="button"
+                          class="kyc-doc-dropzone__view"
+                          (click)="$event.preventDefault(); $event.stopPropagation(); viewExistingKycDoc()"
+                        >
+                          <mat-icon>visibility</mat-icon>
+                          View
+                        </button>
+                        <span class="kyc-doc-dropzone__sep">·</span>
+                        <span class="kyc-doc-dropzone__existing-hint">
+                          <mat-icon>cloud_upload</mat-icon>
+                          Click here to replace
+                        </span>
+                      </div>
+                    </div>
+                  </div>
                 } @else {
                   <div class="kyc-doc-dropzone__hint">
                     <mat-icon>cloud_upload</mat-icon>
@@ -759,11 +862,104 @@
                   </div>
                 }
               </label>
+            }
+          </div>
+
+          @if (selectedKycDoc.sides === 2) {
+            <div class="kyc-doc-upload-slot">
+              <div class="kyc-doc-upload-head">
+                <span class="kyc-doc-upload-title"> <mat-icon>image</mat-icon> Back side </span>
+                <!-- Hide Required pill when saved combined doc covers both sides -->
+                @if (!(existingKycDocuments.length > 0 && !kycDocFiles.back)) {
+                  <span class="kyc-doc-upload-req">Required</span>
+                }
+              </div>
+              <!-- Locked view: saved combined doc covers the back side too. -->
+              @if (existingKycDocuments.length > 0 && !kycDocFiles.back && readOnly) {
+                <div class="kyc-doc-dropzone kyc-doc-dropzone--has kyc-doc-dropzone--locked">
+                  <div class="kyc-doc-dropzone__existing">
+                    @if (kycDocMergedPreview) {
+                      <img [src]="kycDocMergedPreview" alt="Saved KYC document" class="kyc-doc-dropzone__thumb" />
+                    } @else {
+                      <mat-icon class="kyc-doc-dropzone__doc-ic">description</mat-icon>
+                    }
+                    <div class="kyc-doc-dropzone__existing-meta">
+                      <span class="kyc-doc-dropzone__existing-name">
+                        {{ existingKycDocuments[0].fileName || existingKycDocuments[0].name }}
+                      </span>
+                      <button type="button" class="kyc-doc-dropzone__view" (click)="viewExistingKycDoc()">
+                        <mat-icon>visibility</mat-icon>
+                        Click here to view
+                      </button>
+                    </div>
+                  </div>
+                </div>
+              } @else {
+                <label
+                  class="kyc-doc-dropzone"
+                  [class.kyc-doc-dropzone--has]="kycDocFiles.back || existingKycDocuments.length > 0"
+                  [class.kyc-doc-dropzone--req]="!kycDocFiles.back && existingKycDocuments.length === 0"
+                >
+                  <input type="file" accept=".jpg,.jpeg,.png,.pdf" hidden (change)="onKycDocFile($event, 'back')" />
+                  @if (kycDocFiles.back) {
+                    <div class="kyc-doc-dropzone__file">
+                      <mat-icon>insert_drive_file</mat-icon>
+                      <span class="kyc-doc-dropzone__name">{{ kycDocFiles.back.name }}</span>
+                      <button
+                        type="button"
+                        mat-icon-button
+                        class="kyc-doc-dropzone__remove"
+                        (click)="$event.preventDefault(); removeKycDocFile('back')"
+                      >
+                        <mat-icon>close</mat-icon>
+                      </button>
+                    </div>
+                  } @else if (existingKycDocuments.length > 0) {
+                    <!-- Edit mode WITH existing combined doc — view + replace. -->
+                    <div class="kyc-doc-dropzone__existing">
+                      @if (kycDocMergedPreview) {
+                        <img [src]="kycDocMergedPreview" alt="Saved KYC document" class="kyc-doc-dropzone__thumb" />
+                      } @else {
+                        <mat-icon class="kyc-doc-dropzone__doc-ic">description</mat-icon>
+                      }
+                      <div class="kyc-doc-dropzone__existing-meta">
+                        <span class="kyc-doc-dropzone__existing-name">
+                          {{ existingKycDocuments[0].fileName || existingKycDocuments[0].name }}
+                        </span>
+                        <div class="kyc-doc-dropzone__existing-actions">
+                          <button
+                            type="button"
+                            class="kyc-doc-dropzone__view"
+                            (click)="$event.preventDefault(); $event.stopPropagation(); viewExistingKycDoc()"
+                          >
+                            <mat-icon>visibility</mat-icon>
+                            View
+                          </button>
+                          <span class="kyc-doc-dropzone__sep">·</span>
+                          <span class="kyc-doc-dropzone__existing-hint">
+                            <mat-icon>cloud_upload</mat-icon>
+                            Click here to replace
+                          </span>
+                        </div>
+                      </div>
+                    </div>
+                  } @else {
+                    <div class="kyc-doc-dropzone__hint">
+                      <mat-icon>cloud_upload</mat-icon>
+                      <span>Click to upload (JPG / PNG / PDF · max 5 MB)</span>
+                    </div>
+                  }
+                </label>
+              }
             </div>
           }
         </div>
 
-        @if (selectedKycDoc.sides === 2 && kycDocMergedPreview) {
+        <!-- Combined preview + re-crop is an edit-mode tool — hide in read-only,
+             and don't duplicate the thumbnail when nothing's been picked yet. -->
+        @if (
+          selectedKycDoc.sides === 2 && kycDocMergedPreview && !readOnly && (kycDocFiles.front || kycDocFiles.back)
+        ) {
           <div class="kyc-merged">
             <div class="kyc-merged__head">
               <span class="kyc-merged__title">

src/app/clients/client-stepper/client-kyc-step/client-kyc-step.component.scss

@@ -869,6 +869,49 @@
   padding-top: 10px;
 }
 
+/* Read-only Yes/No flag — replaces the disabled mat-checkbox in view mode
+   so we don't fight Material's greyed-out disabled checkbox styling. */
+.ro-flag {
+  display: inline-flex;
+  align-items: center;
+  gap: 12px;
+
+  &__label {
+    font-size: 13.5px;
+    font-weight: 600;
+    color: #0f172a;
+  }
+
+  &__chip {
+    display: inline-flex;
+    align-items: center;
+    gap: 6px;
+    padding: 4px 12px;
+    border-radius: 999px;
+    font-size: 12px;
+    font-weight: 700;
+    letter-spacing: 0.02em;
+
+    mat-icon {
+      font-size: 15px;
+      width: 15px;
+      height: 15px;
+    }
+
+    &--yes {
+      background: #ecfdf5;
+      color: #047857;
+      border: 1px solid #a7f3d0;
+    }
+
+    &--no {
+      background: #fef2f2;
+      color: #b91c1c;
+      border: 1px solid #fecaca;
+    }
+  }
+}
+
 /* Link select inside status box */
 .link-select {
   font-size: 12px;
@@ -1402,12 +1445,36 @@
     }
   }
 
+  /* Non-selected chip in read-only mode — visible but visibly unclickable.
+     The selected chip stays fully highlighted (no `--locked` class on it). */
+  &--locked {
+    cursor: default;
+    background: #f8fafc;
+    border-color: #e2e8f0;
+    color: #94a3b8;
+
+    .kyc-doc-chip__icon {
+      color: #cbd5e1;
+    }
+
+    &:hover {
+      border-color: #e2e8f0;
+      color: #94a3b8;
+    }
+  }
+
   &:focus-visible {
     outline: 2px solid #1976d2;
     outline-offset: 2px;
   }
 }
 
+/* When the whole wrap is locked, prevent the selected chip's cursor from
+   suggesting interactivity either. */
+.kyc-doc-chip-wrap--locked .kyc-doc-chip--sel {
+  cursor: default;
+}
+
 .kyc-doc-banner {
   display: flex;
   align-items: center;
@@ -1640,4 +1707,524 @@
   &__remove {
     flex-shrink: 0;
   }
+
+  /* Locked variant — used when an existing saved doc is shown but the
+     section's top-level Edit hasn't been clicked yet. */
+  &--locked {
+    cursor: default;
+
+    &:hover {
+      background: #f0fdf4;
+      border-color: #86efac;
+    }
+  }
+
+  /* Existing saved document — thumbnail + filename + actions. */
+  &__existing {
+    display: flex;
+    align-items: center;
+    gap: 14px;
+    min-width: 0;
+  }
+
+  &__thumb {
+    width: 56px;
+    height: 56px;
+    object-fit: cover;
+    border-radius: 8px;
+    background: #e2e8f0;
+    border: 1px solid #cbd5e1;
+    flex-shrink: 0;
+  }
+
+  &__doc-ic {
+    width: 40px;
+    height: 40px;
+    font-size: 32px;
+    color: #1e88e5;
+    flex-shrink: 0;
+  }
+
+  &__existing-meta {
+    display: flex;
+    flex-direction: column;
+    gap: 6px;
+    min-width: 0;
+    flex: 1;
+  }
+
+  &__existing-name {
+    font-size: 13px;
+    font-weight: 700;
+    color: #0f172a;
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
+  }
+
+  &__existing-actions {
+    display: inline-flex;
+    align-items: center;
+    gap: 6px;
+    flex-wrap: wrap;
+  }
+
+  &__view {
+    display: inline-flex;
+    align-items: center;
+    gap: 5px;
+    padding: 4px 10px;
+    border-radius: 6px;
+    font-size: 11.5px;
+    font-weight: 700;
+    cursor: pointer;
+    background: #eff6ff;
+    color: #1e40af;
+    border: 1px solid #bfdbfe;
+    transition: all 0.12s;
+
+    mat-icon {
+      font-size: 14px;
+      width: 14px;
+      height: 14px;
+    }
+
+    &:hover {
+      background: #dbeafe;
+      border-color: #1e40af;
+    }
+  }
+
+  &__sep {
+    color: #cbd5e1;
+    font-weight: 700;
+  }
+
+  &__existing-hint {
+    display: inline-flex;
+    align-items: center;
+    gap: 6px;
+    font-size: 11.5px;
+    color: #1e40af;
+    font-weight: 600;
+
+    mat-icon {
+      font-size: 14px;
+      width: 14px;
+      height: 14px;
+    }
+  }
+}
+
+/* ═══════════════════════════════════════════════════════════════
+   Read-only / disabled form-field overrides
+   ─── When the form is .disable()'d (view mode after KYC is locked),
+        Material drops opacity and greys everything. That reads as
+        "blurry" to users. Restore proper contrast: dark text, crisp
+        outline, normal-weight label — just NOT editable.
+   ═══════════════════════════════════════════════════════════════ */
+:host ::ng-deep {
+  /* Outlined form fields in disabled state */
+  .mat-mdc-form-field.mat-form-field-appearance-outline.mat-form-field-disabled {
+    opacity: 1;
+
+    /* Input text */
+    .mat-mdc-input-element,
+    input.mat-mdc-input-element {
+      color: #0f172a !important;
+      -webkit-text-fill-color: #0f172a !important; /* Chrome/Safari override */
+      font-weight: 600;
+      caret-color: transparent;
+    }
+
+    /* Floating label */
+    .mat-mdc-floating-label,
+    .mdc-floating-label {
+      color: #64748b !important;
+      opacity: 1 !important;
+    }
+
+    /* The outline lines */
+    .mdc-notched-outline__leading,
+    .mdc-notched-outline__notch,
+    .mdc-notched-outline__trailing {
+      border-color: #cbd5e1 !important;
+      border-width: 1px !important;
+    }
+
+    /* matPrefix icons (the credit-card / fingerprint glyphs) */
+    .field-prefix-icon mat-icon,
+    .mat-mdc-form-field-icon-prefix mat-icon {
+      color: #475569 !important;
+      opacity: 1;
+    }
+
+    /* matSuffix verify-ok icon — keep its green */
+    .verify-icon-ok {
+      color: #059669 !important;
+      opacity: 1;
+    }
+
+    /* Hint text */
+    .mat-mdc-form-field-hint {
+      color: #64748b !important;
+      opacity: 1;
+    }
+  }
+
+  /* Disabled checkbox — keep the check + label crisp */
+  .mat-mdc-checkbox-disabled {
+    opacity: 1 !important;
+
+    .mdc-checkbox__background {
+      background-color: #059669 !important;
+      border-color: #059669 !important;
+    }
+
+    .mdc-checkbox__checkmark {
+      color: #fff !important;
+    }
+
+    .mdc-form-field > label,
+    .mat-mdc-checkbox-label,
+    .mdc-label {
+      color: #0f172a !important;
+      opacity: 1 !important;
+      font-weight: 500;
+    }
+  }
+
+  /* Disabled mat-select — same treatment as inputs */
+  .mat-mdc-form-field-disabled .mat-mdc-select-value-text,
+  .mat-mdc-form-field-disabled .mat-mdc-select-value {
+    color: #0f172a !important;
+    -webkit-text-fill-color: #0f172a !important;
+    font-weight: 600;
+  }
+
+  /* Disabled "toggle visibility" eye icon button */
+  .mat-mdc-form-field-disabled .toggle-vis-btn {
+    color: #64748b !important;
+    opacity: 1;
+  }
+}
+
+/* ═══════════════════════════════════════════════════════════════
+   Unified Identity Verification Summary (PAN + Aadhaar + Link)
+   ─── replaces the legacy pan-result-card / aadhaar-result-card /
+        pan-link-box trio with a single polished panel.
+   ═══════════════════════════════════════════════════════════════ */
+.idv-summary {
+  margin: 4px 0 12px;
+  border-radius: 14px;
+  background: #fff;
+  border: 1px solid #d1fae5;
+  box-shadow: 0 1px 3px rgb(15 23 42 / 4%);
+  overflow: hidden;
+
+  &.partial {
+    border-color: #fde68a;
+  }
+}
+
+/* Hero strip — gradient green when both verified, amber when partial. */
+.idv-hero {
+  display: flex;
+  align-items: center;
+  gap: 14px;
+  padding: 14px 18px;
+  color: #fff;
+  background: linear-gradient(135deg, #047857 0%, #059669 60%, #10b981 100%);
+
+  .idv-summary.partial & {
+    background: linear-gradient(135deg, #b45309 0%, #d97706 60%, #f59e0b 100%);
+  }
+
+  &__ic {
+    width: 38px;
+    height: 38px;
+    flex-shrink: 0;
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    border-radius: 10px;
+    background: rgb(255 255 255 / 18%);
+    color: #fff;
+    font-size: 16px;
+    backdrop-filter: blur(4px);
+  }
+
+  &__txt {
+    flex: 1;
+    min-width: 0;
+  }
+
+  &__title {
+    font-size: 15px;
+    font-weight: 800;
+    letter-spacing: 0.01em;
+    line-height: 1.1;
+  }
+
+  &__sub {
+    margin-top: 3px;
+    font-size: 11.5px;
+    opacity: 0.92;
+    line-height: 1.3;
+  }
+
+  &__count {
+    flex-shrink: 0;
+    padding: 6px 12px;
+    border-radius: 999px;
+    background: rgb(255 255 255 / 22%);
+    color: #fff;
+    font-weight: 800;
+    display: inline-flex;
+    align-items: baseline;
+    gap: 2px;
+    border: 1px solid rgb(255 255 255 / 30%);
+
+    &-num {
+      font-size: 16px;
+    }
+
+    &-of {
+      font-size: 11px;
+      opacity: 0.85;
+    }
+  }
+}
+
+/* Two-column body */
+.idv-body {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: 0;
+  background: #ecfdf5;
+
+  .idv-summary.partial & {
+    background: #fef3c7;
+  }
+}
+
+.idv-col {
+  padding: 14px 18px;
+  border-right: 1px dashed rgb(5 150 105 / 25%);
+
+  &:last-child {
+    border-right: none;
+  }
+
+  &.muted {
+    background: rgb(255 255 255 / 50%);
+    opacity: 0.85;
+  }
+
+  &__head {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+    margin-bottom: 10px;
+  }
+
+  &__ic {
+    width: 26px;
+    height: 26px;
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    border-radius: 7px;
+    background: #fff;
+    color: #047857;
+    font-size: 12px;
+    flex-shrink: 0;
+    box-shadow: 0 1px 2px rgb(15 23 42 / 8%);
+  }
+
+  &__label {
+    font-size: 10.5px;
+    text-transform: uppercase;
+    letter-spacing: 0.08em;
+    font-weight: 800;
+    color: #065f46;
+  }
+
+  &__rows {
+    display: flex;
+    flex-direction: column;
+    gap: 7px;
+  }
+
+  &__empty {
+    font-size: 11.5px;
+    color: #64748b;
+    background: rgb(255 255 255 / 70%);
+    padding: 10px 12px;
+    border-radius: 8px;
+    border: 1px dashed #cbd5e1;
+
+    strong {
+      color: #334155;
+    }
+  }
+}
+
+.idv-chip {
+  margin-left: auto;
+  display: inline-flex;
+  align-items: center;
+  gap: 5px;
+  padding: 2px 9px;
+  border-radius: 999px;
+  font-size: 10px;
+  font-weight: 800;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+
+  fa-icon {
+    font-size: 9px;
+  }
+
+  &.ok {
+    background: #059669;
+    color: #fff;
+  }
+
+  &.pending {
+    background: #fef3c7;
+    color: #92400e;
+  }
+}
+
+.idv-row {
+  display: flex;
+  align-items: baseline;
+  gap: 8px;
+
+  &__k {
+    flex-shrink: 0;
+    width: 110px;
+    font-size: 10.5px;
+    color: #64748b;
+    font-weight: 600;
+    text-transform: uppercase;
+    letter-spacing: 0.04em;
+  }
+
+  &__v {
+    font-size: 13px;
+    font-weight: 600;
+    color: #0f172a;
+    word-break: break-word;
+
+    &.name {
+      font-size: 14px;
+      font-weight: 800;
+      color: #065f46;
+    }
+
+    &.mono {
+      font-family: ui-monospace, 'Roboto Mono', SFMono-Regular, monospace;
+      font-size: 12px;
+      color: #1f2937;
+    }
+  }
+}
+
+/* Footer — PAN ↔ Aadhaar link status */
+.idv-link {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  padding: 10px 18px;
+  background: #f0fdf4;
+  border-top: 1px solid #bbf7d0;
+
+  &__ic {
+    color: #047857;
+    font-size: 14px;
+    flex-shrink: 0;
+  }
+
+  &__txt {
+    display: flex;
+    align-items: baseline;
+    gap: 8px;
+    flex: 1;
+  }
+
+  &__label {
+    font-size: 10.5px;
+    text-transform: uppercase;
+    letter-spacing: 0.06em;
+    color: #475569;
+    font-weight: 700;
+  }
+
+  &__value {
+    font-size: 13px;
+    font-weight: 800;
+    color: #047857;
+  }
+
+  &__hint {
+    font-size: 11px;
+    color: #64748b;
+    font-style: italic;
+    flex-shrink: 0;
+  }
+
+  &.not-linked {
+    background: #fef2f2;
+    border-top-color: #fecaca;
+
+    .idv-link__ic,
+    .idv-link__value {
+      color: #dc2626;
+    }
+  }
+
+  &.exempt {
+    background: #eff6ff;
+    border-top-color: #bfdbfe;
+
+    .idv-link__ic,
+    .idv-link__value {
+      color: #1d4ed8;
+    }
+  }
+}
+
+/* Responsive — stack columns on narrow screens */
+@media (width <= 640px) {
+  .idv-body {
+    grid-template-columns: 1fr;
+  }
+
+  .idv-col {
+    border-right: none;
+    border-bottom: 1px dashed rgb(5 150 105 / 25%);
+
+    &:last-child {
+      border-bottom: none;
+    }
+  }
+
+  .idv-hero {
+    flex-wrap: wrap;
+  }
+
+  .idv-link {
+    flex-wrap: wrap;
+
+    &__hint {
+      width: 100%;
+      padding-left: 26px;
+    }
+  }
+
+  .idv-row__k {
+    width: 95px;
+  }
 }

src/app/clients/client-stepper/client-kyc-step/client-kyc-step.component.ts

@@ -90,6 +90,23 @@ export class ClientKycStepComponent implements OnInit, OnChanges, OnDestroy {
   kycDocMergedFile: File | null = null;
   kycDocMergedPreview: string | null = null;
 
+  /**
+   * Documents already on the server for the linked client_identifier row (edit mode).
+   * Populated in loadExistingKycIdentifier() so the form can show the user what proof
+   * they uploaded previously instead of presenting an empty file picker.
+   *
+   * Each entry: { id, name, fileName, type, size, previewUrl (base64 data URL for images) }
+   */
+  existingKycIdentifierId: string | null = null;
+  existingKycDocuments: {
+    id: string;
+    name: string;
+    fileName: string;
+    type: string;
+    size: number;
+    previewUrl: string | null;
+  }[] = [];
+
   /** Set true after a save attempt so we can highlight missing photo/signature boxes */
   photoSigTouched = false;
 
@@ -522,6 +539,36 @@ export class ClientKycStepComponent implements OnInit, OnChanges, OnDestroy {
     this.kycDocMergedPreview = null;
   }
 
+  /**
+   * Open the saved KYC ID-proof document in a new browser tab.
+   *
+   * Same flow as the address-step variant: images use the already-loaded
+   * base64 data URL; PDFs (or anything without a cached preview) are fetched
+   * fresh and rendered via a temporary blob URL.
+   */
+  viewExistingKycDoc(): void {
+    if (!this.existingKycIdentifierId || this.existingKycDocuments.length === 0) {
+      return;
+    }
+    const doc = this.existingKycDocuments[0];
+    if (doc.previewUrl) {
+      window.open(doc.previewUrl, '_blank', 'noopener');
+      return;
+    }
+    this.clientsService.downloadClientIdentificationDocument(this.existingKycIdentifierId, doc.id).subscribe({
+      next: (blob: Blob) => {
+        const url = URL.createObjectURL(blob);
+        const w = window.open(url, '_blank', 'noopener');
+        if (w) {
+          setTimeout(() => URL.revokeObjectURL(url), 60_000);
+        }
+      },
+      error: () => {
+        /* silent — UI still shows the saved filename */
+      }
+    });
+  }
+
   private async refreshKycDocMerged(): Promise<void> {
     const proof = this.selectedKycDoc;
     if (!proof || proof.sides !== 2 || !this.kycDocFiles.front || !this.kycDocFiles.back) {
@@ -662,6 +709,9 @@ export class ClientKycStepComponent implements OnInit, OnChanges, OnDestroy {
         // Load existing photo & signature
         this.loadExistingPhoto();
         this.loadExistingSignature();
+        // Show the proof file the user uploaded previously, by matching the KYC document
+        // name against the client_identifier rows on the server.
+        this.loadExistingKycIdentifier(data?.kycDocumentName);
       },
       error: () => {
         // No existing KYC — that's fine for new clients
@@ -670,6 +720,86 @@ export class ClientKycStepComponent implements OnInit, OnChanges, OnDestroy {
     });
   }
 
+  /**
+   * Pull the client_identifier row that backs the KYC proof and any documents attached to
+   * it. Address proof + KYC proof both end up as client_identifier rows (see
+   * create-client.saveKycDocProof + saveAddressProof) — so we filter against `kycDocProofs`
+   * before falling back, otherwise the KYC tab could mistakenly show the address proof's file.
+   *
+   * @param kycDocumentName the document type captured on the KYC record — used to pick
+   *                        the right identifier when a client has more than one
+   */
+  private loadExistingKycIdentifier(kycDocumentName: string | undefined): void {
+    if (!this.clientId) return;
+    this.clientsService.getClientIdentifiers(this.clientId).subscribe({
+      next: (identifiers: any[]) => {
+        if (!identifiers || identifiers.length === 0) return;
+        const isKycType = (i: any) => {
+          const n = i?.documentType?.name?.toLowerCase();
+          return !!n && this.kycDocProofs.some((p) => p.name?.toLowerCase() === n);
+        };
+        // Pick by document-type name match first; otherwise the first identifier whose
+        // type lives in the KYC proof list (avoid bleeding the address proof in here).
+        const match = kycDocumentName
+          ? identifiers.find((i: any) => i?.documentType?.name?.toLowerCase() === kycDocumentName.toLowerCase())
+          : null;
+        const identifier = match || identifiers.find(isKycType);
+        if (!identifier?.id) return;
+
+        this.existingKycIdentifierId = identifier.id.toString();
+        // Backfill document type + number on the form in case the KYC record didn't have
+        // them (older clients were created via the identifier flow only).
+        if (!this.kycForm.get('kycDocumentName')?.value && identifier?.documentType?.name) {
+          this.kycForm.patchValue({
+            kycDocumentName: identifier.documentType.name,
+            kycDocumentNumber: identifier.documentKey || ''
+          });
+          this.selectedKycDoc = this.kycDocProofs.find((p) => p.name === identifier.documentType.name) || null;
+        }
+
+        this.clientsService.getClientIdentificationDocuments(this.existingKycIdentifierId).subscribe({
+          next: (docs: any[]) => {
+            if (!docs || docs.length === 0) return;
+            this.existingKycDocuments = docs.map((d: any) => ({
+              id: d.id?.toString() || '',
+              name: d.name || '',
+              fileName: d.fileName || '',
+              type: d.type || '',
+              size: d.size || 0,
+              previewUrl: null as string | null
+            }));
+            // Build a preview for the first image-typed document so the UI can show
+            // exactly what the user uploaded last time.
+            const firstImage = this.existingKycDocuments.find((d) => (d.type || '').toLowerCase().startsWith('image/'));
+            if (firstImage) {
+              this.clientsService
+                .downloadClientIdentificationDocument(this.existingKycIdentifierId!, firstImage.id)
+                .subscribe({
+                  next: async (blob: any) => {
+                    const buffer = await blob.arrayBuffer();
+                    const bytes = new Uint8Array(buffer);
+                    let binary = '';
+                    for (let i = 0; i < bytes.length; i++) {
+                      binary += String.fromCharCode(bytes[i]);
+                    }
+                    firstImage.previewUrl = 'data:' + blob.type + ';base64,' + btoa(binary);
+                    // Mirror onto the merged-preview slot so the existing chip-picker
+                    // visualisation lights up without template changes.
+                    if (!this.kycDocMergedPreview) {
+                      this.kycDocMergedPreview = firstImage.previewUrl;
+                    }
+                  },
+                  error: () => {}
+                });
+            }
+          },
+          error: () => {}
+        });
+      },
+      error: () => {}
+    });
+  }
+
   /** Fetch existing client profile photo */
   private loadExistingPhoto(): void {
     if (!this.clientId) return;
@@ -801,9 +931,18 @@ export class ClientKycStepComponent implements OnInit, OnChanges, OnDestroy {
       this.panVerifyError = 'Client must be created first. Complete General tab and click Next.';
       return;
     }
-    const pan = this.kycForm.value.panNumber;
+    const pan = (this.kycForm.value.panNumber || '').toUpperCase().trim();
     if (!pan) {
       this.panVerifyError = 'Enter PAN number first.';
+      this.kycForm.get('panNumber')?.markAsTouched();
+      return;
+    }
+    // Block API call when the PAN format is invalid — Fineract would accept
+    // the raw value otherwise and persist a junk record.
+    if (!/^[A-Z]{5}[0-9]{4}[A-Z]{1}$/.test(pan)) {
+      this.panVerifyError = 'Invalid PAN format. Expected pattern: ABCDE1234F (5 letters, 4 digits, 1 letter).';
+      this.kycForm.get('panNumber')?.setErrors({ pattern: true });
+      this.kycForm.get('panNumber')?.markAsTouched();
       return;
     }
 
@@ -893,8 +1032,20 @@ export class ClientKycStepComponent implements OnInit, OnChanges, OnDestroy {
    */
   verifyEnterprisePan() {
     if (!this.clientId) return;
-    const pan = this.kycForm.value.enterprisePan;
-    if (!pan || this.kycForm.get('enterprisePan')?.invalid) return;
+    const pan = (this.kycForm.value.enterprisePan || '').toUpperCase().trim();
+    if (!pan) {
+      this.showPanErrorAlert('Enter Enterprise PAN number first.');
+      this.kycForm.get('enterprisePan')?.markAsTouched();
+      return;
+    }
+    if (!/^[A-Z]{5}[0-9]{4}[A-Z]{1}$/.test(pan)) {
+      this.showPanErrorAlert(
+        'Invalid Enterprise PAN format. Expected pattern: ABCDE1234F (5 letters, 4 digits, 1 letter).'
+      );
+      this.kycForm.get('enterprisePan')?.setErrors({ pattern: true });
+      this.kycForm.get('enterprisePan')?.markAsTouched();
+      return;
+    }
 
     this.entPanVerifying = true;
     const dateFormat = this.settingsService.dateFormat;
@@ -955,8 +1106,18 @@ export class ClientKycStepComponent implements OnInit, OnChanges, OnDestroy {
   /** Verify GSTIN via API */
   verifyGstin() {
     if (!this.clientId) return;
-    const gstin = this.kycForm.value.gstinNumber;
-    if (!gstin || this.kycForm.get('gstinNumber')?.invalid) return;
+    const gstin = (this.kycForm.value.gstinNumber || '').toUpperCase().trim();
+    if (!gstin) {
+      this.showPanErrorAlert('Enter GSTIN number first.');
+      this.kycForm.get('gstinNumber')?.markAsTouched();
+      return;
+    }
+    if (!/^[0-9]{2}[A-Z]{5}[0-9]{4}[A-Z]{1}[1-9A-Z]{1}Z[0-9A-Z]{1}$/.test(gstin)) {
+      this.showPanErrorAlert('Invalid GSTIN format. Expected pattern: 22AAAAA0000A1Z5 (15 characters).');
+      this.kycForm.get('gstinNumber')?.setErrors({ pattern: true });
+      this.kycForm.get('gstinNumber')?.markAsTouched();
+      return;
+    }
 
     this.gstinVerifying = true;
     const dateFormat = this.settingsService.dateFormat;
@@ -1019,8 +1180,18 @@ export class ClientKycStepComponent implements OnInit, OnChanges, OnDestroy {
 
   /** Verify CIN (dummy — no real API) */
   verifyCin() {
-    const cin = this.kycForm.value.cinNumber;
-    if (!cin) return;
+    const cin = (this.kycForm.value.cinNumber || '').toUpperCase().trim();
+    if (!cin) {
+      this.showPanErrorAlert('Enter CIN number first.');
+      this.kycForm.get('cinNumber')?.markAsTouched();
+      return;
+    }
+    if (!/^[A-Z]{1}[0-9]{5}[A-Z]{2}[0-9]{4}[A-Z]{3}[0-9]{6}$/.test(cin)) {
+      this.showPanErrorAlert('Invalid CIN format. Expected pattern: L17110MH1973PLC019786 (21 characters).');
+      this.kycForm.get('cinNumber')?.setErrors({ pattern: true });
+      this.kycForm.get('cinNumber')?.markAsTouched();
+      return;
+    }
 
     this.cinVerifying = true;
     this.cinProgressValue = 0;
@@ -1068,9 +1239,16 @@ export class ClientKycStepComponent implements OnInit, OnChanges, OnDestroy {
       this.aadhaarVerifyError = 'Client must be created first. Complete General tab and click Next.';
       return;
     }
-    const aadhaar = this.kycForm.value.aadhaarNumber;
-    if (!aadhaar || aadhaar.length !== 12) {
-      this.aadhaarVerifyError = 'Enter valid 12-digit Aadhaar first.';
+    const aadhaar = (this.kycForm.value.aadhaarNumber || '').trim();
+    if (!aadhaar) {
+      this.aadhaarVerifyError = 'Enter Aadhaar number first.';
+      this.kycForm.get('aadhaarNumber')?.markAsTouched();
+      return;
+    }
+    if (!/^\d{12}$/.test(aadhaar)) {
+      this.aadhaarVerifyError = 'Invalid Aadhaar format. Aadhaar must be exactly 12 digits.';
+      this.kycForm.get('aadhaarNumber')?.setErrors({ pattern: true });
+      this.kycForm.get('aadhaarNumber')?.markAsTouched();
       return;
     }
 
@@ -1287,6 +1465,18 @@ export class ClientKycStepComponent implements OnInit, OnChanges, OnDestroy {
     const dateFormat = this.settingsService.dateFormat;
     const v = formVal;
     const formatDate = (d: any) => (d instanceof Date ? this.dateUtils.formatDate(d, dateFormat) : d || null);
+    // Backend regex on these identifiers is upper-case only; tolerate user-typed lowercase
+    // / whitespace here so the save doesn't 400 on
+    //   "validation.msg.CLIENTKYC.panNumber.does.not.match.regexp"
+    // (or the equivalent for gstin / cin / enterprisePan).
+    const norm = (s: any): string | null => {
+      const out = (s || '').toString().toUpperCase().replace(/\s+/g, '');
+      return out.length ? out : null;
+    };
+    const panNorm = norm(v.panNumber);
+    const enterprisePanNorm = norm(v.enterprisePan);
+    const gstinNorm = norm(v.gstinNumber);
+    const cinNorm = norm(v.cinNumber);
 
     return {
       locale: 'en',
@@ -1294,12 +1484,12 @@ export class ClientKycStepComponent implements OnInit, OnChanges, OnDestroy {
       kycType: 1,
       riskCategory: v.riskCategory || 1,
       // For non-individual: Company PAN is used as panNumber for verification
-      panNumber: this.isNonIndividual ? v.enterprisePan || null : v.hasPan ? v.panNumber || null : null,
+      panNumber: this.isNonIndividual ? enterprisePanNorm : v.hasPan ? panNorm : null,
       aadhaarNumberMasked: this.isNonIndividual ? 'XXXXXXXX0000' : aadhaarMasked,
       panAadhaarSeedingStatus: this.panAadhaarSeedingStatus || null,
-      gstinNumber: v.gstinNumber || null,
-      enterprisePan: v.enterprisePan || null,
-      cinNumber: v.cinNumber || null,
+      gstinNumber: gstinNorm,
+      enterprisePan: enterprisePanNorm,
+      cinNumber: cinNorm,
       incorporationDate: formatDate(v.incorporationDate),
       // KYC Document
       kycDocumentName: v.kycDocumentName || null,

src/app/clients/clients-view/address-tab/address-tab.component.html

@@ -104,14 +104,23 @@
               <div class="addr-field__value">{{ address.countyDistrict }}</div>
             </div>
           }
-          @if (address.stateProvinceId) {
-            <div class="addr-field">
-              <div class="addr-field__label">State</div>
-              <div class="addr-field__value">
-                {{ getSelectedValue('stateProvinceIdOptions', address.stateProvinceId)?.name || '-' }}
-              </div>
+          <!-- State — always render. The address payload may carry the value
+               under `stateProvinceId` (numeric → resolve via template options),
+               `stateName` / `stateProvinceName` (string), or be missing
+               entirely. Render whatever we can find, otherwise show "—". -->
+          <div class="addr-field">
+            <div class="addr-field__label">State</div>
+            <div class="addr-field__value">
+              {{
+                (address.stateProvinceId
+                  ? getSelectedValue('stateProvinceIdOptions', address.stateProvinceId)?.name
+                  : null) ||
+                  address.stateName ||
+                  address.stateProvinceName ||
+                  '—'
+              }}
             </div>
-          }
+          </div>
           <div class="addr-field">
             <div class="addr-field__label">Country</div>
             <div class="addr-field__value">

src/app/clients/clients-view/address-tab/address-tab.component.ts

@@ -16,6 +16,9 @@ import { SelectBase } from 'app/shared/form-dialog/formfield/model/select-base';
 
 /** Custom Components */
 import { FormDialogComponent } from 'app/shared/form-dialog/form-dialog.component';
+import { EditAddressDialogComponent } from './edit-address-dialog/edit-address-dialog.component';
+import { SuccessDialogComponent } from 'app/shared/success-dialog/success-dialog.component';
+import { ErrorDialogComponent } from 'app/shared/error-dialog/error-dialog.component';
 
 /** Custom Services */
 import { TranslateService } from '@ngx-translate/core';
@@ -87,29 +90,42 @@ export class AddressTabComponent {
    * Adds a client address.
    */
   addAddress() {
-    const data = {
-      title:
-        this.translateService.instant('labels.buttons.Add') +
-        ' ' +
-        this.translateService.instant('labels.catalogs.Client') +
-        ' ' +
-        this.translateService.instant('labels.heading.Address'),
-      formfields: this.getAddressFormFields('add'),
-      layout: { columns: 2, columnWidth: 350 }
-    };
-    const addAddressDialogRef = this.dialog.open(FormDialogComponent, { data });
-    addAddressDialogRef.afterClosed().subscribe((response: any) => {
-      if (response.data) {
-        this.clientService
-          .createClientAddress(this.clientId, response.data.value.addressType, response.data.value)
-          .subscribe((res: any) => {
-            const addressData = response.data.value;
-            addressData.addressId = res.resourceId;
-            addressData.addressType = this.getSelectedValue('addressTypeIdOptions', addressData.addressType).name;
-            addressData.isActive = false;
-            this.clientAddressData.push(addressData);
-          });
-      }
+    // Use the Nexora dialog with PIN lookup + "Copy from existing address" picker.
+    const ref = this.dialog.open(EditAddressDialogComponent, {
+      data: {
+        mode: 'add',
+        title:
+          this.translateService.instant('labels.buttons.Add') +
+          ' ' +
+          this.translateService.instant('labels.catalogs.Client') +
+          ' ' +
+          this.translateService.instant('labels.heading.Address'),
+        address: null,
+        template: this.clientAddressTemplate,
+        fieldConfig: this.clientAddressFieldConfig,
+        existingAddresses: this.clientAddressData || []
+      },
+      panelClass: 'ead-panel',
+      autoFocus: false
+    });
+    ref.afterClosed().subscribe((response: any) => {
+      if (!response?.value) return;
+      const payload = { ...response.value };
+      const typeName = this.getSelectedValue('addressTypeIdOptions', payload.addressType)?.name;
+      this.clientService.createClientAddress(this.clientId, payload.addressType, payload).subscribe({
+        next: (res: any) => {
+          payload.addressId = res.resourceId;
+          payload.addressType = typeName;
+          payload.isActive = false;
+          this.clientAddressData.push(payload);
+          this.showSuccess('Address Added', `${typeName || 'Address'} has been added to this client's profile.`);
+        },
+        error: (err: any) => {
+          const apiMsg =
+            err?.error?.errors?.[0]?.defaultUserMessage || err?.error?.defaultUserMessage || 'Please try again.';
+          this.showError(`Failed to add address. ${apiMsg}`);
+        }
+      });
     });
   }
 
@@ -119,31 +135,54 @@ export class AddressTabComponent {
    * @param {number} index address index
    */
   editAddress(address: any, index: number) {
-    const data = {
-      title:
-        this.translateService.instant('labels.buttons.Edit') +
-        ' ' +
-        this.translateService.instant('labels.catalogs.Client') +
-        ' ' +
-        this.translateService.instant('labels.heading.Address'),
-      formfields: this.getAddressFormFields('edit', address),
-      layout: { columns: 2, columnWidth: 350, addButtonText: 'Edit' }
-    };
-    const editAddressDialogRef = this.dialog.open(FormDialogComponent, { data });
-    editAddressDialogRef.afterClosed().subscribe((response: any) => {
-      if (response.data) {
-        const addressData = response.data.value;
-        addressData.addressId = address.addressId;
-        addressData.isActive = address.isActive;
-        this.clientService
-          .editClientAddress(this.clientId, address.addressTypeId, addressData)
-          .subscribe((res: any) => {
-            addressData.addressTypeId = address.addressTypeId;
-            addressData.addressType = address.addressType;
-            this.clientAddressData[index] = addressData;
-          });
-      }
+    // Open the Nexora edit dialog with PIN lookup (mirrors the stepper).
+    const ref = this.dialog.open(EditAddressDialogComponent, {
+      data: {
+        title:
+          this.translateService.instant('labels.buttons.Edit') +
+          ' ' +
+          this.translateService.instant('labels.catalogs.Client') +
+          ' ' +
+          this.translateService.instant('labels.heading.Address'),
+        address,
+        template: this.clientAddressTemplate,
+        fieldConfig: this.clientAddressFieldConfig
+      },
+      panelClass: 'ead-panel',
+      autoFocus: false
     });
+    ref.afterClosed().subscribe((response: any) => {
+      if (!response?.value) return;
+      const addressData = { ...response.value };
+      addressData.addressId = address.addressId;
+      addressData.isActive = address.isActive;
+      this.clientService.editClientAddress(this.clientId, address.addressTypeId, addressData).subscribe({
+        next: () => {
+          addressData.addressTypeId = address.addressTypeId;
+          addressData.addressType = address.addressType;
+          this.clientAddressData[index] = addressData;
+          this.showSuccess('Address Updated', `${address.addressType || 'Address'} has been updated successfully.`);
+        },
+        error: (err: any) => {
+          const apiMsg =
+            err?.error?.errors?.[0]?.defaultUserMessage || err?.error?.defaultUserMessage || 'Please try again.';
+          this.showError(`Failed to update address. ${apiMsg}`);
+        }
+      });
+    });
+  }
+
+  /** Polished success modal — matches the rest of the Nexora UI. */
+  private showSuccess(title: string, message: string): void {
+    this.dialog.open(SuccessDialogComponent, {
+      data: { title, message, buttonLabel: 'OK' },
+      panelClass: 'sd-panel'
+    });
+  }
+
+  /** Polished error modal — single string body. */
+  private showError(message: string): void {
+    this.dialog.open(ErrorDialogComponent, { data: message });
   }
 
   /**
@@ -297,7 +336,9 @@ export class AddressTabComponent {
       this.isFieldEnabled('countyDistrict')
         ? new InputBase({
             controlName: 'countyDistrict',
-            label: this.translateService.instant('labels.inputs.State / Province'),
+            // Was mistakenly labeled "State / Province" — that label belongs to
+            // the stateProvinceId select above. This control holds the District.
+            label: this.translateService.instant('labels.inputs.County / District'),
             value: address ? address.countyDistrict : '',
             type: 'text',
             order: 11

src/app/clients/clients-view/address-tab/edit-address-dialog/edit-address-dialog.component.html

@@ -0,0 +1,186 @@
+<!--
+  Copyright since 2025 Mifos Initiative
+
+  This Source Code Form is subject to the terms of the Mozilla Public
+  License, v. 2.0. If a copy of the MPL was not distributed with this
+  file, You can obtain one at http://mozilla.org/MPL/2.0/.
+-->
+
+<div class="ead-root">
+  <div class="ead-head">
+    <div class="ead-head__left">
+      <fa-icon icon="map-marker-alt" class="ead-head__ic"></fa-icon>
+      <div>
+        <h2 class="ead-head__title">{{ data.title || (isAdd ? 'Add Client Address' : 'Edit Client Address') }}</h2>
+        <div class="ead-head__sub">
+          @if (isAdd) {
+            Select address type and enter PIN to auto-fill city, district &amp; state.
+          } @else {
+            Update postal details. Enter PIN to auto-fill city, district &amp; state.
+          }
+        </div>
+      </div>
+    </div>
+    <button class="ead-x" (click)="cancel()" matTooltip="Close">
+      <fa-icon icon="times"></fa-icon>
+    </button>
+  </div>
+
+  <form class="ead-body" [formGroup]="form" (ngSubmit)="submit()">
+    <!-- Address Type + Copy-from (Add mode only) -->
+    @if (isAdd) {
+      <div class="ead-grid">
+        <div class="ead-field">
+          <label>Address Type *</label>
+          <select formControlName="addressType">
+            <option [ngValue]="''">— Select address type —</option>
+            @for (t of addressTypeOptions; track t.id) {
+              <option [ngValue]="t.id">{{ t.name }}</option>
+            }
+          </select>
+          @if (form.get('addressType')?.touched && form.get('addressType')?.hasError('required')) {
+            <div class="ead-err">Address type is required.</div>
+          }
+        </div>
+        @if (copySourceOptions.length > 0) {
+          <div class="ead-field">
+            <label>Copy from existing address (optional)</label>
+            <select
+              [(ngModel)]="copyFromAddressId"
+              [ngModelOptions]="{ standalone: true }"
+              (change)="onCopyFromAddress()"
+            >
+              <option [ngValue]="''">— Don't copy —</option>
+              @for (a of copySourceOptions; track a.addressId) {
+                <option [ngValue]="a.addressId">
+                  {{ a.addressType || 'Address' }} &middot; {{ a.city || a.countyDistrict || '' }}
+                  @if (a.postalCode) {
+                    &middot; {{ a.postalCode }}
+                  }
+                </option>
+              }
+            </select>
+          </div>
+        }
+      </div>
+    }
+
+    <!-- PIN + Street -->
+    <div class="ead-grid">
+      <div class="ead-field">
+        <label>Postal Code *</label>
+        <div class="ead-input-wrap">
+          <fa-icon icon="map-pin" class="ead-input-ic"></fa-icon>
+          <input
+            type="text"
+            inputmode="numeric"
+            maxlength="6"
+            formControlName="postalCode"
+            placeholder="6-digit PIN"
+            (input)="onPinInput()"
+            (keypress)="$event.charCode >= 48 && $event.charCode <= 57 ? true : $event.preventDefault()"
+          />
+          @if (pinStatus.loading) {
+            <span class="ead-pin-status loading"
+              ><fa-icon icon="spinner" class="fa-spin"></fa-icon> Looking up&hellip;</span
+            >
+          } @else if (pinStatus.found) {
+            <span class="ead-pin-status ok"><fa-icon icon="check-circle"></fa-icon> PIN verified</span>
+          } @else if (pinStatus.error) {
+            <span class="ead-pin-status err"
+              ><fa-icon icon="exclamation-triangle"></fa-icon> {{ pinStatus.message }}</span
+            >
+          }
+        </div>
+        @if (form.get('postalCode')?.touched && form.get('postalCode')?.hasError('pattern')) {
+          <div class="ead-err">Enter a valid 6-digit PIN.</div>
+        }
+      </div>
+      @if (isFieldEnabled('street')) {
+        <div class="ead-field">
+          <label>Street</label>
+          <input type="text" formControlName="street" placeholder="Street, Road, Lane" />
+        </div>
+      }
+    </div>
+
+    <!-- Address lines -->
+    <div class="ead-grid">
+      @if (isFieldEnabled('addressLine1')) {
+        <div class="ead-field">
+          <label>Address Line 1</label>
+          <input type="text" formControlName="addressLine1" placeholder="House / Building No." />
+        </div>
+      }
+      @if (isFieldEnabled('addressLine2')) {
+        <div class="ead-field">
+          <label>Address Line 2</label>
+          <input type="text" formControlName="addressLine2" placeholder="Apartment / Block" />
+        </div>
+      }
+    </div>
+
+    <div class="ead-grid">
+      @if (isFieldEnabled('addressLine3')) {
+        <div class="ead-field">
+          <label>Address Line 3</label>
+          <input type="text" formControlName="addressLine3" placeholder="Locality / Sector" />
+        </div>
+      }
+      @if (isFieldEnabled('townVillage')) {
+        <div class="ead-field">
+          <label>Town / Village (Locality)</label>
+          <select formControlName="townVillage">
+            <option [ngValue]="''">— Select —</option>
+            @for (loc of effectiveLocalityOptions; track loc) {
+              <option [ngValue]="loc">{{ loc }}</option>
+            }
+          </select>
+        </div>
+      }
+    </div>
+
+    <!-- City / District / State -->
+    <div class="ead-grid ead-grid--three">
+      @if (isFieldEnabled('city')) {
+        <div class="ead-field">
+          <label>City</label>
+          <input type="text" formControlName="city" placeholder="City" />
+        </div>
+      }
+      @if (isFieldEnabled('countyDistrict')) {
+        <div class="ead-field">
+          <label>County / District</label>
+          <input type="text" formControlName="countyDistrict" placeholder="District" />
+        </div>
+      }
+      @if (isFieldEnabled('stateProvinceId')) {
+        <div class="ead-field">
+          <label>State / Province</label>
+          <!-- Plain text — populated by the PIN service, mirrors create wizard.
+               On submit we resolve to the matching stateProvinceId for the API. -->
+          <input type="text" formControlName="state" placeholder="State / Province" />
+        </div>
+      }
+    </div>
+
+    <!-- Country -->
+    @if (isFieldEnabled('countryId')) {
+      <div class="ead-grid">
+        <div class="ead-field">
+          <label>Country</label>
+          <input type="text" formControlName="country" placeholder="Country" />
+        </div>
+        <div></div>
+      </div>
+    }
+
+    <div class="ead-actions">
+      <button type="button" class="ead-btn ghost" (click)="cancel()">Cancel</button>
+      <button type="submit" class="ead-btn primary" [disabled]="form.invalid">
+        <fa-icon [icon]="isAdd ? 'plus' : 'check'"></fa-icon>
+        {{ isAdd ? 'Add Address' : 'Save Changes' }}
+      </button>
+    </div>
+  </form>
+</div>

src/app/clients/clients-view/address-tab/edit-address-dialog/edit-address-dialog.component.scss

@@ -0,0 +1,274 @@
+/**
+ * Copyright since 2025 Mifos Initiative
+ *
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ */
+
+$navy: #0d1b2a;
+$blue: #1e88e5;
+$blue-d: #1e40af;
+$green: #10b981;
+$red: #ef4444;
+$amber: #f59e0b;
+$purple: #7c3aed;
+
+:host {
+  display: block;
+}
+
+.ead-root {
+  background: #fff;
+  width: 760px;
+  max-width: 96vw;
+  max-height: 92vh;
+  display: flex;
+  flex-direction: column;
+}
+
+.ead-head {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 14px 20px;
+  border-bottom: 1px solid #e2e8f0;
+  background: linear-gradient(180deg, #f8fafc 0%, #fff 100%);
+
+  &__left {
+    display: flex;
+    align-items: center;
+    gap: 12px;
+  }
+
+  &__ic {
+    width: 38px;
+    height: 38px;
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    border-radius: 10px;
+    background: linear-gradient(135deg, $blue 0%, $purple 100%);
+    color: #fff;
+    font-size: 14px;
+    box-shadow: 0 2px 6px -2px rgb(29 78 216 / 35%);
+  }
+
+  &__title {
+    margin: 0;
+    font-size: 16px;
+    font-weight: 800;
+    color: $navy;
+  }
+
+  &__sub {
+    margin-top: 2px;
+    font-size: 11.5px;
+    color: #64748b;
+  }
+}
+
+.ead-x {
+  width: 32px;
+  height: 32px;
+  border-radius: 999px;
+  border: 1px solid #e2e8f0;
+  background: #fff;
+  color: #64748b;
+  cursor: pointer;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+
+  &:hover {
+    background: #fef2f2;
+    color: $red;
+    border-color: #fecaca;
+  }
+}
+
+.ead-body {
+  flex: 1;
+  overflow-y: auto;
+  padding: 16px 20px 20px;
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+}
+
+.ead-grid {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: 10px 14px;
+
+  &--three {
+    grid-template-columns: 1fr 1fr 1fr;
+  }
+}
+
+.ead-field {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+
+  label {
+    font-size: 11px;
+    font-weight: 600;
+    color: #475569;
+  }
+
+  input,
+  select {
+    height: 38px;
+    padding: 0 12px;
+    border: 1px solid #cbd5e1;
+    border-radius: 8px;
+    background: #fff;
+    color: $navy;
+    font-size: 13px;
+    font-weight: 500;
+    transition: all 0.12s;
+
+    &:focus {
+      outline: none;
+      border-color: $blue;
+      box-shadow: 0 0 0 3px rgb(30 136 229 / 14%);
+    }
+  }
+
+  select {
+    appearance: none;
+    background-image:
+      linear-gradient(45deg, transparent 50%, #64748b 50%), linear-gradient(135deg, #64748b 50%, transparent 50%);
+    background-position:
+      calc(100% - 14px) 50%,
+      calc(100% - 9px) 50%;
+    background-size:
+      5px 5px,
+      5px 5px;
+    background-repeat: no-repeat;
+    padding-right: 28px;
+  }
+}
+
+.ead-input-wrap {
+  position: relative;
+  display: flex;
+  align-items: center;
+
+  input {
+    flex: 1;
+    padding-left: 36px;
+  }
+}
+
+.ead-input-ic {
+  position: absolute;
+  left: 12px;
+  color: $blue;
+  font-size: 13px;
+  pointer-events: none;
+}
+
+.ead-pin-status {
+  position: absolute;
+  right: 10px;
+  display: inline-flex;
+  align-items: center;
+  gap: 5px;
+  padding: 2px 9px;
+  border-radius: 999px;
+  font-size: 10.5px;
+  font-weight: 700;
+
+  fa-icon {
+    font-size: 11px;
+  }
+
+  &.ok {
+    background: #ecfdf5;
+    color: #047857;
+    border: 1px solid #a7f3d0;
+  }
+
+  &.loading {
+    background: #eff6ff;
+    color: $blue-d;
+    border: 1px solid #bfdbfe;
+  }
+
+  &.err {
+    background: #fef2f2;
+    color: #b91c1c;
+    border: 1px solid #fecaca;
+  }
+}
+
+.ead-err {
+  font-size: 10.5px;
+  color: $red;
+  font-weight: 600;
+}
+
+.ead-actions {
+  display: flex;
+  justify-content: flex-end;
+  gap: 10px;
+  border-top: 1px solid #e2e8f0;
+  padding-top: 14px;
+  margin-top: 4px;
+}
+
+.ead-btn {
+  display: inline-flex;
+  align-items: center;
+  gap: 8px;
+  height: 38px;
+  padding: 0 18px;
+  border-radius: 8px;
+  font-size: 13px;
+  font-weight: 700;
+  cursor: pointer;
+  transition: all 0.15s;
+  border: 1px solid transparent;
+
+  fa-icon {
+    font-size: 11px;
+  }
+
+  &.ghost {
+    background: #fff;
+    border-color: #d0d5dd;
+    color: #475569;
+
+    &:hover {
+      background: #f8fafc;
+      border-color: #94a3b8;
+      color: $navy;
+    }
+  }
+
+  &.primary {
+    background: linear-gradient(135deg, $blue 0%, $blue-d 100%);
+    border-color: $blue-d;
+    color: #fff;
+    box-shadow: 0 2px 6px -2px rgb(30 64 175 / 35%);
+
+    &:hover:not(:disabled) {
+      box-shadow: 0 4px 12px -3px rgb(30 64 175 / 45%);
+      transform: translateY(-1px);
+    }
+  }
+
+  &:disabled {
+    opacity: 0.55;
+    cursor: not-allowed;
+  }
+}
+
+@media (width <= 640px) {
+  .ead-grid,
+  .ead-grid--three {
+    grid-template-columns: 1fr;
+  }
+}

src/app/clients/clients-view/address-tab/edit-address-dialog/edit-address-dialog.component.ts

@@ -0,0 +1,354 @@
+/**
+ * Copyright since 2025 Mifos Initiative
+ *
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ */
+
+import { Component, OnInit, inject } from '@angular/core';
+import { CommonModule } from '@angular/common';
+import { FormsModule, ReactiveFormsModule, UntypedFormBuilder, UntypedFormGroup, Validators } from '@angular/forms';
+import { MAT_DIALOG_DATA, MatDialogRef } from '@angular/material/dialog';
+import { MatTooltip } from '@angular/material/tooltip';
+import { HttpClient } from '@angular/common/http';
+import { FaIconComponent } from '@fortawesome/angular-fontawesome';
+import { STANDALONE_SHARED_IMPORTS } from 'app/standalone-shared.module';
+
+export interface EditAddressDialogData {
+  /** 'add' shows Address Type select + Copy-from picker; 'edit' hides them. */
+  mode?: 'add' | 'edit';
+  title: string;
+  /** Existing address payload (edit) or null (add). */
+  address: any;
+  template: {
+    addressTypeIdOptions?: { id: number; name: string }[];
+    stateProvinceIdOptions?: { id: number; name: string }[];
+    countryIdOptions?: { id: number; name: string }[];
+    [k: string]: any;
+  };
+  /** Field-config rows from `clientAddressFieldConfig`; used to honour
+   *  the org's address-field visibility / enabling settings. */
+  fieldConfig: { field: string; isEnabled: boolean }[];
+  /** All currently-saved addresses for this client. In 'add' mode the user can
+   *  pick one as the source for "Copy from existing address". */
+  existingAddresses?: any[];
+}
+
+interface PinPostOffice {
+  Name: string;
+  Block?: string;
+  Division?: string;
+  District?: string;
+  State?: string;
+}
+
+/**
+ * Edit Client Address dialog (post-create, in client view).
+ *
+ * Mirrors the create-stepper's address experience:
+ *  • Postal Code field auto-triggers a PIN lookup
+ *  • Locality / Area becomes a dropdown of post offices for that PIN
+ *  • City / District / State auto-fill from the lookup (only when empty)
+ *  • State resolves to the matching `stateProvinceId` from the template
+ *
+ * On submit, returns the form value via `dialogRef.close({ value })`.
+ */
+@Component({
+  selector: 'mifosx-edit-address-dialog',
+  templateUrl: './edit-address-dialog.component.html',
+  styleUrls: ['./edit-address-dialog.component.scss'],
+  imports: [
+    ...STANDALONE_SHARED_IMPORTS,
+    CommonModule,
+    ReactiveFormsModule,
+    FormsModule,
+    FaIconComponent,
+    MatTooltip
+  ]
+})
+export class EditAddressDialogComponent implements OnInit {
+  private fb = inject(UntypedFormBuilder);
+  private http = inject(HttpClient);
+  public dialogRef = inject(MatDialogRef<EditAddressDialogComponent>);
+  public data = inject<EditAddressDialogData>(MAT_DIALOG_DATA);
+
+  form!: UntypedFormGroup;
+  localityOptions: string[] = [];
+  pinStatus: { loading: boolean; found: boolean; error: boolean; message: string } = {
+    loading: false,
+    found: false,
+    error: false,
+    message: ''
+  };
+
+  /** Currently-selected source for "Copy from existing address" (id). */
+  copyFromAddressId: number | '' = '';
+
+  private pinTimer: any = null;
+  private pinCache: Record<string, PinPostOffice[]> = {};
+
+  get isAdd(): boolean {
+    return this.data.mode === 'add';
+  }
+
+  get stateOptions() {
+    return this.data.template?.stateProvinceIdOptions || [];
+  }
+  get countryOptions() {
+    return this.data.template?.countryIdOptions || [];
+  }
+  get addressTypeOptions() {
+    return this.data.template?.addressTypeIdOptions || [];
+  }
+  /** Existing addresses that can be a "Copy from" source (excludes empties). */
+  get copySourceOptions(): any[] {
+    return (this.data.existingAddresses || []).filter((a) => a && (a.addressLine1 || a.postalCode));
+  }
+
+  ngOnInit(): void {
+    const a = this.data.address || {};
+    // Pre-resolve the saved stateProvinceId (numeric, from Fineract) to its
+    // display name so the text field shows something meaningful on load.
+    const savedStateName =
+      a.stateName ||
+      a.stateProvinceName ||
+      (a.stateProvinceId ? (this.stateOptions.find((s) => s.id === a.stateProvinceId)?.name ?? '') : '');
+    const savedCountryName =
+      a.countryName || (a.countryId ? (this.countryOptions.find((c) => c.id === a.countryId)?.name ?? '') : '');
+
+    this.form = this.fb.group({
+      ...(this.isAdd
+        ? {
+            addressType: [
+              a.addressType || '',
+              Validators.required
+            ]
+          }
+        : {}),
+      postalCode: [
+        a.postalCode || '',
+        [
+          Validators.required,
+          Validators.pattern(/^\d{6}$/)
+        ]
+      ],
+      street: [a.street || ''],
+      addressLine1: [a.addressLine1 || ''],
+      addressLine2: [a.addressLine2 || ''],
+      addressLine3: [a.addressLine3 || ''],
+      townVillage: [a.townVillage || ''],
+      city: [a.city || ''],
+      countyDistrict: [a.countyDistrict || ''],
+      // State + Country are plain TEXT now (matching the create-stepper). On
+      // submit we resolve them to the matching template id when possible —
+      // see `submit()`. We also keep the raw original ids around so we don't
+      // lose them if the user doesn't touch the fields.
+      state: [savedStateName],
+      country: [savedCountryName || 'India'],
+      // Hidden originals — used on submit when text wasn't changed.
+      _origStateProvinceId: [a.stateProvinceId || ''],
+      _origCountryId: [a.countryId || '']
+    });
+
+    // If we already have a PIN on load, re-run the lookup so the locality
+    // dropdown is populated and "PIN verified" badge shows in edit mode.
+    if ((a.postalCode || '').toString().length === 6) {
+      this.runPinLookup(true);
+    }
+  }
+
+  /**
+   * Copy address fields from an existing address (selected via the dropdown).
+   * The Address Type is preserved — the user's current selection wins, since
+   * the whole point of "Add" is creating a NEW address type.
+   */
+  onCopyFromAddress(): void {
+    const src = this.copySourceOptions.find((a) => String(a.addressId) === String(this.copyFromAddressId));
+    if (!src) return;
+    const srcStateName =
+      src.stateName ||
+      src.stateProvinceName ||
+      (src.stateProvinceId ? (this.stateOptions.find((s) => s.id === src.stateProvinceId)?.name ?? '') : '');
+    const srcCountryName =
+      src.countryName ||
+      (src.countryId ? (this.countryOptions.find((c) => c.id === src.countryId)?.name ?? 'India') : 'India');
+
+    const patch: Record<string, any> = {
+      postalCode: src.postalCode || '',
+      street: src.street || '',
+      addressLine1: src.addressLine1 || '',
+      addressLine2: src.addressLine2 || '',
+      addressLine3: src.addressLine3 || '',
+      townVillage: src.townVillage || '',
+      city: src.city || '',
+      countyDistrict: src.countyDistrict || '',
+      state: srcStateName,
+      country: srcCountryName,
+      _origStateProvinceId: src.stateProvinceId || '',
+      _origCountryId: src.countryId || ''
+    };
+    this.form.patchValue(patch);
+    // Re-run the PIN lookup so the locality dropdown options + "PIN verified"
+    // chip light up for the copied PIN.
+    if ((patch['postalCode'] || '').toString().length === 6) {
+      this.runPinLookup(true);
+    }
+  }
+
+  isFieldEnabled(field: string): boolean {
+    const cfg = (this.data.fieldConfig || []).find((c) => c.field === field);
+    return cfg ? !!cfg.isEnabled : true;
+  }
+
+  /** PIN input: debounce + lookup. */
+  onPinInput(): void {
+    clearTimeout(this.pinTimer);
+    const pin = (this.form.get('postalCode')?.value || '').toString().replace(/\D/g, '');
+    this.form.get('postalCode')?.setValue(pin, { emitEvent: false });
+    if (pin.length < 6) {
+      this.pinStatus = { loading: false, found: false, error: false, message: '' };
+      this.localityOptions = [];
+      return;
+    }
+    this.pinTimer = setTimeout(() => this.runPinLookup(false), 550);
+  }
+
+  /**
+   * Fetch the post-office list for the current PIN and apply it.
+   * @param preserve when true, don't overwrite existing values for
+   *                  locality / city / district / state (used on load).
+   */
+  private runPinLookup(preserve: boolean): void {
+    const pin = (this.form.get('postalCode')?.value || '').toString();
+    if (pin.length !== 6) return;
+    if (this.pinCache[pin]) {
+      this.applyPinData(this.pinCache[pin], preserve);
+      this.pinStatus = { loading: false, found: true, error: false, message: 'Verified' };
+      return;
+    }
+    this.pinStatus = { loading: true, found: false, error: false, message: 'Looking up...' };
+    this.http.get<any[]>(`https://api.postalpincode.in/pincode/${pin}`).subscribe({
+      next: (data: any) => {
+        if (data?.[0]?.Status === 'Success') {
+          this.pinCache[pin] = data[0].PostOffice;
+          this.applyPinData(data[0].PostOffice, preserve);
+          this.pinStatus = { loading: false, found: true, error: false, message: 'Verified' };
+        } else {
+          this.localityOptions = [];
+          this.pinStatus = { loading: false, found: false, error: true, message: 'Invalid PIN' };
+        }
+      },
+      error: () => {
+        this.pinStatus = { loading: false, found: false, error: true, message: 'Network error' };
+      }
+    });
+  }
+
+  private applyPinData(offices: PinPostOffice[], preserve: boolean): void {
+    const seen = new Set<string>();
+    this.localityOptions = (offices || [])
+      .filter((o) => {
+        if (!o?.Name || seen.has(o.Name)) return false;
+        seen.add(o.Name);
+        return true;
+      })
+      .map((o) => o.Name);
+
+    const first = offices?.[0];
+    if (!first) return;
+
+    const patch: Record<string, any> = {};
+
+    // Town / Village — pick the first locality from the lookup. Skip only when
+    // there's already a saved value AND we're in preserve mode.
+    if (!preserve || !this.form.get('townVillage')?.value) {
+      if (this.localityOptions[0]) patch['townVillage'] = this.localityOptions[0];
+    }
+
+    // City — Block / Division / District fallback chain
+    if (!preserve || !this.form.get('city')?.value) {
+      const cityValue = first.Block || first.Division || first.District || '';
+      if (cityValue) patch['city'] = cityValue;
+    }
+
+    // District
+    if (!preserve || !this.form.get('countyDistrict')?.value) {
+      if (first.District) patch['countyDistrict'] = first.District;
+    }
+
+    // State — stored as plain TEXT in the form (same as the create wizard).
+    // We display whatever the PIN service returns ("Madhya Pradesh", "Kerala",
+    // etc.) without forcing it through the small Fineract dropdown which
+    // sometimes only carries a handful of states.
+    if (!preserve || !this.form.get('state')?.value) {
+      if (first.State) patch['state'] = first.State;
+    }
+
+    // Country — postalpincode.in only serves India. Default to "India" text.
+    if (!preserve || !this.form.get('country')?.value) {
+      patch['country'] = 'India';
+    }
+
+    if (Object.keys(patch).length > 0) {
+      this.form.patchValue(patch);
+    }
+  }
+
+  /** Lowercase, collapse internal whitespace, trim — for fuzzy name matching. */
+  private normalize(s: string | undefined | null): string {
+    return (s || '').toString().toLowerCase().replace(/[-_]+/g, ' ').replace(/\s+/g, ' ').trim();
+  }
+
+  /** Preserve the saved locality even if it's not in the lookup results. */
+  get effectiveLocalityOptions(): string[] {
+    const saved = this.form?.get('townVillage')?.value;
+    if (saved && !this.localityOptions.includes(saved)) {
+      return [
+        saved,
+        ...this.localityOptions
+      ];
+    }
+    return this.localityOptions;
+  }
+
+  submit(): void {
+    if (this.form.invalid) {
+      this.form.markAllAsTouched();
+      return;
+    }
+
+    // Build the API payload — Fineract expects `stateProvinceId` (numeric id)
+    // and `countryId`, not the text names we've been displaying. Resolve via
+    // the template options; fall back to the original ids if the user didn't
+    // change the field.
+    const raw = this.form.value;
+    const payload: Record<string, any> = {
+      postalCode: raw.postalCode,
+      street: raw.street,
+      addressLine1: raw.addressLine1,
+      addressLine2: raw.addressLine2,
+      addressLine3: raw.addressLine3,
+      townVillage: raw.townVillage,
+      city: raw.city,
+      countyDistrict: raw.countyDistrict
+    };
+    if (raw.addressType) payload['addressType'] = raw.addressType;
+
+    const stateMatch = raw.state
+      ? this.stateOptions.find((s) => this.normalize(s.name) === this.normalize(raw.state))
+      : null;
+    payload['stateProvinceId'] = stateMatch ? stateMatch.id : raw._origStateProvinceId || '';
+
+    const countryMatch = raw.country
+      ? this.countryOptions.find((c) => this.normalize(c.name) === this.normalize(raw.country))
+      : null;
+    payload['countryId'] = countryMatch ? countryMatch.id : raw._origCountryId || '';
+
+    this.dialogRef.close({ value: payload });
+  }
+
+  cancel(): void {
+    this.dialogRef.close();
+  }
+}

src/app/clients/clients-view/custom-dialogs/edit-notes-dialog/edit-notes-dialog.component.html

@@ -10,14 +10,29 @@
 <div>
   <form #formRef="ngForm" [formGroup]="noteForm">
     <mat-form-field>
-      <textarea formControlName="note" matInput placeholder="{{ 'labels.text.Write a note' | translate }}"></textarea>
+      <textarea
+        formControlName="note"
+        matInput
+        placeholder="{{ 'labels.text.Write a note' | translate }}"
+        matTooltip="At least two words required — e.g. 'Hello User', 'Updated mobile', 'Re-KYC done'."
+        matTooltipPosition="above"
+        matTooltipShowDelay="300"
+        (keydown)="onNoteKeyDown($event)"
+        (input)="onNoteInput($event)"
+      ></textarea>
+      @if (noteForm.controls['note'].touched && noteForm.controls['note'].hasError('required')) {
+        <mat-error>Note cannot be empty.</mat-error>
+      }
+      @if (noteForm.controls['note'].touched && noteForm.controls['note'].hasError('minWords')) {
+        <mat-error>Note must contain at least 2 words (whitespace doesn't count).</mat-error>
+      }
     </mat-form-field>
     <mat-dialog-actions align="end">
       <button mat-raised-button mat-dialog-close>{{ 'labels.buttons.Cancel' | translate }}</button>
       <button
         mat-raised-button
         color="primary"
-        [disabled]="noteForm.pristine"
+        [disabled]="noteForm.pristine || noteForm.invalid"
         [mat-dialog-close]="{ editForm: noteForm }"
       >
         {{ 'labels.buttons.Confirm' | translate }}

src/app/clients/clients-view/custom-dialogs/edit-notes-dialog/edit-notes-dialog.component.ts

@@ -15,8 +15,10 @@ import {
   MatDialogActions,
   MatDialogClose
 } from '@angular/material/dialog';
+import { MatTooltip } from '@angular/material/tooltip';
 import { UntypedFormGroup, UntypedFormBuilder, Validators, ReactiveFormsModule } from '@angular/forms';
 import { STANDALONE_SHARED_IMPORTS } from 'app/standalone-shared.module';
+import { minWordsValidator } from 'app/shared/validators/min-words.validator';
 
 @Component({
   selector: 'mifosx-edit-notes-dialog',
@@ -26,7 +28,8 @@ import { STANDALONE_SHARED_IMPORTS } from 'app/standalone-shared.module';
     ...STANDALONE_SHARED_IMPORTS,
     MatDialogTitle,
     MatDialogActions,
-    MatDialogClose
+    MatDialogClose,
+    MatTooltip
   ]
 })
 export class EditNotesDialogComponent implements OnInit {
@@ -42,10 +45,37 @@ export class EditNotesDialogComponent implements OnInit {
 
   createNoteForm() {
     this.noteForm = this.formBuilder.group({
+      // Same rule as the entity-notes Add form — reject whitespace / single-word.
       note: [
         this.data.noteContent,
-        Validators.required
+        [
+          Validators.required,
+          minWordsValidator(2)
+        ]
       ]
     });
   }
+
+  /** Block whitespace at position 0 of an otherwise-empty textarea. */
+  onNoteKeyDown(event: KeyboardEvent): void {
+    if (event.key !== ' ' && event.key !== 'Tab' && event.key !== 'Enter') return;
+    const el = event.target as HTMLTextAreaElement;
+    if (el.selectionStart === 0 && el.value.trim() === '') {
+      event.preventDefault();
+    }
+  }
+
+  /** Strip leading whitespace + collapse internal runs of spaces/tabs. */
+  onNoteInput(event: Event): void {
+    const el = event.target as HTMLTextAreaElement;
+    const before = el.value;
+    const after = before.replace(/^[ \t]+/, '').replace(/[ \t]{2,}/g, ' ');
+    if (before !== after) {
+      const cursorDelta = before.length - after.length;
+      const pos = Math.max(0, (el.selectionStart ?? after.length) - cursorDelta);
+      el.value = after;
+      this.noteForm.get('note')!.setValue(after, { emitEvent: false });
+      el.setSelectionRange(pos, pos);
+    }
+  }
 }

src/app/clients/clients-view/identities-tab/identities-tab.component.ts

@@ -44,6 +44,8 @@ import { TranslateService } from '@ngx-translate/core';
 import { ClientsService } from '../../clients.service';
 import { FaIconComponent } from '@fortawesome/angular-fontawesome';
 import { STANDALONE_SHARED_IMPORTS } from 'app/standalone-shared.module';
+import { Observable, of } from 'rxjs';
+import { map } from 'rxjs/operators';
 
 /**
  * Identities Tab Component
@@ -206,15 +208,57 @@ export class IdentitiesTabComponent implements OnDestroy {
   /**
    * Create one identifier from a KYC section payload, then upload each file
    * as a document attached to that identifier.
+   *
+   * `section.proofId` may arrive either as a numeric CodeValue id (when sourced from
+   * /kyc/proof-types — the address-proof chip-picker is built from this list and works
+   * straight away) or as a string CODE like "AADHAAR" / "PAN" (when sourced from the
+   * KYC step's constitution-driven document list — that list isn't backed by
+   * CodeValues). The backend's ClientIdentifierRequest.documentTypeId is a Long, so a
+   * string proofId triggers Spring's HttpMessageNotReadableException → generic 400
+   * "String instead of Number". Route through resolveDocumentTypeId so we always post
+   * a numeric documentTypeId.
    */
   private createIdentifierWithDocs(section: any, description: string, kind: 'id' | 'address'): void {
-    const identifierData = {
-      documentTypeId: section.proofId,
-      status: 'Active',
-      documentKey: kind === 'id' ? section.documentKey : `${section.proof?.name || 'Address Proof'} - ${this.clientId}`,
-      description: kind === 'address' && section.address ? section.address : description
-    };
+    const proofName = section.proof?.name || (kind === 'address' ? 'Address Proof' : 'KYC Document');
+    this.resolveDocumentTypeId(section.proofId, proofName).subscribe((documentTypeId: number | null) => {
+      if (documentTypeId == null) {
+        // No CodeValue match (e.g. a constitution-specific non-individual doc like
+        // "Trust Deed" that hasn't been seeded). Skip silently rather than firing the
+        // 400 — the parent already captured the file separately if needed.
+        return;
+      }
+      const identifierData = {
+        documentTypeId,
+        status: 'Active',
+        documentKey: kind === 'id' ? section.documentKey : `${proofName} - ${this.clientId}`,
+        description: kind === 'address' && section.address ? section.address : description
+      };
 
+      this.postIdentifierAndDocs(identifierData, section, proofName, description);
+    });
+  }
+
+  /**
+   * Pass-through when proofId is already numeric (address proof, identities tab address
+   * picker). Otherwise resolve the string code/name against the ID-proof CodeValues so
+   * the backend gets a proper Long for documentTypeId.
+   */
+  private resolveDocumentTypeId(proofId: any, proofName: string): Observable<number | null> {
+    if (typeof proofId === 'number' && Number.isFinite(proofId)) {
+      return of(proofId);
+    }
+    return this.clientService.getKycProofTypes('id').pipe(
+      map((res: any) => {
+        const list: any[] = res?.idProofs || [];
+        const target = (proofName || '').trim().toLowerCase();
+        const match = list.find((p: any) => (p?.name || '').trim().toLowerCase() === target);
+        return (match?.id ?? null) as number | null;
+      })
+    );
+  }
+
+  /** Extracted post-and-upload-files step so the resolver wrapper stays readable. */
+  private postIdentifierAndDocs(identifierData: any, section: any, proofName: string, description: string): void {
     this.clientService.addClientIdentifier(this.clientId, identifierData).subscribe({
       next: (res: any) => {
         const newIdentifierId = res.resourceId;

src/app/clients/clients-view/kyc-tab/kyc-tab.component.html

@@ -203,27 +203,54 @@
             <span class="kv-table__col kv-table__col--action"></span>
           </div>
         }
+      </div>
 
-        <!-- PAN-Aadhaar Link Row -->
-        <div class="kv-table__row kv-table__row--link">
-          <span class="kv-table__col kv-table__col--doc">
-            <mat-icon class="kv-doc-icon">link</mat-icon> PAN–Aadhaar Link
-          </span>
-          <span class="kv-table__col kv-table__col--num">Sec 139AA</span>
-          <span class="kv-table__col kv-table__col--status">
-            @if (kycData?.panAadhaarSeedingStatus === 'Y') {
-              <span class="kv-status kv-status--ok"><mat-icon>check_circle</mat-icon> Linked</span>
-            } @else if (kycData?.panAadhaarSeedingStatus === 'N') {
-              <span class="kv-status kv-status--fail"><mat-icon>cancel</mat-icon> Not Linked</span>
-            } @else if (kycData?.panAadhaarSeedingStatus === 'E') {
-              <span class="kv-status kv-status--info"><mat-icon>info</mat-icon> Exempt</span>
-            } @else {
-              <span class="kv-status kv-status--pending"><mat-icon>radio_button_unchecked</mat-icon> Pending</span>
-            }
-          </span>
-          <span class="kv-table__col kv-table__col--date">—</span>
-          <span class="kv-table__col kv-table__col--action"></span>
+      <!-- ─── PAN ↔ Aadhaar Link — premium status card (replaces the legacy
+             table row). Dark gradient base with state-driven accent so the
+             linking state is the first thing a reviewer sees. -->
+      <div
+        class="pal-card"
+        [class.pal-card--ok]="kycData?.panAadhaarSeedingStatus === 'Y'"
+        [class.pal-card--fail]="kycData?.panAadhaarSeedingStatus === 'N'"
+        [class.pal-card--info]="kycData?.panAadhaarSeedingStatus === 'E'"
+        [class.pal-card--pending]="
+          kycData?.panAadhaarSeedingStatus !== 'Y' &&
+          kycData?.panAadhaarSeedingStatus !== 'N' &&
+          kycData?.panAadhaarSeedingStatus !== 'E'
+        "
+      >
+        <div class="pal-card__left">
+          <div class="pal-card__icon">
+            <mat-icon>credit_card</mat-icon>
+          </div>
+          <div class="pal-card__txt">
+            <div class="pal-card__small">Verification Status</div>
+            <div class="pal-card__title">PAN &harr; Aadhaar</div>
+            <div class="pal-card__status">
+              @if (kycData?.panAadhaarSeedingStatus === 'Y') {
+                <mat-icon>check_circle</mat-icon> Linked (Seeded)
+              } @else if (kycData?.panAadhaarSeedingStatus === 'N') {
+                <mat-icon>cancel</mat-icon> Not Linked
+              } @else if (kycData?.panAadhaarSeedingStatus === 'E') {
+                <mat-icon>info</mat-icon> Exempt
+              } @else {
+                <mat-icon>radio_button_unchecked</mat-icon> Pending
+              }
+            </div>
+          </div>
         </div>
+        <div class="pal-card__badge">
+          @if (kycData?.panAadhaarSeedingStatus === 'Y') {
+            <mat-icon>check</mat-icon>
+          } @else if (kycData?.panAadhaarSeedingStatus === 'N') {
+            <mat-icon>close</mat-icon>
+          } @else if (kycData?.panAadhaarSeedingStatus === 'E') {
+            <mat-icon>info</mat-icon>
+          } @else {
+            <mat-icon>schedule</mat-icon>
+          }
+        </div>
+        <div class="pal-card__hint">As per Income Tax Portal &mdash; Section 139AA</div>
       </div>
 
       <!-- Aadhaar OTP inline (shown below table when re-verifying) -->

src/app/clients/clients-view/kyc-tab/kyc-tab.component.scss

@@ -989,3 +989,276 @@
     max-width: 100%;
   }
 }
+
+/* ═══════════════════════════════════════════════════════════════
+   PAN ↔ Aadhaar premium status card
+   ─── Replaces the legacy table-row treatment. Dark gradient with
+        offset glow circles, large gradient icon, and a state-driven
+        accent (green / red / blue / amber).
+   ═══════════════════════════════════════════════════════════════ */
+.pal-card {
+  margin-top: 16px;
+  width: 100%;
+  min-height: 88px;
+  padding: 14px 18px 30px;
+  border-radius: 18px;
+  position: relative;
+  overflow: hidden;
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  background: linear-gradient(135deg, #111827, #0f172a);
+  border: 1px solid rgb(255 255 255 / 8%);
+  box-shadow:
+    0 12px 32px rgb(0 0 0 / 35%),
+    inset 0 1px 1px rgb(255 255 255 / 5%);
+  font-family: Inter, 'Segoe UI', Roboto, sans-serif;
+
+  /* Decorative glows — colors swap with the state variant */
+  &::before {
+    content: '';
+    position: absolute;
+    width: 180px;
+    height: 180px;
+    background: #2563eb;
+    border-radius: 50%;
+    top: -110px;
+    right: -70px;
+    opacity: 0.18;
+    pointer-events: none;
+  }
+
+  &::after {
+    content: '';
+    position: absolute;
+    width: 120px;
+    height: 120px;
+    background: #22c55e;
+    border-radius: 50%;
+    bottom: -70px;
+    left: -50px;
+    opacity: 0.12;
+    pointer-events: none;
+  }
+
+  &__left {
+    display: flex;
+    align-items: center;
+    gap: 14px;
+    z-index: 2;
+  }
+
+  &__icon {
+    width: 54px;
+    height: 54px;
+    border-radius: 16px;
+    background: linear-gradient(145deg, #2563eb, #06b6d4);
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    color: #fff;
+    font-size: 22px;
+    position: relative;
+    box-shadow: 0 10px 20px rgb(37 99 235 / 35%);
+    flex-shrink: 0;
+
+    mat-icon {
+      font-size: 26px;
+      width: 26px;
+      height: 26px;
+    }
+
+    &::before {
+      content: '';
+      position: absolute;
+      inset: 0;
+      border-radius: 16px;
+      border: 1px solid rgb(255 255 255 / 20%);
+    }
+  }
+
+  &__txt {
+    display: flex;
+    flex-direction: column;
+    gap: 4px;
+  }
+
+  &__small {
+    font-size: 10.5px;
+    color: #94a3b8;
+    letter-spacing: 0.1em;
+    text-transform: uppercase;
+    font-weight: 700;
+  }
+
+  &__title {
+    color: #fff;
+    font-size: 17px;
+    font-weight: 700;
+    line-height: 1.1;
+  }
+
+  &__status {
+    display: inline-flex;
+    align-items: center;
+    gap: 6px;
+    margin-top: 4px;
+    padding: 4px 11px;
+    border-radius: 50px;
+    background: rgb(34 197 94 / 12%);
+    border: 1px solid rgb(74 222 128 / 25%);
+    color: #4ade80;
+    font-size: 11.5px;
+    font-weight: 600;
+    backdrop-filter: blur(5px);
+    width: fit-content;
+
+    mat-icon {
+      font-size: 13px;
+      width: 13px;
+      height: 13px;
+    }
+  }
+
+  &__badge {
+    z-index: 2;
+    width: 42px;
+    height: 42px;
+    border-radius: 50%;
+    background: linear-gradient(135deg, #22c55e, #16a34a);
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    color: #fff;
+    box-shadow: 0 0 18px rgb(34 197 94 / 45%);
+    flex-shrink: 0;
+
+    mat-icon {
+      font-size: 20px;
+      width: 20px;
+      height: 20px;
+    }
+  }
+
+  &__hint {
+    position: absolute;
+    bottom: 8px;
+    right: 16px;
+    font-size: 10px;
+    color: rgb(255 255 255 / 35%);
+    font-style: italic;
+    letter-spacing: 0.02em;
+    z-index: 1;
+  }
+
+  /* ─── State variants ─── */
+  &--ok {
+    &::before {
+      background: #2563eb;
+    }
+
+    &::after {
+      background: #22c55e;
+    }
+  }
+
+  &--fail {
+    border-color: rgb(239 68 68 / 22%);
+
+    &::before {
+      background: #ef4444;
+      opacity: 0.22;
+    }
+
+    &::after {
+      background: #f87171;
+      opacity: 0.16;
+    }
+
+    .pal-card__status {
+      background: rgb(239 68 68 / 14%);
+      border-color: rgb(248 113 113 / 32%);
+      color: #fca5a5;
+    }
+
+    .pal-card__badge {
+      background: linear-gradient(135deg, #ef4444, #b91c1c);
+      box-shadow: 0 0 18px rgb(239 68 68 / 45%);
+    }
+
+    .pal-card__icon {
+      background: linear-gradient(145deg, #ef4444, #f97316);
+      box-shadow: 0 10px 20px rgb(239 68 68 / 35%);
+    }
+  }
+
+  &--info {
+    border-color: rgb(59 130 246 / 22%);
+
+    &::before {
+      background: #3b82f6;
+      opacity: 0.22;
+    }
+
+    &::after {
+      background: #60a5fa;
+      opacity: 0.14;
+    }
+
+    .pal-card__status {
+      background: rgb(59 130 246 / 14%);
+      border-color: rgb(96 165 250 / 32%);
+      color: #93c5fd;
+    }
+
+    .pal-card__badge {
+      background: linear-gradient(135deg, #3b82f6, #1d4ed8);
+      box-shadow: 0 0 18px rgb(59 130 246 / 45%);
+    }
+  }
+
+  &--pending {
+    border-color: rgb(245 158 11 / 22%);
+
+    &::before {
+      background: #f59e0b;
+      opacity: 0.22;
+    }
+
+    &::after {
+      background: #fbbf24;
+      opacity: 0.14;
+    }
+
+    .pal-card__status {
+      background: rgb(245 158 11 / 14%);
+      border-color: rgb(251 191 36 / 32%);
+      color: #fbbf24;
+    }
+
+    .pal-card__badge {
+      background: linear-gradient(135deg, #f59e0b, #b45309);
+      box-shadow: 0 0 18px rgb(245 158 11 / 45%);
+    }
+
+    .pal-card__icon {
+      background: linear-gradient(145deg, #f59e0b, #d97706);
+      box-shadow: 0 10px 20px rgb(245 158 11 / 35%);
+    }
+  }
+}
+
+@media (width <= 540px) {
+  .pal-card {
+    flex-wrap: wrap;
+    gap: 10px;
+    padding-bottom: 36px;
+
+    &__hint {
+      position: static;
+      width: 100%;
+      text-align: right;
+      margin-top: 4px;
+    }
+  }
+}

src/app/clients/clients-view/nominee-tab/nominee-tab.component.html

@@ -284,6 +284,13 @@
             </div>
           }
 
+          @if (selfSelectError) {
+            <div class="search-self-error">
+              <mat-icon>error_outline</mat-icon>
+              {{ selfSelectError }}
+            </div>
+          }
+
           @if (selectedClient) {
             <!-- Linked Client Card -->
             <div class="nom-linked-card">
@@ -431,6 +438,12 @@
                         }
                       </div>
                     }
+                    @if (guardianSelfSelectError) {
+                      <div class="search-self-error">
+                        <mat-icon>error_outline</mat-icon>
+                        {{ guardianSelfSelectError }}
+                      </div>
+                    }
                   } @else {
                     <span class="nom-guardian-selected"
                       >{{ selectedGuardian.displayName }}

src/app/clients/clients-view/nominee-tab/nominee-tab.component.scss

@@ -516,6 +516,27 @@ $primary-light: #e8f0fe;
   padding: 4px 0;
 }
 
+/* Shown when the user tries to pick themselves as nominee / guardian. */
+.search-self-error {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  margin-top: 6px;
+  padding: 6px 10px;
+  background: #fef2f2;
+  border: 1px solid #fecaca;
+  border-radius: 6px;
+  color: #b91c1c;
+  font-size: 11.5px;
+  font-weight: 600;
+
+  mat-icon {
+    font-size: 14px;
+    width: 14px;
+    height: 14px;
+  }
+}
+
 /* Linked card */
 .nom-linked-card {
   display: flex;

src/app/clients/clients-view/nominee-tab/nominee-tab.component.ts

@@ -295,9 +295,11 @@ export class NomineeTabComponent implements OnInit {
     this.searching = true;
     this.searchTimer = setTimeout(() => {
       // Nominee picker (post-create tab): nominees must be natural persons.
+      // The host client is excluded from results so they can't be picked as
+      // their own nominee.
       this.clientsService.searchByText(text, 0, 8, '', '', true, 'INDIVIDUAL').subscribe({
         next: (data: any) => {
-          this.searchResults = data?.content || [];
+          this.searchResults = (data?.content || []).filter((c: any) => !this.isSelfClient(c?.id));
           this.searching = false;
           this.clientsService.enrichSearchResults(this.searchResults);
         },
@@ -316,7 +318,21 @@ export class NomineeTabComponent implements OnInit {
     }, 200);
   }
 
+  /** Self-check: prevent a client from being added as their own nominee/guardian. */
+  isSelfClient(clientId: number | string | null | undefined): boolean {
+    if (this.clientId == null || clientId == null) return false;
+    return String(this.clientId) === String(clientId);
+  }
+
+  /** Inline error shown above the picker when the user tries to pick themselves. */
+  selfSelectError = '';
+
   selectClient(client: any): void {
+    if (this.isSelfClient(client?.id)) {
+      this.selfSelectError = `You can't link this client as their own nominee. Please pick a different person.`;
+      return;
+    }
+    this.selfSelectError = '';
     this.selectedClient = client;
     this.searchResults = [];
     this.searchText = '';
@@ -414,9 +430,10 @@ export class NomineeTabComponent implements OnInit {
     this.guardianSearching = true;
     this.guardianSearchTimer = setTimeout(() => {
       // Guardian picker (post-create tab): guardians must be natural persons.
+      // The host client is filtered out so they can't be picked as their own guardian.
       this.clientsService.searchByText(text, 0, 8, '', '', true, 'INDIVIDUAL').subscribe({
         next: (data: any) => {
-          this.guardianSearchResults = data?.content || [];
+          this.guardianSearchResults = (data?.content || []).filter((c: any) => !this.isSelfClient(c?.id));
           this.guardianSearching = false;
           this.clientsService.enrichSearchResults(this.guardianSearchResults);
         },
@@ -428,7 +445,15 @@ export class NomineeTabComponent implements OnInit {
     }, 400);
   }
 
+  /** Inline error shown above the guardian picker when self-select is attempted. */
+  guardianSelfSelectError = '';
+
   selectGuardian(client: any): void {
+    if (this.isSelfClient(client?.id)) {
+      this.guardianSelfSelectError = `You can't link this client as their own guardian. Please pick a different person.`;
+      return;
+    }
+    this.guardianSelfSelectError = '';
     this.selectedGuardian = client;
     this.guardianSearchResults = [];
     this.guardianSearchText = '';

src/app/clients/clients.service.ts

@@ -474,6 +474,26 @@ export class ClientsService {
     return this.http.get(`/client/${clientId}/addresses`);
   }
 
+  /**
+   * Documents attached to an m_client_address row. The generic document API takes
+   * `client_addresses` as the parent-entity type — see DocumentApiResource.
+   * Used by the address-step component to render a thumbnail of the proof file the user
+   * previously uploaded so it isn't invisible on the edit screen.
+   */
+  getClientAddressDocuments(clientAddressId: string) {
+    return this.http.get(`/client_addresses/${clientAddressId}/documents`);
+  }
+
+  downloadClientAddressDocument(clientAddressId: string, documentId: string) {
+    return this.http.get(`/client_addresses/${clientAddressId}/documents/${documentId}/attachment`, {
+      responseType: 'blob'
+    });
+  }
+
+  uploadClientAddressDocument(clientAddressId: string, documentData: any) {
+    return this.http.post(`/client_addresses/${clientAddressId}/documents`, documentData);
+  }
+
   getClientAddressTemplate() {
     return this.http.get(`/client/addresses/template`);
   }

src/app/clients/common-resolvers/client-identities.resolver.ts

@@ -11,8 +11,8 @@ import { Injectable, inject } from '@angular/core';
 import { ActivatedRouteSnapshot } from '@angular/router';
 
 /** rxjs Imports */
-import { Observable, forkJoin, from } from 'rxjs';
-import { map } from 'rxjs/operators';
+import { Observable, forkJoin, of } from 'rxjs';
+import { map, switchMap } from 'rxjs/operators';
 
 /** Custom Services */
 import { ClientsService } from '../clients.service';
@@ -25,25 +25,24 @@ export class ClientIdentitiesResolver {
   private clientsService = inject(ClientsService);
 
   /**
-   * Returns the Client Identities data.
-   * @returns {Observable<any>}
+   * Returns the Client Identities data with each identifier's attached documents
+   * already populated. We previously fired the per-identifier document fetches inside a
+   * non-blocking `subscribe`, so the resolver returned BEFORE the documents arrived and
+   * the view rendered with empty `documents` arrays.
    */
   resolve(route: ActivatedRouteSnapshot): Observable<any> {
     const clientId = route.parent.paramMap.get('clientId');
-    let identitiesData: any;
     return this.clientsService.getClientIdentifiers(clientId).pipe(
-      map((identities: any) => {
-        identitiesData = identities;
-        const docObservable: Observable<any>[] = [];
-        identities.forEach((identity: any) => {
-          docObservable.push(this.clientsService.getClientIdentificationDocuments(identity.id));
-        });
-        forkJoin(docObservable).subscribe((documents) => {
-          documents.forEach((document, index) => {
-            identitiesData[index].documents = document;
-          });
-        });
-        return identitiesData;
+      switchMap((identities: any[]) => {
+        if (!identities || identities.length === 0) {
+          return of(identities || []);
+        }
+        const enriched$ = identities.map((identity: any) =>
+          this.clientsService
+            .getClientIdentificationDocuments(identity.id)
+            .pipe(map((documents: any) => ({ ...identity, documents })))
+        );
+        return forkJoin(enriched$);
       })
     );
   }

src/app/clients/create-client/create-client.component.html

@@ -245,7 +245,10 @@
             color="primary"
             class="save-next-btn"
             (click)="onNext()"
-            [disabled]="savingClient || (selectedTabIndex === 0 && clientGeneralStep?.sanctionsBlocked)"
+            [disabled]="!currentStepValid"
+            [matTooltip]="currentStepBlockerMessage"
+            [matTooltipDisabled]="currentStepValid"
+            matTooltipPosition="above"
           >
             @if (savingClient) {
               <mat-progress-spinner

src/app/clients/create-client/create-client.component.ts

@@ -9,6 +9,8 @@
 /** Angular Imports */
 import { Component, QueryList, ViewChild, ViewChildren, inject } from '@angular/core';
 import { Router, ActivatedRoute } from '@angular/router';
+import { Observable, of } from 'rxjs';
+import { map } from 'rxjs/operators';
 
 /** Custom Services */
 import { ClientsService } from '../clients.service';
@@ -133,6 +135,76 @@ export class CreateClientComponent {
     return 5;
   }
 
+  /**
+   * Per-tab form-validity gate for the Save & Next button.
+   * Returns false when the current tab has unfilled / invalid required fields
+   * so the user can't move forward (and the button is visibly disabled).
+   * The mapping follows the tab order in create-client.component.html:
+   *   0  General
+   *   1  KYC & Documents
+   *   2  (non-individual) Scheme & Sector  |  (individual) Address
+   *   3  (non-individual) Address          |  (individual) Family
+   *   4  Application Summary  (handled by Submit, not Save & Next)
+   */
+  get currentStepValid(): boolean {
+    if (this.savingClient) return false;
+    const idx = this.selectedTabIndex;
+
+    if (idx === 0) {
+      if (!this.clientGeneralStep || !this.clientGeneralForm) return false;
+      if (this.clientGeneralStep.sanctionsBlocked) return false;
+      return this.clientGeneralForm.valid;
+    }
+    if (idx === 1) {
+      // KYC tab — block when the kyc form has unfilled required fields
+      // (kycDocumentName / kycDocumentNumber / pattern errors on PAN / Aadhaar etc.)
+      const kf = this.clientKycStep?.kycForm;
+      return !kf || kf.valid;
+    }
+    if (this.legalFormType === 2) {
+      if (idx === 2) {
+        // Scheme & Sector (entity KYC) — categories are opt-in, so always allow.
+        return true;
+      }
+      if (idx === 3) {
+        // Address tab for non-individuals
+        return this.isAddressStepValid();
+      }
+    } else {
+      if (idx === 2) {
+        // Address tab for individuals
+        return this.isAddressStepValid();
+      }
+      if (idx === 3) {
+        // Family tab — relations are optional, always allow.
+        return true;
+      }
+    }
+    return true;
+  }
+
+  /** Permanent address is the only mandatory address; current/office/correspondence are optional. */
+  private isAddressStepValid(): boolean {
+    const step = this.clientIndiaAddressStep;
+    if (!step) return true; // step not yet mounted — don't block
+    const perm = step.permanentForm;
+    return !perm || perm.valid;
+  }
+
+  /**
+   * Human-readable explanation of why the Save & Next button is disabled.
+   * Surfaced via matTooltip so the user knows what to fix.
+   */
+  get currentStepBlockerMessage(): string {
+    if (this.savingClient) return 'Saving — please wait…';
+    if (this.currentStepValid) return '';
+    const idx = this.selectedTabIndex;
+    if (idx === 0 && this.clientGeneralStep?.sanctionsBlocked) {
+      return 'Client failed sanctions screening — cannot proceed.';
+    }
+    return 'Please fill all mandatory fields on this tab to continue.';
+  }
+
   /** Get constitution type from general step for entity KYC */
   getConstitutionType(): string {
     return this.clientGeneralStep?.createClientForm?.get('clientNonPersonDetails.constitutionId')?.value || '';
@@ -521,11 +593,17 @@ export class CreateClientComponent {
             isActive: tab === 'permanent'
           };
 
-          // Try to resolve state to stateProvinceId
+          // Try to resolve state to stateProvinceId. We normalise both sides (lowercase,
+          // collapse underscores + whitespace) so legacy UPPER_SNAKE rows still match the
+          // postal-PIN API's "Madhya Pradesh" form and vice versa. See migration 0297.
           if ((addr as any).state && template?.stateProvinceIdOptions?.length) {
-            const stateMatch = template.stateProvinceIdOptions.find(
-              (s: any) => s.name?.toLowerCase() === (addr as any).state?.toLowerCase()
-            );
+            const norm = (s: string) =>
+              (s || '')
+                .toLowerCase()
+                .replace(/[_\s]+/g, ' ')
+                .trim();
+            const target = norm((addr as any).state);
+            const stateMatch = template.stateProvinceIdOptions.find((s: any) => norm(s.name) === target);
             if (stateMatch) payload.stateProvinceId = stateMatch.id;
           }
 
@@ -580,28 +658,60 @@ export class CreateClientComponent {
     if (!payload?.proofId || !payload?.files?.length) return;
 
     const proofName = payload.proof?.name || 'KYC Document';
-    const identifierData: any = {
-      documentTypeId: payload.proofId,
-      status: 'Active',
-      documentKey: payload.documentKey || `${proofName} - ${clientId}`,
-      description: 'KYC document'
-    };
+    // The KYC step's chip-picker carries `id` as a doc-type CODE string (e.g. "AADHAAR")
+    // because its list is constitution-driven, not CodeValue-backed. The backend
+    // ClientIdentifierRequest.documentTypeId is a Long, so a string proofId trips Jackson
+    // with HttpMessageNotReadableException → 400. Resolve to the numeric CodeValue id by
+    // matching on name against /kyc/proof-types?type=id before posting.
+    this.resolveDocumentTypeId(payload.proofId, proofName).subscribe((documentTypeId: number | null) => {
+      if (documentTypeId == null) {
+        // No CodeValue match (e.g. non-individual constitution-specific docs). Skip the
+        // identifier save rather than firing a 400; the form's other KYC fields still get
+        // persisted via the KYC entity.
+        return;
+      }
+      const identifierData: any = {
+        documentTypeId,
+        status: 'Active',
+        documentKey: payload.documentKey || `${proofName} - ${clientId}`,
+        description: 'KYC document'
+      };
 
-    this.clientsService.addClientIdentifier(clientId, identifierData).subscribe({
-      next: (res: any) => {
-        const identifierId = res?.resourceId;
-        if (!identifierId) return;
-        for (const entry of payload.files) {
-          const formData = new FormData();
-          formData.append('name', `${proofName} — ${entry.slot}`);
-          formData.append('file', entry.file);
-          this.clientsService.uploadClientIdentifierDocument(identifierId, formData).subscribe({ error: () => {} });
-        }
-      },
-      error: () => {}
+      this.clientsService.addClientIdentifier(clientId, identifierData).subscribe({
+        next: (res: any) => {
+          const identifierId = res?.resourceId;
+          if (!identifierId) return;
+          for (const entry of payload.files) {
+            const formData = new FormData();
+            formData.append('name', `${proofName} — ${entry.slot}`);
+            formData.append('file', entry.file);
+            this.clientsService.uploadClientIdentifierDocument(identifierId, formData).subscribe({ error: () => {} });
+          }
+        },
+        error: () => {}
+      });
     });
   }
 
+  /**
+   * Pass-through when proofId is already numeric (address proof, identities tab). Otherwise
+   * resolve the string code/name against the ID-proof CodeValues so the backend gets a
+   * proper Long for documentTypeId.
+   */
+  private resolveDocumentTypeId(proofId: any, proofName: string): Observable<number | null> {
+    if (typeof proofId === 'number' && Number.isFinite(proofId)) {
+      return of(proofId);
+    }
+    return this.clientsService.getKycProofTypes('id').pipe(
+      map((res: any) => {
+        const list: any[] = res?.idProofs || [];
+        const targetName = (proofName || '').trim().toLowerCase();
+        const match = list.find((p: any) => (p?.name || '').trim().toLowerCase() === targetName);
+        return (match?.id ?? null) as number | null;
+      })
+    );
+  }
+
   /**
    * Save family members via POST /clients/{id}/familymembers
    */

src/app/clients/edit-client/edit-client.component.html

@@ -207,7 +207,15 @@
         </button>
       }
       @if (selectedTabIndex < totalTabs - 1) {
-        <button mat-raised-button color="primary" (click)="onNext()" [disabled]="savingClient">
+        <button
+          mat-raised-button
+          color="primary"
+          (click)="onNext()"
+          [disabled]="!currentStepValid"
+          [matTooltip]="currentStepBlockerMessage"
+          [matTooltipDisabled]="currentStepValid"
+          matTooltipPosition="above"
+        >
           @if (savingClient) {
             <mat-progress-spinner diameter="18" mode="indeterminate" class="m-r-10"></mat-progress-spinner>
             Saving...

src/app/clients/edit-client/edit-client.component.ts

@@ -10,6 +10,8 @@
 import { Component, QueryList, ViewChild, ViewChildren, inject } from '@angular/core';
 import { Router, ActivatedRoute } from '@angular/router';
 import { MatDialog } from '@angular/material/dialog';
+import { Observable, of } from 'rxjs';
+import { map } from 'rxjs/operators';
 
 /** Custom Services */
 import { ClientsService } from '../clients.service';
@@ -145,6 +147,57 @@ export class EditClientComponent {
     return areValids;
   }
 
+  /**
+   * Per-tab form-validity gate for the Save & Next button. Mirrors the create
+   * flow — blocks navigation when the current tab has unfilled / invalid
+   * required fields. Tab order:
+   *   0  General
+   *   1  KYC & Documents
+   *   2  (non-individual) Scheme & Sector  |  (individual) Address
+   *   3  (non-individual) Address          |  (individual) Family
+   *   4  (non-individual) Family           |  Preview / Submit
+   */
+  get currentStepValid(): boolean {
+    if (this.savingClient) return false;
+    const idx = this.selectedTabIndex;
+
+    if (idx === 0) {
+      if (!this.clientGeneralStep || !this.clientGeneralForm) return false;
+      if (this.clientGeneralStep.sanctionsBlocked) return false;
+      return this.clientGeneralForm.valid;
+    }
+    if (idx === 1) {
+      const kf = this.clientKycStep?.kycForm;
+      return !kf || kf.valid;
+    }
+    if (this.legalFormType === 2) {
+      if (idx === 2) return true; // Scheme & Sector — opt-in
+      if (idx === 3) return this.isAddressStepValid();
+      if (idx === 4) return true; // Family — optional
+    } else {
+      if (idx === 2) return this.isAddressStepValid();
+      if (idx === 3) return true; // Family — optional
+    }
+    return true;
+  }
+
+  private isAddressStepValid(): boolean {
+    const step = this.clientIndiaAddressStep;
+    if (!step) return true;
+    const perm = step.permanentForm;
+    return !perm || perm.valid;
+  }
+
+  /** Human-readable explanation surfaced via matTooltip on the disabled button. */
+  get currentStepBlockerMessage(): string {
+    if (this.savingClient) return 'Saving — please wait…';
+    if (this.currentStepValid) return '';
+    if (this.selectedTabIndex === 0 && this.clientGeneralStep?.sanctionsBlocked) {
+      return 'Client failed sanctions screening — cannot proceed.';
+    }
+    return 'Please fill all mandatory fields on this tab to continue.';
+  }
+
   /** Whether the current tab has unsaved edits */
   isCurrentTabEdited(): boolean {
     return this.tabEditMode[this.selectedTabIndex] === true;
@@ -637,10 +690,17 @@ export class EditClientComponent {
             isActive: tab === 'permanent'
           };
 
+          // Resolve state name to stateProvinceId. Normalise both sides (lowercase,
+          // collapse underscores + whitespace) so legacy UPPER_SNAKE rows still match
+          // the postal-PIN API's "Madhya Pradesh" form and vice versa. See migration 0297.
           if ((addr as any).state && template?.stateProvinceIdOptions?.length) {
-            const stateMatch = template.stateProvinceIdOptions.find(
-              (s: any) => s.name?.toLowerCase() === (addr as any).state?.toLowerCase()
-            );
+            const norm = (s: string) =>
+              (s || '')
+                .toLowerCase()
+                .replace(/[_\s]+/g, ' ')
+                .trim();
+            const target = norm((addr as any).state);
+            const stateMatch = template.stateProvinceIdOptions.find((s: any) => norm(s.name) === target);
             if (stateMatch) payload.stateProvinceId = stateMatch.id;
           }
 
@@ -695,28 +755,55 @@ export class EditClientComponent {
     if (!payload?.proofId || !payload?.files?.length) return;
 
     const proofName = payload.proof?.name || 'KYC Document';
-    const identifierData: any = {
-      documentTypeId: payload.proofId,
-      status: 'Active',
-      documentKey: payload.documentKey || `${proofName} - ${clientId}`,
-      description: 'KYC document'
-    };
+    // The KYC step's chip-picker carries `id` as a doc-type CODE string (e.g. "AADHAAR").
+    // The backend ClientIdentifierRequest.documentTypeId is a Long, so a string proofId
+    // trips Jackson → HttpMessageNotReadableException → 400. Resolve to numeric CodeValue
+    // id by matching on name against /kyc/proof-types?type=id before posting.
+    this.resolveDocumentTypeId(payload.proofId, proofName).subscribe((documentTypeId: number | null) => {
+      if (documentTypeId == null) {
+        return;
+      }
+      const identifierData: any = {
+        documentTypeId,
+        status: 'Active',
+        documentKey: payload.documentKey || `${proofName} - ${clientId}`,
+        description: 'KYC document'
+      };
 
-    this.clientsService.addClientIdentifier(clientId, identifierData).subscribe({
-      next: (res: any) => {
-        const identifierId = res?.resourceId;
-        if (!identifierId) return;
-        for (const entry of payload.files) {
-          const formData = new FormData();
-          formData.append('name', `${proofName} — ${entry.slot}`);
-          formData.append('file', entry.file);
-          this.clientsService.uploadClientIdentifierDocument(identifierId, formData).subscribe({ error: () => {} });
-        }
-      },
-      error: () => {}
+      this.clientsService.addClientIdentifier(clientId, identifierData).subscribe({
+        next: (res: any) => {
+          const identifierId = res?.resourceId;
+          if (!identifierId) return;
+          for (const entry of payload.files) {
+            const formData = new FormData();
+            formData.append('name', `${proofName} — ${entry.slot}`);
+            formData.append('file', entry.file);
+            this.clientsService.uploadClientIdentifierDocument(identifierId, formData).subscribe({ error: () => {} });
+          }
+        },
+        error: () => {}
+      });
     });
   }
 
+  /**
+   * Pass-through when proofId is already numeric (address proof). Otherwise resolve the
+   * string code/name against the ID-proof CodeValues so the backend gets a proper Long.
+   */
+  private resolveDocumentTypeId(proofId: any, proofName: string): Observable<number | null> {
+    if (typeof proofId === 'number' && Number.isFinite(proofId)) {
+      return of(proofId);
+    }
+    return this.clientsService.getKycProofTypes('id').pipe(
+      map((res: any) => {
+        const list: any[] = res?.idProofs || [];
+        const targetName = (proofName || '').trim().toLowerCase();
+        const match = list.find((p: any) => (p?.name || '').trim().toLowerCase() === targetName);
+        return (match?.id ?? null) as number | null;
+      })
+    );
+  }
+
   private saveClientFamilyMembers(clientId: string) {
     const members = this.clientFamilyMembersStep.clientFamilyMembers;
     for (const member of members) {