refactor: update module docstrings for clarity and consistency

backend/app/models/__init__.py

@@ -1,3 +1,5 @@
+"""Model exports for SQLAlchemy/SQLModel metadata discovery."""
+
 from app.models.activity_events import ActivityEvent
 from app.models.agents import Agent
 from app.models.approvals import Approval

backend/app/models/activity_events.py

@@ -1,6 +1,8 @@
+"""Activity event model persisted for audit and feed use-cases."""
+
 from __future__ import annotations
 
-from datetime import datetime
+from datetime import datetime  # noqa: TCH003
 from uuid import UUID, uuid4
 
 from sqlmodel import Field
@@ -10,6 +12,8 @@ from app.models.base import QueryModel
 
 
 class ActivityEvent(QueryModel, table=True):
+    """Discrete activity event tied to tasks and agents."""
+
     __tablename__ = "activity_events"
 
     id: UUID = Field(default_factory=uuid4, primary_key=True)

backend/app/models/agents.py

@@ -1,6 +1,8 @@
+"""Agent model representing autonomous actors assigned to boards."""
+
 from __future__ import annotations
 
-from datetime import datetime
+from datetime import datetime  # noqa: TCH003
 from typing import Any
 from uuid import UUID, uuid4
 
@@ -12,6 +14,8 @@ from app.models.base import QueryModel
 
 
 class Agent(QueryModel, table=True):
+    """Agent configuration and lifecycle state persisted in the database."""
+
     __tablename__ = "agents"
 
     id: UUID = Field(default_factory=uuid4, primary_key=True)
@@ -20,8 +24,14 @@ class Agent(QueryModel, table=True):
     status: str = Field(default="provisioning", index=True)
     openclaw_session_id: str | None = Field(default=None, index=True)
     agent_token_hash: str | None = Field(default=None, index=True)
-    heartbeat_config: dict[str, Any] | None = Field(default=None, sa_column=Column(JSON))
-    identity_profile: dict[str, Any] | None = Field(default=None, sa_column=Column(JSON))
+    heartbeat_config: dict[str, Any] | None = Field(
+        default=None,
+        sa_column=Column(JSON),
+    )
+    identity_profile: dict[str, Any] | None = Field(
+        default=None,
+        sa_column=Column(JSON),
+    )
     identity_template: str | None = Field(default=None, sa_column=Column(Text))
     soul_template: str | None = Field(default=None, sa_column=Column(Text))
     provision_requested_at: datetime | None = Field(default=None)

backend/app/models/approvals.py

@@ -1,6 +1,8 @@
+"""Approval model storing pending and resolved approval actions."""
+
 from __future__ import annotations
 
-from datetime import datetime
+from datetime import datetime  # noqa: TCH003
 from uuid import UUID, uuid4
 
 from sqlalchemy import JSON, Column
@@ -11,6 +13,8 @@ from app.models.base import QueryModel
 
 
 class Approval(QueryModel, table=True):
+    """Approval request and decision metadata for gated operations."""
+
     __tablename__ = "approvals"
 
     id: UUID = Field(default_factory=uuid4, primary_key=True)

backend/app/models/base.py

@@ -1,3 +1,5 @@
+"""Base model mixins and shared SQLModel abstractions."""
+
 from __future__ import annotations
 
 from typing import ClassVar, Self
@@ -8,4 +10,6 @@ from app.db.query_manager import ManagerDescriptor
 
 
 class QueryModel(SQLModel, table=False):
+    """Base SQLModel with a shared query manager descriptor."""
+
     objects: ClassVar[ManagerDescriptor[Self]] = ManagerDescriptor()

backend/app/models/board_group_memory.py

@@ -1,6 +1,8 @@
+"""Board-group scoped memory entries for shared context."""
+
 from __future__ import annotations
 
-from datetime import datetime
+from datetime import datetime  # noqa: TCH003
 from uuid import UUID, uuid4
 
 from sqlalchemy import JSON, Column
@@ -11,6 +13,8 @@ from app.models.base import QueryModel
 
 
 class BoardGroupMemory(QueryModel, table=True):
+    """Persisted memory items associated with a board group."""
+
     __tablename__ = "board_group_memory"
 
     id: UUID = Field(default_factory=uuid4, primary_key=True)

backend/app/models/board_groups.py

@@ -1,6 +1,8 @@
+"""Board group model used to organize boards inside organizations."""
+
 from __future__ import annotations
 
