Add client groups and family tracking

app/modules/clients/filters.py

@@ -6,6 +6,7 @@ class ClientListFilters:
     q: str = ""
     status: str = ""
     client_type: str = ""
+    client_group_id: int | None = None
     partner_id: int | None = None
     include_archived: bool = False
     page: int = 1
@@ -20,6 +21,9 @@ class ClientListFilters:
             partner_id = None
         elif not isinstance(partner_id, int):
             partner_id = int(partner_id)
+        client_group_id = kwargs.get("client_group_id")
+        if client_group_id in ("", None): client_group_id = None
+        elif not isinstance(client_group_id, int): client_group_id = int(client_group_id)
         include_archived = kwargs.get("include_archived", False)
         if isinstance(include_archived, str):
             include_archived = include_archived.lower() in ("1", "true", "yes", "on")
@@ -27,6 +31,7 @@ class ClientListFilters:
             q=kwargs.get("q", "") or "",
             status=kwargs.get("status", "") or "",
             client_type=kwargs.get("client_type", "") or "",
+            client_group_id=client_group_id,
             partner_id=partner_id,
             include_archived=include_archived,
             page=max(int(kwargs.get("page", 1) or 1), 1),

app/modules/clients/import_service.py

@@ -11,6 +11,7 @@ from sqlalchemy import select
 from sqlalchemy.orm import Session
 
 from app.modules.client_identity.service import ensure_identity, normalize_pan, placeholder_email
+from app.modules.client_groups.service import get_group_by_code, resolve_or_create_group
 from app.modules.clients import repository
 from app.modules.clients.models import Client
 from app.modules.clients.schemas import ClientCreate
