refactor: update module docstrings for clarity and consistency

backend/app/schemas/organizations.py

@@ -1,12 +1,16 @@
+"""Schemas for organization, membership, and invite API payloads."""
+
 from __future__ import annotations
 
-from datetime import datetime
-from uuid import UUID
+from datetime import datetime  # noqa: TCH003
+from uuid import UUID  # noqa: TCH003
 
 from sqlmodel import Field, SQLModel
 
 
 class OrganizationRead(SQLModel):
+    """Organization payload returned by read endpoints."""
+
     id: UUID
     name: str
     created_at: datetime
@@ -14,14 +18,20 @@ class OrganizationRead(SQLModel):
 
 
 class OrganizationCreate(SQLModel):
+    """Payload for creating a new organization."""
+
     name: str
 
 
 class OrganizationActiveUpdate(SQLModel):
+    """Payload for switching the active organization context."""
+
     organization_id: UUID
 
 
 class OrganizationListItem(SQLModel):
+    """Organization list row for current user memberships."""
+
     id: UUID
     name: str
     role: str
@@ -29,6 +39,8 @@ class OrganizationListItem(SQLModel):
 
 
 class OrganizationUserRead(SQLModel):
+    """Embedded user fields included in organization member payloads."""
+
     id: UUID
     email: str | None = None
     name: str | None = None
@@ -36,6 +48,8 @@ class OrganizationUserRead(SQLModel):
 
 
 class OrganizationMemberRead(SQLModel):
+    """Organization member payload including board-level access overrides."""
+
     id: UUID
     organization_id: UUID
     user_id: UUID
@@ -49,16 +63,22 @@ class OrganizationMemberRead(SQLModel):
 
 
 class OrganizationMemberUpdate(SQLModel):
+    """Payload for partial updates to organization member role."""
+
     role: str | None = None
 
 
 class OrganizationBoardAccessSpec(SQLModel):
+    """Board access specification used in member/invite mutation payloads."""
+
     board_id: UUID
     can_read: bool = True
     can_write: bool = False
 
 
 class OrganizationBoardAccessRead(SQLModel):
+    """Board access payload returned from read endpoints."""
+
     id: UUID
     board_id: UUID
     can_read: bool
@@ -68,12 +88,16 @@ class OrganizationBoardAccessRead(SQLModel):
 
 
 class OrganizationMemberAccessUpdate(SQLModel):
+    """Payload for replacing organization member access permissions."""
+
     all_boards_read: bool = False
     all_boards_write: bool = False
     board_access: list[OrganizationBoardAccessSpec] = Field(default_factory=list)
 
 
 class OrganizationInviteCreate(SQLModel):
+    """Payload for creating an organization invite."""
+
     invited_email: str
     role: str = "member"
     all_boards_read: bool = False
@@ -82,6 +106,8 @@ class OrganizationInviteCreate(SQLModel):
 
 
 class OrganizationInviteRead(SQLModel):
+    """Organization invite payload returned from read endpoints."""
+
     id: UUID
     organization_id: UUID
     invited_email: str
@@ -97,4 +123,6 @@ class OrganizationInviteRead(SQLModel):
 
 
 class OrganizationInviteAccept(SQLModel):
+    """Payload for accepting an organization invite token."""
+
     token: str