-from datetime import datetime
+from datetime import datetime  # noqa: TCH003
 from uuid import UUID, uuid4
 
 from sqlmodel import Field
@@ -10,6 +12,8 @@ from app.models.tenancy import TenantScoped
 
 
 class BoardGroup(TenantScoped, table=True):
+    """Logical grouping container for boards within an organization."""
+
     __tablename__ = "board_groups"
 
     id: UUID = Field(default_factory=uuid4, primary_key=True)

backend/app/models/board_memory.py

@@ -1,6 +1,8 @@
+"""Board-level memory entries for persistent contextual state."""
+
 from __future__ import annotations
 
-from datetime import datetime
+from datetime import datetime  # noqa: TCH003
 from uuid import UUID, uuid4
 
 from sqlalchemy import JSON, Column
@@ -11,6 +13,8 @@ from app.models.base import QueryModel
 
 
 class BoardMemory(QueryModel, table=True):
+    """Persisted memory item attached directly to a board."""
+
     __tablename__ = "board_memory"
 
     id: UUID = Field(default_factory=uuid4, primary_key=True)

backend/app/models/board_onboarding.py

@@ -1,6 +1,8 @@
+"""Board onboarding session model for guided setup state."""
+
 from __future__ import annotations
 
-from datetime import datetime
+from datetime import datetime  # noqa: TCH003
 from uuid import UUID, uuid4
 
 from sqlalchemy import JSON, Column
@@ -11,13 +13,18 @@ from app.models.base import QueryModel
 
 
 class BoardOnboardingSession(QueryModel, table=True):
+    """Persisted onboarding conversation and draft goal data for a board."""
+
     __tablename__ = "board_onboarding_sessions"
 
     id: UUID = Field(default_factory=uuid4, primary_key=True)
     board_id: UUID = Field(foreign_key="boards.id", index=True)
     session_key: str
     status: str = Field(default="active", index=True)
-    messages: list[dict[str, object]] | None = Field(default=None, sa_column=Column(JSON))
+    messages: list[dict[str, object]] | None = Field(
+        default=None,
+        sa_column=Column(JSON),
+    )
     draft_goal: dict[str, object] | None = Field(default=None, sa_column=Column(JSON))
     created_at: datetime = Field(default_factory=utcnow)
     updated_at: datetime = Field(default_factory=utcnow)

backend/app/models/boards.py

@@ -1,6 +1,8 @@
+"""Board model for organization workspaces and goal configuration."""
+
 from __future__ import annotations
 
-from datetime import datetime
+from datetime import datetime  # noqa: TCH003
 from uuid import UUID, uuid4
 
 from sqlalchemy import JSON, Column
@@ -11,6 +13,8 @@ from app.models.tenancy import TenantScoped
 
 
 class Board(TenantScoped, table=True):
+    """Primary board entity grouping tasks, agents, and goal metadata."""
+
     __tablename__ = "boards"
 
     id: UUID = Field(default_factory=uuid4, primary_key=True)
@@ -18,10 +22,17 @@ class Board(TenantScoped, table=True):
     name: str
     slug: str = Field(index=True)
     gateway_id: UUID | None = Field(default=None, foreign_key="gateways.id", index=True)
-    board_group_id: UUID | None = Field(default=None, foreign_key="board_groups.id", index=True)
+    board_group_id: UUID | None = Field(
+        default=None,
+        foreign_key="board_groups.id",
+        index=True,
+    )
     board_type: str = Field(default="goal", index=True)
     objective: str | None = None
-    success_metrics: dict[str, object] | None = Field(default=None, sa_column=Column(JSON))
+    success_metrics: dict[str, object] | None = Field(
+        default=None,
+        sa_column=Column(JSON),
+    )
     target_date: datetime | None = None
     goal_confirmed: bool = Field(default=False)
     goal_source: str | None = None

backend/app/models/gateways.py

@@ -1,6 +1,8 @@
+"""Gateway model storing organization-level gateway integration metadata."""
+
 from __future__ import annotations
 
-from datetime import datetime
+from datetime import datetime  # noqa: TCH003
 from uuid import UUID, uuid4
 
 from sqlmodel import Field
@@ -10,6 +12,8 @@ from app.models.base import QueryModel
 
 
 class Gateway(QueryModel, table=True):
+    """Configured external gateway endpoint and authentication settings."""
+
     __tablename__ = "gateways"
 
     id: UUID = Field(default_factory=uuid4, primary_key=True)