@@ -31,6 +32,11 @@ TEMPLATE_COLUMNS = [
     "referral_status",
     "communication_routing_mode",
     "branch_id",
+    "client_group_code",
+    "client_group_name",
+    "group_type",
+    "group_relationship",
+    "is_group_head",
     "client_code",
     "client_name",
     "client_type",
@@ -75,6 +81,7 @@ TEMPLATE_COLUMNS = [
 ]
 
 BOOL_FIELDS = {
+    "is_group_head",
     "gst_applicable",
     "income_tax_applicable",
     "tds_applicable",
@@ -239,6 +246,11 @@ def build_client_import_template_bytes(*, current_user, tenant_id: int, partner_
         "partner_user_id": "Must be an active Partner user in the same firm.",
         "referred_by_consultant_id": "Optional active consultant profile id who introduced the client.",
         "primary_consultant_id": "Optional active consultant profile id for the operational client link.",
+        "client_group_code": "Optional tenant-unique group code. Existing group is matched by this code.",
+        "client_group_name": "Required only when creating a new group during import.",
+        "group_type": "Family, Business Group, Promoter Group, Trust Group, Common Management, or Other.",
+        "group_relationship": "Optional relationship such as Spouse, HUF, Company, Trust, or Related Concern.",
+        "is_group_head": "yes/no. Only one group head is recommended per group.",
         "referral_date": "Optional referral date supported by the existing client schema.",
         "referral_reference": "Optional referral or source reference.",
         "referral_status": "active, inactive, ended, or pending.",
@@ -407,6 +419,9 @@ def build_preview(
             "tenant_id": firm_tenant_id,
             "branch_id": branch_id,
             "partner_id": partner_user_id or None,
+            "client_group_id": None,
+            "group_relationship": cleaned.get("group_relationship"),
+            "is_group_head": bool(cleaned.get("is_group_head")),
             "referred_by_consultant_id": referred_id,
             "primary_consultant_id": primary_id,
             "referral_date": cleaned.get("referral_date"),
@@ -470,6 +485,9 @@ def build_preview(
                 "tenant_id": firm_tenant_id,
                 "branch_id": branch_id,
                 "partner_id": partner_user_id,
+                "client_group_code": cleaned.get("client_group_code"),
+                "client_group_name": cleaned.get("client_group_name"),
+                "group_type": cleaned.get("group_type") or "Family",
                 "client_payload": payload,
                 "portal_password": password,
                 "portal_password_confirm": password_confirm,
@@ -530,6 +548,16 @@ def commit_import(
             if existing_user:
                 raise ValueError("Email is already used by another ERP login.")
 
+            group = resolve_or_create_group(
+                db, tenant_id=int(payload["tenant_id"]), actor_user_id=current_user.id,
+                group_code=item.get("client_group_code"), group_name=item.get("client_group_name"), group_type=item.get("group_type"),
+            )
+            payload["client_group_id"] = group.id if group else None
+            if group and payload.get("is_group_head"):
+                existing_head = db.execute(select(Client).where(Client.tenant_id == int(payload["tenant_id"]), Client.client_group_id == group.id, Client.is_group_head.is_(True))).scalar_one_or_none()
+                if existing_head:
+                    raise ValueError(f"Group {group.group_code} already has group head {existing_head.client_code} - {existing_head.client_name}.")
+
             data = ClientCreate(**payload)
             row = create_client_service(
                 db,

app/modules/clients/models.py

@@ -20,6 +20,9 @@ class Client(CommonBase):
     tenant_id: Mapped[int] = mapped_column(ForeignKey("tenants.id"), nullable=False, index=True)
     branch_id: Mapped[int] = mapped_column(ForeignKey("branches.id"), nullable=False, index=True)
     partner_id: Mapped[int | None] = mapped_column(ForeignKey("users.id"), nullable=True, index=True)
+    client_group_id: Mapped[int | None] = mapped_column(ForeignKey("client_groups.id", ondelete="SET NULL"), nullable=True, index=True)
+    group_relationship: Mapped[str | None] = mapped_column(String(100), nullable=True)
+    is_group_head: Mapped[bool] = mapped_column(Boolean, nullable=False, default=False, index=True)
     default_review_partner_user_id: Mapped[int | None] = mapped_column(ForeignKey("users.id"), nullable=True, index=True)
     referred_by_consultant_id: Mapped[int | None] = mapped_column(ForeignKey("consultant_profiles.id", ondelete="SET NULL"), nullable=True, index=True)
     referral_date: Mapped[date | None] = mapped_column(Date, nullable=True)

app/modules/clients/repository.py

@@ -9,6 +9,7 @@ from app.core.security.passwords import hash_password
 from app.modules.clients.association_models import ClientAssociation
 from app.modules.clients.constants import CLIENT_SORT_FIELDS
 from app.modules.clients.models import Client, ClientAuditLog
+from app.modules.client_groups.models import ClientGroup
 from app.modules.core.iam.models import User
 from app.modules.core.rbac.models import Role, UserRole
 from app.modules.core.tenancy.models import Branch, Tenant
@@ -30,16 +31,18 @@ def build_clients_query(
     q: str = "",
     status: str = "",
     client_type: str = "",
+    client_group_id: int | None = None,
     include_archived: bool = False,
 ):
     assoc = ClientAssociation
-
     stmt = (
         select(
             Client,
             User.full_name.label("partner_name"),
             Branch.name.label("branch_name"),
             Tenant.name.label("tenant_name"),
+            ClientGroup.group_name.label("client_group_name"),
+            ClientGroup.group_code.label("client_group_code"),
             assoc.association_type.label("association_type"),
             assoc.firm_tenant_id.label("assoc_firm_tenant_id"),
             assoc.consultant_id.label("assoc_consultant_id"),
@@ -47,189 +50,85 @@ def build_clients_query(
             assoc.created_source.label("assoc_created_source"),
         )
         .outerjoin(assoc, assoc.client_id == Client.id)
+        .outerjoin(ClientGroup, ClientGroup.id == Client.client_group_id)
         .join(User, User.id == Client.partner_id, isouter=True)
         .join(Branch, Branch.id == Client.branch_id, isouter=True)
         .join(Tenant, Tenant.id == Client.tenant_id, isouter=True)
     )
-
     if not allow_all_clients:
         stmt = stmt.where(Client.tenant_id == tenant_id)
-
     if not include_archived:
         stmt = stmt.where(Client.is_archived.is_(False))
-
     if branch_id and not allow_all_clients and not allow_cross_branch:
         stmt = stmt.where(Client.branch_id == branch_id)
-
     if partner_id:
-        stmt = stmt.where(
-            (Client.partner_id == partner_id) | (assoc.partner_user_id == partner_id)
-        )
-
+        stmt = stmt.where((Client.partner_id == partner_id) | (assoc.partner_user_id == partner_id))
     if status:
         stmt = stmt.where(Client.status == status)
-
     if client_type:
         stmt = stmt.where(Client.client_type == client_type)
-
+    if client_group_id:
+        stmt = stmt.where(Client.client_group_id == client_group_id)
     if q:
         like = f"%{q.strip()}%"
-        stmt = stmt.where(
-            or_(
-                Client.client_code.ilike(like),
-                Client.client_name.ilike(like),
-                Client.trade_name.ilike(like),
-                Client.pan.ilike(like),
-                Client.gstin.ilike(like),
-                Client.mobile.ilike(like),
-                Client.email.ilike(like),
-            )
-        )
-
+        stmt = stmt.where(or_(
+            Client.client_code.ilike(like), Client.client_name.ilike(like), Client.trade_name.ilike(like),
+            Client.pan.ilike(like), Client.gstin.ilike(like), Client.mobile.ilike(like), Client.email.ilike(like),
+            ClientGroup.group_name.ilike(like), ClientGroup.group_code.ilike(like),
+        ))
     return stmt
 
 
 def list_clients(
-    db: Session,
-    *,
-    tenant_id: int,
-    branch_id: int | None = None,
-    allow_cross_branch: bool = False,
-    allow_all_clients: bool = False,
-    partner_id: int | None = None,
-    q: str = "",
-    status: str = "",
-    client_type: str = "",
-    include_archived: bool = False,
-    page: int = 1,
-    per_page: int = 10,
-    sort_by: str = "client_name",
-    sort_order: str = "asc",
+    db: Session, *, tenant_id: int, branch_id: int | None = None,
+    allow_cross_branch: bool = False, allow_all_clients: bool = False,
+    partner_id: int | None = None, q: str = "", status: str = "", client_type: str = "",
+    client_group_id: int | None = None, include_archived: bool = False,
+    page: int = 1, per_page: int = 10, sort_by: str = "client_name", sort_order: str = "asc",
 ) -> dict:
     stmt = build_clients_query(
-        tenant_id=tenant_id,
-        branch_id=branch_id,
-        allow_cross_branch=allow_cross_branch,
-        allow_all_clients=allow_all_clients,
-        partner_id=partner_id,
-        q=q,
-        status=status,
-        client_type=client_type,
-        include_archived=include_archived,
+        tenant_id=tenant_id, branch_id=branch_id, allow_cross_branch=allow_cross_branch,
+        allow_all_clients=allow_all_clients, partner_id=partner_id, q=q, status=status,
+        client_type=client_type, client_group_id=client_group_id, include_archived=include_archived,
     )
-
     total = db.execute(select(func.count()).select_from(stmt.subquery())).scalar_one()
-    result = db.execute(
-        stmt.order_by(_safe_sort(sort_by, sort_order))
-        .offset((page - 1) * per_page)
-        .limit(per_page)
-    ).all()
-
-    rows = []
-    for (
-        client,
-        partner_name,
-        branch_name,
-        tenant_name,
-        association_type,
-        assoc_firm_tenant_id,
-        assoc_consultant_id,
-        assoc_partner_user_id,
-        assoc_created_source,
-    ) in result:
-        row = {**client.__dict__}
-        row.pop("_sa_instance_state", None)
-        row.update(
-            {
-                "partner_name": partner_name,
-                "branch_name": branch_name,
-                "tenant_name": tenant_name,
-                "association_type": association_type,
-                "assoc_firm_tenant_id": assoc_firm_tenant_id,
-                "assoc_consultant_id": assoc_consultant_id,
-                "assoc_partner_user_id": assoc_partner_user_id,
-                "assoc_created_source": assoc_created_source,
-                "effective_partner_id": assoc_partner_user_id or row.get("partner_id"),
-            }
-        )
-        rows.append(row)
-
-    stats_stmt = select(
-        func.count(Client.id),
-        func.sum(case((Client.status == "active", 1), else_=0)),
-        func.sum(case((Client.status == "inactive", 1), else_=0)),
-        func.sum(case((Client.status == "archived", 1), else_=0)),
-    )
-
+    result = db.execute(stmt.order_by(_safe_sort(sort_by, sort_order)).offset((page - 1) * per_page).limit(per_page)).all()
+    rows=[]
+    for client, partner_name, branch_name, tenant_name, client_group_name, client_group_code, association_type, assoc_firm_tenant_id, assoc_consultant_id, assoc_partner_user_id, assoc_created_source in result:
+        row={**client.__dict__}; row.pop("_sa_instance_state",None)
+        row.update({
+            "partner_name":partner_name,"branch_name":branch_name,"tenant_name":tenant_name,
+            "client_group_name":client_group_name,"client_group_code":client_group_code,
+            "association_type":association_type,"assoc_firm_tenant_id":assoc_firm_tenant_id,
+            "assoc_consultant_id":assoc_consultant_id,"assoc_partner_user_id":assoc_partner_user_id,
+            "assoc_created_source":assoc_created_source,"effective_partner_id":assoc_partner_user_id or row.get("partner_id"),
+        }); rows.append(row)
+    stats_stmt=select(func.count(Client.id),func.sum(case((Client.status=="active",1),else_=0)),func.sum(case((Client.status=="inactive",1),else_=0)),func.sum(case((Client.status=="archived",1),else_=0)))
     if not allow_all_clients:
-        stats_stmt = stats_stmt.where(Client.tenant_id == tenant_id)
-        if branch_id and not allow_cross_branch:
-            stats_stmt = stats_stmt.where(Client.branch_id == branch_id)
-
-    if partner_id:
-        stats_stmt = stats_stmt.where(Client.partner_id == partner_id)
-
-    total_all, active, inactive, archived = db.execute(stats_stmt).one()
-
-    pages = ceil(total / per_page) if per_page else 1
-    return {
-        "rows": rows,
-        "meta": {
-            "total": total,
-            "page": page,
-            "per_page": per_page,
-            "pages": max(pages, 1),
-        },
-        "stats": {
-            "total": int(total_all or 0),
-            "active": int(active or 0),
-            "inactive": int(inactive or 0),
-            "archived": int(archived or 0),
-        },
-    }
+        stats_stmt=stats_stmt.where(Client.tenant_id==tenant_id)
+        if branch_id and not allow_cross_branch: stats_stmt=stats_stmt.where(Client.branch_id==branch_id)
+    if partner_id: stats_stmt=stats_stmt.where(Client.partner_id==partner_id)
+    total_all,active,inactive,archived=db.execute(stats_stmt).one()
+    pages=ceil(total/per_page) if per_page else 1
+    return {"rows":rows,"meta":{"total":total,"page":page,"per_page":per_page,"pages":max(pages,1)},"stats":{"total":int(total_all or 0),"active":int(active or 0),"inactive":int(inactive or 0),"archived":int(archived or 0)}}
 
 
 def get_client_detail_payload(db: Session, client_id: int):
-    assoc = ClientAssociation
-
-    stmt = (
-        select(
-            Client,
-            assoc.association_type.label("association_type"),
-            assoc.firm_tenant_id.label("assoc_firm_tenant_id"),
-            assoc.consultant_id.label("assoc_consultant_id"),
-            assoc.partner_user_id.label("assoc_partner_user_id"),
-            assoc.created_source.label("assoc_created_source"),
-        )
-        .outerjoin(assoc, assoc.client_id == Client.id)
-        .where(Client.id == client_id)
-    )
-
-    result = db.execute(stmt).one_or_none()
-    if not result:
-        return None
-
-    (
-        client,
-        association_type,
-        assoc_firm_tenant_id,
-        assoc_consultant_id,
-        assoc_partner_user_id,
-        assoc_created_source,
-    ) = result
-
-    row = {**client.__dict__}
-    row.pop("_sa_instance_state", None)
-    row.update(
-        {
-            "association_type": association_type,
-            "assoc_firm_tenant_id": assoc_firm_tenant_id,
-            "assoc_consultant_id": assoc_consultant_id,
-            "assoc_partner_user_id": assoc_partner_user_id,
-            "assoc_created_source": assoc_created_source,
-            "effective_partner_id": assoc_partner_user_id or row.get("partner_id"),
-        }
-    )
+    assoc=ClientAssociation
+    stmt=(select(
+        Client, ClientGroup.group_name.label("client_group_name"), ClientGroup.group_code.label("client_group_code"),
+        assoc.association_type.label("association_type"), assoc.firm_tenant_id.label("assoc_firm_tenant_id"),
+        assoc.consultant_id.label("assoc_consultant_id"), assoc.partner_user_id.label("assoc_partner_user_id"),
+        assoc.created_source.label("assoc_created_source"),
+    ).outerjoin(assoc,assoc.client_id==Client.id).outerjoin(ClientGroup,ClientGroup.id==Client.client_group_id).where(Client.id==client_id))
+    result=db.execute(stmt).one_or_none()
+    if not result: return None
+    client,client_group_name,client_group_code,association_type,assoc_firm_tenant_id,assoc_consultant_id,assoc_partner_user_id,assoc_created_source=result
+    row={**client.__dict__}; row.pop("_sa_instance_state",None)
+    row.update({"client_group_name":client_group_name,"client_group_code":client_group_code,"association_type":association_type,
+        "assoc_firm_tenant_id":assoc_firm_tenant_id,"assoc_consultant_id":assoc_consultant_id,
+        "assoc_partner_user_id":assoc_partner_user_id,"assoc_created_source":assoc_created_source,
+        "effective_partner_id":assoc_partner_user_id or row.get("partner_id")})
     return row
 
 

app/modules/clients/schemas.py

@@ -21,6 +21,9 @@ class ClientBase(BaseModel):
     tenant_id: int
     branch_id: int
     partner_id: Optional[int] = None
+    client_group_id: Optional[int] = None
+    group_relationship: Optional[str] = None
+    is_group_head: bool = False
     default_review_partner_user_id: Optional[int] = None
     referred_by_consultant_id: Optional[int] = None
     primary_consultant_id: Optional[int] = None
@@ -88,7 +91,7 @@ class ClientBase(BaseModel):
 
     @field_validator(
         "trade_name", "cin_llpin", "msme_no", "iec_code", "contact_person_name", "contact_person_designation",
-        "address_line_1", "address_line_2", "city", "state", "country", "client_category", "risk_category", "referral_reference", "acceptance_review_notes", "acceptance_rejection_reason", "notes",
+        "address_line_1", "address_line_2", "city", "state", "country", "client_category", "risk_category", "referral_reference", "group_relationship", "acceptance_review_notes", "acceptance_rejection_reason", "notes",
         mode="before",
     )
     @classmethod
@@ -213,6 +216,9 @@ class ClientUpdate(BaseModel):
     tenant_id: Optional[int] = None
     branch_id: Optional[int] = None
     partner_id: Optional[int] = None
+    client_group_id: Optional[int] = None
+    group_relationship: Optional[str] = None
+    is_group_head: Optional[bool] = None
     default_review_partner_user_id: Optional[int] = None
     referred_by_consultant_id: Optional[int] = None
     primary_consultant_id: Optional[int] = None
@@ -272,7 +278,7 @@ class ClientUpdate(BaseModel):
 
     @field_validator(
         "client_name", "trade_name", "cin_llpin", "msme_no", "iec_code", "contact_person_name", "contact_person_designation",
-        "address_line_1", "address_line_2", "city", "state", "country", "client_category", "risk_category", "referral_reference", "acceptance_review_notes", "acceptance_rejection_reason", "notes",
+        "address_line_1", "address_line_2", "city", "state", "country", "client_category", "risk_category", "referral_reference", "group_relationship", "acceptance_review_notes", "acceptance_rejection_reason", "notes",
         mode="before",
     )
     @classmethod

app/modules/clients/service.py

@@ -30,6 +30,8 @@ from app.modules.core.iam.models import User
 from app.modules.core.rbac.models import Role, UserRole
 from app.modules.documents.models import PermanentClientDocument
 from app.modules.consultants.service import sync_primary_client_consultant_link
+from app.modules.client_groups.service import get_group
+from app.modules.clients.models import Client
 
 
 
@@ -43,6 +45,26 @@ def _payload_from_schema(data):
 
 
 
+
+def _validate_client_group_assignment(db, *, payload: dict, existing_row=None):
+    group_id = payload.get("client_group_id")
+    tenant_id = payload.get("tenant_id") or getattr(existing_row, "tenant_id", None)
+    if group_id:
+        group = get_group(db, tenant_id=int(tenant_id), group_id=int(group_id))
+        if not group or not group.is_active:
+            raise HTTPException(status_code=400, detail="Selected client group is invalid or inactive for this firm.")
+    if payload.get("is_group_head") and group_id:
+        stmt = select(Client).where(Client.tenant_id == int(tenant_id), Client.client_group_id == int(group_id), Client.is_group_head.is_(True))
+        if existing_row is not None:
+            stmt = stmt.where(Client.id != existing_row.id)
+        existing_head = db.execute(stmt).scalar_one_or_none()
+        if existing_head:
+            raise HTTPException(status_code=400, detail=f"This group already has group head {existing_head.client_code} - {existing_head.client_name}.")
+    if not group_id:
+        payload["group_relationship"] = None
+        payload["is_group_head"] = False
+
+
 def _is_high_risk(risk_category: str | None) -> bool:
     return (risk_category or "").strip().lower() in CLIENT_ACCEPTANCE_APPROVAL_REQUIRED_RISKS
 
@@ -271,6 +293,7 @@ def create_client_service(db, *, data, actor_user_id: int, scope, current_user_r
 
     payload = _payload_from_schema(data)
     _enforce_client_acceptance_controls(payload)
+    _validate_client_group_assignment(db, payload=payload)
     row = repository.create_client(db, payload)
     row = _sync_client_portal_user(db, row=row, portal_password=portal_password, portal_password_confirm=portal_password_confirm)
     sync_primary_client_consultant_link(db, client=row, consultant_id=getattr(data, "primary_consultant_id", None), actor_user_id=actor_user_id)
@@ -301,6 +324,7 @@ def update_client_service(db, *, row, data, actor_user_id: int, scope, current_u
 
     payload = _payload_from_schema(data)
     _enforce_client_acceptance_controls(payload, existing_row=row)
+    _validate_client_group_assignment(db, payload=payload, existing_row=row)
 
     if payload.get("pan"):
         existing_pan = repository.get_client_by_pan(db, tenant_id=payload["tenant_id"], pan=payload["pan"])
@@ -441,6 +465,10 @@ def export_clients_csv(payload: dict) -> str:
             "pan",
             "gstin",
             "partner",
+            "client_group_code",
+            "client_group_name",
+            "group_relationship",
+            "is_group_head",
             "association_type",
             "association_source",
         ]
@@ -455,6 +483,10 @@ def export_clients_csv(payload: dict) -> str:
                 row.get("pan"),
                 row.get("gstin"),
                 row.get("partner_name") or row.get("effective_partner_id"),
+                row.get("client_group_code"),
+                row.get("client_group_name"),
+                row.get("group_relationship"),
+                row.get("is_group_head"),
                 row.get("association_type"),
                 row.get("assoc_created_source"),
             ]

app/modules/clients/templates/clients/detail.html

@@ -60,7 +60,8 @@
   </div>
   {% endif %}
 
-  <div class="grid gap-6 xl:grid-cols-3">
+  <div class="rounded-2xl border border-slate-200 bg-white p-5 shadow-soft"><div class="text-xs font-semibold uppercase tracking-wide text-slate-500">Client Group</div>{% if client_group %}<div class="mt-2 text-lg font-semibold text-slate-900"><a class="text-brand-700 hover:underline" href="/client-groups/{{ client_group.id }}">{{ client_group.group_name }}</a></div><div class="mt-1 text-sm text-slate-500">{{ client_group.group_code }} · {{ row.group_relationship or client_group.group_type }}{% if row.is_group_head %} · Group Head{% endif %}</div>{% else %}<div class="mt-2 text-sm text-slate-500">Not linked to a group.</div>{% endif %}</div>
+<div class="grid gap-6 xl:grid-cols-3">
     <section class="rounded-2xl bg-white p-6 shadow-soft xl:col-span-2">
       <h3 class="text-base font-semibold text-slate-900">Profile</h3>
       <div class="mt-4 grid gap-4 md:grid-cols-2">

app/modules/clients/templates/clients/list.html

@@ -7,7 +7,7 @@
       <p class="text-sm text-slate-500">Association-aware list view.</p>
     </div>
 
-    <div class="flex gap-3">
+    <div class="flex gap-3"><a href="/client-groups" class="inline-flex rounded-xl border border-slate-300 px-4 py-2 text-sm font-medium text-slate-700 hover:bg-slate-50">Client Groups</a>
       {% if can_export %}
       <a href="/clients/export?q={{ q }}&status={{ status }}&client_type={{ client_type }}&include_archived={{ include_archived }}&sort_by={{ sort_by }}&sort_order={{ sort_order }}"
          class="inline-flex rounded-xl border border-slate-300 px-4 py-2 text-sm font-medium text-slate-700 hover:bg-slate-50">

app/modules/clients/templates/clients/partials/form.html

@@ -162,7 +162,25 @@
     </div>
   </section>
 
-  <section class="rounded-2xl bg-white p-6 shadow-soft">
+  
+  <section class="rounded-2xl border border-slate-200 p-5 md:col-span-2">
+    <h3 class="text-sm font-semibold text-slate-900">Client Group / Family</h3>
+    <p class="mt-1 text-xs text-slate-500">Link this client to an existing family, promoter or related business group. Consultant access remains client-specific.</p>
+    <div class="mt-4 grid gap-4 md:grid-cols-3">
+      <label class="text-sm font-medium text-slate-700">Client Group
+        <select name="client_group_id" class="mt-1 w-full rounded-xl border border-slate-300 px-4 py-2 text-sm">
+          <option value="">-- No group --</option>
+          {% for g in form_options.client_groups or [] %}<option value="{{ g.id }}" {% if (form_data.client_group_id or (row.client_group_id if is_edit else None)) == g.id %}selected{% endif %}>{{ g.group_code }} — {{ g.group_name }}</option>{% endfor %}
+        </select>
+      </label>
+      <label class="text-sm font-medium text-slate-700">Relationship within group
+        <input name="group_relationship" value="{{ form_data.group_relationship or (row.group_relationship if is_edit else '') }}" placeholder="Spouse, HUF, Company, Trust..." class="mt-1 w-full rounded-xl border border-slate-300 px-4 py-2 text-sm">
+      </label>
+      <label class="mt-7 inline-flex items-center gap-2 text-sm font-medium text-slate-700"><input type="checkbox" name="is_group_head" {% if form_data.is_group_head or (is_edit and row.is_group_head) %}checked{% endif %}> Group head</label>
+    </div>
+    <div class="mt-3"><a href="/client-groups/new" class="text-sm font-medium text-brand-700 hover:underline">Create a new client group</a></div>
+  </section>
+<section class="rounded-2xl bg-white p-6 shadow-soft">
     <h3 class="text-base font-semibold text-slate-900">Assignment & Scope</h3>
     <div class="mt-4 space-y-4">
       <div>

app/modules/clients/templates/clients/partials/table.html

@@ -1,2 +1,2 @@
 
-<div class="overflow-hidden rounded-2xl bg-white shadow-soft"><table class="min-w-full divide-y divide-slate-200"><thead class="bg-slate-50"><tr><th class="px-4 py-3 text-left text-xs font-semibold uppercase tracking-wide text-slate-500">Code</th><th class="px-4 py-3 text-left text-xs font-semibold uppercase tracking-wide text-slate-500">Client</th><th class="px-4 py-3 text-left text-xs font-semibold uppercase tracking-wide text-slate-500">Association</th><th class="px-4 py-3 text-left text-xs font-semibold uppercase tracking-wide text-slate-500">Partner</th><th class="px-4 py-3 text-left text-xs font-semibold uppercase tracking-wide text-slate-500">Branch</th><th class="px-4 py-3 text-left text-xs font-semibold uppercase tracking-wide text-slate-500">Status</th><th class="px-4 py-3"></th></tr></thead><tbody class="divide-y divide-slate-100">{% for row in rows %}<tr><td class="px-4 py-3 text-sm font-medium text-slate-900">{{ row.client_code }}</td><td class="px-4 py-3 text-sm text-slate-700"><div class="font-medium">{{ row.client_name }}</div><div class="text-xs text-slate-500">{{ row.pan or row.gstin or '-' }}</div></td><td class="px-4 py-3 text-sm text-slate-700"><div>{{ row.association_type or 'legacy_firm' }}</div><div class="text-xs text-slate-500">{{ row.assoc_created_source or 'legacy' }}</div></td><td class="px-4 py-3 text-sm text-slate-700">{{ row.partner_name or row.effective_partner_id or '-' }}</td><td class="px-4 py-3 text-sm text-slate-700">{{ row.branch_name or row.assoc_firm_branch_id or row.branch_id or '-' }}</td><td class="px-4 py-3 text-sm">{% if row.status == 'active' %}<span class="rounded-full bg-emerald-100 px-2 py-1 text-xs font-medium text-emerald-700">Active</span>{% elif row.status == 'archived' %}<span class="rounded-full bg-amber-100 px-2 py-1 text-xs font-medium text-amber-800">Archived</span>{% else %}<span class="rounded-full bg-slate-200 px-2 py-1 text-xs font-medium text-slate-700">Inactive</span>{% endif %}</td><td class="px-4 py-3 text-right"><a href="/clients/{{ row.id }}" class="text-sm font-medium text-brand-700 hover:underline">Open</a></td></tr>{% else %}<tr><td colspan="7" class="px-4 py-8 text-center text-sm text-slate-500">No clients found.</td></tr>{% endfor %}</tbody></table></div>
+<div class="overflow-hidden rounded-2xl bg-white shadow-soft"><table class="min-w-full divide-y divide-slate-200"><thead class="bg-slate-50"><tr><th class="px-4 py-3 text-left text-xs font-semibold uppercase tracking-wide text-slate-500">Code</th><th class="px-4 py-3 text-left text-xs font-semibold uppercase tracking-wide text-slate-500">Client</th><th class="px-4 py-3 text-left text-xs font-semibold uppercase tracking-wide text-slate-500">Group</th><th class="px-4 py-3 text-left text-xs font-semibold uppercase tracking-wide text-slate-500">Association</th><th class="px-4 py-3 text-left text-xs font-semibold uppercase tracking-wide text-slate-500">Partner</th><th class="px-4 py-3 text-left text-xs font-semibold uppercase tracking-wide text-slate-500">Branch</th><th class="px-4 py-3 text-left text-xs font-semibold uppercase tracking-wide text-slate-500">Status</th><th class="px-4 py-3"></th></tr></thead><tbody class="divide-y divide-slate-100">{% for row in rows %}<tr><td class="px-4 py-3 text-sm font-medium text-slate-900">{{ row.client_code }}</td><td class="px-4 py-3 text-sm text-slate-700"><div class="font-medium">{{ row.client_name }}</div><div class="text-xs text-slate-500">{{ row.pan or row.gstin or '-' }}</div></td><td class="px-4 py-3 text-sm text-slate-700">{% if row.client_group_name %}<a href="/client-groups/{{ row.client_group_id }}" class="font-medium text-brand-700">{{ row.client_group_name }}</a><div class="text-xs text-slate-500">{{ row.group_relationship or row.client_group_code }}</div>{% else %}-{% endif %}</td><td class="px-4 py-3 text-sm text-slate-700"><div>{{ row.association_type or 'legacy_firm' }}</div><div class="text-xs text-slate-500">{{ row.assoc_created_source or 'legacy' }}</div></td><td class="px-4 py-3 text-sm text-slate-700">{{ row.partner_name or row.effective_partner_id or '-' }}</td><td class="px-4 py-3 text-sm text-slate-700">{{ row.branch_name or row.assoc_firm_branch_id or row.branch_id or '-' }}</td><td class="px-4 py-3 text-sm">{% if row.status == 'active' %}<span class="rounded-full bg-emerald-100 px-2 py-1 text-xs font-medium text-emerald-700">Active</span>{% elif row.status == 'archived' %}<span class="rounded-full bg-amber-100 px-2 py-1 text-xs font-medium text-amber-800">Archived</span>{% else %}<span class="rounded-full bg-slate-200 px-2 py-1 text-xs font-medium text-slate-700">Inactive</span>{% endif %}</td><td class="px-4 py-3 text-right"><a href="/clients/{{ row.id }}" class="text-sm font-medium text-brand-700 hover:underline">Open</a></td></tr>{% else %}<tr><td colspan="8" class="px-4 py-8 text-center text-sm text-slate-500">No clients found.</td></tr>{% endfor %}</tbody></table></div>

app/modules/clients/ui.py

@@ -55,6 +55,7 @@ from app.modules.core.rbac.deps import get_user_permissions, get_user_roles
 from app.modules.core.rbac.permission_guard import require_permission
 from app.modules.services.execution import list_client_visible_task_comments
 from app.modules.clients.auditor_service import build_client_auditor_card
+from app.modules.client_groups.service import get_group, list_groups
 from app.modules.clients.portal_service import (
     build_client_portal_summary,
     create_client_reply,
@@ -173,6 +174,9 @@ def _build_form_payload(request: Request, user, scope, *, include_client_code: b
         "tenant_id": tenant_id,
         "branch_id": branch_id,
         "partner_id": partner_id,
+        "client_group_id": int(form.get("client_group_id")) if form.get("client_group_id") not in (None, "", "None") else None,
+        "group_relationship": form.get("group_relationship"),
+        "is_group_head": _form_bool(form.get("is_group_head")),
         "default_review_partner_user_id": int(form.get("default_review_partner_user_id")) if form.get("default_review_partner_user_id") not in (None, "", "None") else None,
         "referred_by_consultant_id": int(form.get("referred_by_consultant_id")) if form.get("referred_by_consultant_id") not in (None, "", "None") else None,
         "primary_consultant_id": int(form.get("primary_consultant_id")) if form.get("primary_consultant_id") not in (None, "", "None") else None,
@@ -260,6 +264,7 @@ def _form_options(db, scope, form_mode: str):
             "active_tenant_id": tenant_id,
             "active_branch_id": branch_id,
             "consultants": list_consultants(db, tenant_id=tenant_id, include_inactive=False) if tenant_id else [],
+            "client_groups": [item["group"] for item in list_groups(db, tenant_id=tenant_id)] if tenant_id else [],
         }
 
     return {
@@ -271,6 +276,7 @@ def _form_options(db, scope, form_mode: str):
             branch_id=None if scope.allow_cross_branch else branch_id,
         ),
         "consultants": list_consultants(db, tenant_id=tenant_id, branch_id=branch_id, include_inactive=False),
+        "client_groups": [item["group"] for item in list_groups(db, tenant_id=tenant_id)],
         "review_partners": repository.list_partners_for_scope(
             db,
             tenant_id=tenant_id,
@@ -287,6 +293,7 @@ def clients_list(
     q: str = "",
     status: str = "",
     client_type: str = "",
+    client_group_id: int | None = None,
     partner_id: int | None = None,
     include_archived: bool = False,
     page: int = 1,
@@ -313,6 +320,7 @@ def clients_list(
             status=status,
             client_type=client_type,
             partner_id=partner_id,
+            client_group_id=client_group_id,
             include_archived=include_archived,
             page=page,
             per_page=per_page,
@@ -332,6 +340,7 @@ def clients_list(
             q=filters.q,
             status=filters.status,
             client_type=filters.client_type,
+            client_group_id=filters.client_group_id,
             include_archived=filters.include_archived,
             page=filters.page,
             per_page=filters.per_page,
@@ -354,6 +363,7 @@ def clients_list(
             status=filters.status,
             client_type=filters.client_type,
             partner_id=filters.partner_id,
+            client_group_id=filters.client_group_id,
             include_archived=filters.include_archived,
             page=filters.page,
             per_page=filters.per_page,
@@ -697,6 +707,7 @@ def client_detail(request: Request, client_id: int):
             can_archive=has("clients.archive"),
             can_restore=has("clients.restore"),
             consultant_summary=get_client_consultant_summary(db, tenant_id=int(row["tenant_id"]), client_id=client_id),
+            client_group=get_group(db, tenant_id=int(row["tenant_id"]), group_id=int(row["client_group_id"])) if row.get("client_group_id") else None,
             can_manage_acceptance=has("clients.acceptance.manage"),
             can_approve_acceptance=has("clients.acceptance.approve"),
         )