backend/app/models/organization_board_access.py

@@ -1,6 +1,8 @@
+"""Board-level access grants assigned to organization members."""
+
 from __future__ import annotations
 
-from datetime import datetime
+from datetime import datetime  # noqa: TCH003
 from uuid import UUID, uuid4
 
 from sqlalchemy import UniqueConstraint
@@ -11,6 +13,8 @@ from app.models.base import QueryModel
 
 
 class OrganizationBoardAccess(QueryModel, table=True):
+    """Member-specific board permissions within an organization."""
+
     __tablename__ = "organization_board_access"
     __table_args__ = (
         UniqueConstraint(
@@ -21,7 +25,10 @@ class OrganizationBoardAccess(QueryModel, table=True):
     )
 
     id: UUID = Field(default_factory=uuid4, primary_key=True)
-    organization_member_id: UUID = Field(foreign_key="organization_members.id", index=True)
+    organization_member_id: UUID = Field(
+        foreign_key="organization_members.id",
+        index=True,
+    )
     board_id: UUID = Field(foreign_key="boards.id", index=True)
     can_read: bool = Field(default=True)
     can_write: bool = Field(default=False)

backend/app/models/organization_invite_board_access.py

@@ -1,6 +1,8 @@
+"""Board access grants attached to pending organization invites."""
+
 from __future__ import annotations
 
-from datetime import datetime
+from datetime import datetime  # noqa: TCH003
 from uuid import UUID, uuid4
 
 from sqlalchemy import UniqueConstraint
@@ -11,6 +13,8 @@ from app.models.base import QueryModel
 
 
 class OrganizationInviteBoardAccess(QueryModel, table=True):
+    """Invite-specific board permissions applied after invite acceptance."""
+
     __tablename__ = "organization_invite_board_access"
     __table_args__ = (
         UniqueConstraint(
@@ -21,7 +25,10 @@ class OrganizationInviteBoardAccess(QueryModel, table=True):
     )
 
     id: UUID = Field(default_factory=uuid4, primary_key=True)
-    organization_invite_id: UUID = Field(foreign_key="organization_invites.id", index=True)
+    organization_invite_id: UUID = Field(
+        foreign_key="organization_invites.id",
+        index=True,
+    )
     board_id: UUID = Field(foreign_key="boards.id", index=True)
     can_read: bool = Field(default=True)
     can_write: bool = Field(default=False)

backend/app/models/organization_invites.py

@@ -1,6 +1,8 @@
+"""Organization invite model for email-based tenant membership flow."""
+
 from __future__ import annotations
 
-from datetime import datetime
+from datetime import datetime  # noqa: TCH003
 from uuid import UUID, uuid4
 
 from sqlalchemy import UniqueConstraint
@@ -11,6 +13,8 @@ from app.models.base import QueryModel
 
 
 class OrganizationInvite(QueryModel, table=True):
+    """Invitation record granting prospective organization access."""
+
     __tablename__ = "organization_invites"
     __table_args__ = (UniqueConstraint("token", name="uq_org_invites_token"),)
 
@@ -21,8 +25,16 @@ class OrganizationInvite(QueryModel, table=True):
     role: str = Field(default="member", index=True)
     all_boards_read: bool = Field(default=False)
     all_boards_write: bool = Field(default=False)
-    created_by_user_id: UUID | None = Field(default=None, foreign_key="users.id", index=True)
-    accepted_by_user_id: UUID | None = Field(default=None, foreign_key="users.id", index=True)
+    created_by_user_id: UUID | None = Field(
+        default=None,
+        foreign_key="users.id",
+        index=True,
+    )
+    accepted_by_user_id: UUID | None = Field(
+        default=None,
+        foreign_key="users.id",
+        index=True,
+    )
     accepted_at: datetime | None = None
     created_at: datetime = Field(default_factory=utcnow)
     updated_at: datetime = Field(default_factory=utcnow)

backend/app/models/organization_members.py

@@ -1,6 +1,8 @@
+"""Organization membership model with role and board-access flags."""
+
 from __future__ import annotations
 
-from datetime import datetime
+from datetime import datetime  # noqa: TCH003
 from uuid import UUID, uuid4
 
 from sqlalchemy import UniqueConstraint
@@ -11,6 +13,8 @@ from app.models.base import QueryModel
 
 
 class OrganizationMember(QueryModel, table=True):
+    """Membership row linking a user to an organization and permissions."""
+
     __tablename__ = "organization_members"
     __table_args__ = (
         UniqueConstraint(

backend/app/models/organizations.py

@@ -1,6 +1,8 @@
+"""Organization model representing top-level tenant entities."""
+
 from __future__ import annotations
 
-from datetime import datetime
+from datetime import datetime  # noqa: TCH003
 from uuid import UUID, uuid4
 
 from sqlalchemy import UniqueConstraint
@@ -11,6 +13,8 @@ from app.models.base import QueryModel
 
 
 class Organization(QueryModel, table=True):
+    """Top-level organization tenant record."""
+
     __tablename__ = "organizations"
     __table_args__ = (UniqueConstraint("name", name="uq_organizations_name"),)
 

backend/app/models/task_dependencies.py

@@ -1,6 +1,8 @@
+"""Task dependency edge model for board-local dependency graphs."""
+
 from __future__ import annotations
 
-from datetime import datetime
+from datetime import datetime  # noqa: TCH003
 from uuid import UUID, uuid4
 
 from sqlalchemy import CheckConstraint, UniqueConstraint
@@ -11,6 +13,8 @@ from app.models.tenancy import TenantScoped
 
 
 class TaskDependency(TenantScoped, table=True):
+    """Directed dependency edge between two tasks in the same board."""
+
     __tablename__ = "task_dependencies"
     __table_args__ = (
         UniqueConstraint(

backend/app/models/task_fingerprints.py

@@ -1,6 +1,8 @@
+"""Task fingerprint model for duplicate/task-linking operations."""
+
 from __future__ import annotations
 
-from datetime import datetime
+from datetime import datetime  # noqa: TCH003
 from uuid import UUID, uuid4
 
 from sqlmodel import Field
@@ -10,6 +12,8 @@ from app.models.base import QueryModel
 
 
 class TaskFingerprint(QueryModel, table=True):
+    """Hashed task-content fingerprint associated with a board and task."""
+
     __tablename__ = "task_fingerprints"
 
     id: UUID = Field(default_factory=uuid4, primary_key=True)

backend/app/models/tasks.py

@@ -1,6 +1,8 @@
+"""Task model representing board work items and execution metadata."""
+
 from __future__ import annotations
 
-from datetime import datetime
+from datetime import datetime  # noqa: TCH003
 from uuid import UUID, uuid4
 
 from sqlmodel import Field
@@ -10,6 +12,8 @@ from app.models.tenancy import TenantScoped
 
 
 class Task(TenantScoped, table=True):
+    """Board-scoped task entity with ownership, status, and timing fields."""
+
     __tablename__ = "tasks"
 
     id: UUID = Field(default_factory=uuid4, primary_key=True)
@@ -22,8 +26,16 @@ class Task(TenantScoped, table=True):
     due_at: datetime | None = None
     in_progress_at: datetime | None = None
 
-    created_by_user_id: UUID | None = Field(default=None, foreign_key="users.id", index=True)
-    assigned_agent_id: UUID | None = Field(default=None, foreign_key="agents.id", index=True)
+    created_by_user_id: UUID | None = Field(
+        default=None,
+        foreign_key="users.id",
+        index=True,
+    )
+    assigned_agent_id: UUID | None = Field(
+        default=None,
+        foreign_key="agents.id",
+        index=True,
+    )
     auto_created: bool = Field(default=False)
     auto_reason: str | None = None
 

backend/app/models/tenancy.py

@@ -1,7 +1,9 @@
+"""Shared tenancy-scoped model base classes."""
+
 from __future__ import annotations
 
 from app.models.base import QueryModel
 
 
 class TenantScoped(QueryModel, table=False):
-    pass
+    """Base class for models constrained to a tenant/organization scope."""

backend/app/models/users.py

@@ -1,3 +1,5 @@
+"""User model storing identity and profile preferences."""
+
 from __future__ import annotations
 
 from uuid import UUID, uuid4
@@ -8,6 +10,8 @@ from app.models.base import QueryModel
 
 
 class User(QueryModel, table=True):
+    """Application user account and profile attributes."""
+
     __tablename__ = "users"
 
     id: UUID = Field(default_factory=uuid4, primary_key=True)
@@ -21,5 +25,7 @@ class User(QueryModel, table=True):
     context: str | None = None
     is_super_admin: bool = Field(default=False)
     active_organization_id: UUID | None = Field(
-        default=None, foreign_key="organizations.id", index=True
+        default=None,
+        foreign_key="organizations.id",
+        index=True,
     )