refactor: update module docstrings for clarity and consistency

backend/app/api/boards.py

@@ -1,12 +1,14 @@
+"""Board CRUD and snapshot endpoints."""
+
 from __future__ import annotations
 
 import re
+from typing import TYPE_CHECKING
 from uuid import UUID, uuid4
 
 from fastapi import APIRouter, Depends, HTTPException, Query, status
 from sqlalchemy import func
 from sqlmodel import col, select
-from sqlmodel.ext.asyncio.session import AsyncSession
 
 from app.api.deps import (
     get_board_for_actor_read,
@@ -47,9 +49,23 @@ from app.services.board_group_snapshot import build_board_group_snapshot
 from app.services.board_snapshot import build_board_snapshot
 from app.services.organizations import OrganizationContext, board_access_filter
 
+if TYPE_CHECKING:
+    from sqlmodel.ext.asyncio.session import AsyncSession
+
 router = APIRouter(prefix="/boards", tags=["boards"])
 
 AGENT_SESSION_PREFIX = "agent"
+SESSION_DEP = Depends(get_session)
+ORG_ADMIN_DEP = Depends(require_org_admin)
+ORG_MEMBER_DEP = Depends(require_org_member)
+BOARD_USER_READ_DEP = Depends(get_board_for_user_read)
+BOARD_USER_WRITE_DEP = Depends(get_board_for_user_write)
+BOARD_ACTOR_READ_DEP = Depends(get_board_for_actor_read)
+GATEWAY_ID_QUERY = Query(default=None)
+BOARD_GROUP_ID_QUERY = Query(default=None)
+INCLUDE_SELF_QUERY = Query(default=False)
+INCLUDE_DONE_QUERY = Query(default=False)
+PER_BOARD_TASK_LIMIT_QUERY = Query(default=5, ge=0, le=100)
 
 
 def _slugify(value: str) -> str:
@@ -83,10 +99,12 @@ async def _require_gateway(
 
 async def _require_gateway_for_create(
     payload: BoardCreate,
-    ctx: OrganizationContext = Depends(require_org_admin),
-    session: AsyncSession = Depends(get_session),
+    ctx: OrganizationContext = ORG_ADMIN_DEP,
+    session: AsyncSession = SESSION_DEP,
 ) -> Gateway:
-    return await _require_gateway(session, payload.gateway_id, organization_id=ctx.organization.id)
+    return await _require_gateway(
+        session, payload.gateway_id, organization_id=ctx.organization.id,
+    )
 
 
 async def _require_board_group(
@@ -111,8 +129,8 @@ async def _require_board_group(
 
 async def _require_board_group_for_create(
     payload: BoardCreate,
-    ctx: OrganizationContext = Depends(require_org_admin),
-    session: AsyncSession = Depends(get_session),
+    ctx: OrganizationContext = ORG_ADMIN_DEP,
+    session: AsyncSession = SESSION_DEP,
 ) -> BoardGroup | None:
     if payload.board_group_id is None:
         return None
@@ -123,6 +141,10 @@ async def _require_board_group_for_create(
     )
 
 
+GATEWAY_CREATE_DEP = Depends(_require_gateway_for_create)
+BOARD_GROUP_CREATE_DEP = Depends(_require_board_group_for_create)
+
+
 async def _apply_board_update(
     *,
     payload: BoardUpdate,
@@ -132,7 +154,7 @@ async def _apply_board_update(
     updates = payload.model_dump(exclude_unset=True)
     if "gateway_id" in updates:
         await _require_gateway(
-            session, updates["gateway_id"], organization_id=board.organization_id
+            session, updates["gateway_id"], organization_id=board.organization_id,
         )
     if "board_group_id" in updates and updates["board_group_id"] is not None:
         await _require_board_group(
@@ -141,13 +163,15 @@ async def _apply_board_update(
             organization_id=board.organization_id,
         )
     crud.apply_updates(board, updates)
-    if updates.get("board_type") == "goal":
+    if (
+        updates.get("board_type") == "goal"
+        and (not board.objective or not board.success_metrics)
+    ):
         # Validate only when explicitly switching to goal boards.
-        if not board.objective or not board.success_metrics:
-            raise HTTPException(
-                status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
-                detail="Goal boards require objective and success_metrics",
-            )
+        raise HTTPException(
+            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+            detail="Goal boards require objective and success_metrics",
+        )
     if not board.gateway_id:
         raise HTTPException(
             status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
@@ -158,7 +182,7 @@ async def _apply_board_update(
 
 
 async def _board_gateway(
-    session: AsyncSession, board: Board
+    session: AsyncSession, board: Board,
 ) -> tuple[Gateway | None, GatewayClientConfig | None]:
     if not board.gateway_id:
         return None, None
@@ -218,28 +242,32 @@ async def _cleanup_agent_on_gateway(
 
 @router.get("", response_model=DefaultLimitOffsetPage[BoardRead])
 async def list_boards(
-    gateway_id: UUID | None = Query(default=None),
-    board_group_id: UUID | None = Query(default=None),
-    session: AsyncSession = Depends(get_session),
-    ctx: OrganizationContext = Depends(require_org_member),
+    gateway_id: UUID | None = GATEWAY_ID_QUERY,
+    board_group_id: UUID | None = BOARD_GROUP_ID_QUERY,
+    session: AsyncSession = SESSION_DEP,
+    ctx: OrganizationContext = ORG_MEMBER_DEP,
 ) -> DefaultLimitOffsetPage[BoardRead]:
+    """List boards visible to the current organization member."""
     statement = select(Board).where(board_access_filter(ctx.member, write=False))
     if gateway_id is not None:
         statement = statement.where(col(Board.gateway_id) == gateway_id)
     if board_group_id is not None:
         statement = statement.where(col(Board.board_group_id) == board_group_id)
-    statement = statement.order_by(func.lower(col(Board.name)).asc(), col(Board.created_at).desc())
+    statement = statement.order_by(
+        func.lower(col(Board.name)).asc(), col(Board.created_at).desc(),
+    )
     return await paginate(session, statement)
 
 
 @router.post("", response_model=BoardRead)
 async def create_board(
     payload: BoardCreate,
-    _gateway: Gateway = Depends(_require_gateway_for_create),
-    _board_group: BoardGroup | None = Depends(_require_board_group_for_create),
-    session: AsyncSession = Depends(get_session),
-    ctx: OrganizationContext = Depends(require_org_admin),
+    _gateway: Gateway = GATEWAY_CREATE_DEP,
+    _board_group: BoardGroup | None = BOARD_GROUP_CREATE_DEP,
+    session: AsyncSession = SESSION_DEP,
+    ctx: OrganizationContext = ORG_ADMIN_DEP,
 ) -> Board:
+    """Create a board in the active organization."""
     data = payload.model_dump()
     data["organization_id"] = ctx.organization.id
     return await crud.create(session, Board, **data)
@@ -247,27 +275,31 @@ async def create_board(
 
 @router.get("/{board_id}", response_model=BoardRead)
 def get_board(
-    board: Board = Depends(get_board_for_user_read),
+    board: Board = BOARD_USER_READ_DEP,
 ) -> Board:
+    """Get a board by id."""
     return board
 
 
 @router.get("/{board_id}/snapshot", response_model=BoardSnapshot)
 async def get_board_snapshot(
-    board: Board = Depends(get_board_for_actor_read),
-    session: AsyncSession = Depends(get_session),
+    board: Board = BOARD_ACTOR_READ_DEP,
+    session: AsyncSession = SESSION_DEP,
 ) -> BoardSnapshot:
+    """Get a board snapshot view model."""
     return await build_board_snapshot(session, board)
 
 
 @router.get("/{board_id}/group-snapshot", response_model=BoardGroupSnapshot)
 async def get_board_group_snapshot(
-    include_self: bool = Query(default=False),
-    include_done: bool = Query(default=False),
-    per_board_task_limit: int = Query(default=5, ge=0, le=100),
-    board: Board = Depends(get_board_for_actor_read),
-    session: AsyncSession = Depends(get_session),
+    *,
+    include_self: bool = INCLUDE_SELF_QUERY,
+    include_done: bool = INCLUDE_DONE_QUERY,
+    per_board_task_limit: int = PER_BOARD_TASK_LIMIT_QUERY,
+    board: Board = BOARD_ACTOR_READ_DEP,
+    session: AsyncSession = SESSION_DEP,
 ) -> BoardGroupSnapshot:
+    """Get a grouped snapshot across related boards."""
     return await build_board_group_snapshot(
         session,
         board=board,
@@ -280,19 +312,23 @@ async def get_board_group_snapshot(
 @router.patch("/{board_id}", response_model=BoardRead)
 async def update_board(
     payload: BoardUpdate,
-    session: AsyncSession = Depends(get_session),
-    board: Board = Depends(get_board_for_user_write),
+    session: AsyncSession = SESSION_DEP,
+    board: Board = BOARD_USER_WRITE_DEP,
 ) -> Board:
+    """Update mutable board properties."""
     return await _apply_board_update(payload=payload, session=session, board=board)
 
 
 @router.delete("/{board_id}", response_model=OkResponse)
 async def delete_board(
-    session: AsyncSession = Depends(get_session),
-    board: Board = Depends(get_board_for_user_write),
+    session: AsyncSession = SESSION_DEP,
+    board: Board = BOARD_USER_WRITE_DEP,
 ) -> OkResponse:
+    """Delete a board and all dependent records."""
     agents = await Agent.objects.filter_by(board_id=board.id).all(session)
-    task_ids = list(await session.exec(select(Task.id).where(Task.board_id == board.id)))
+    task_ids = list(
+        await session.exec(select(Task.id).where(Task.board_id == board.id)),
+    )
 
     config, client_config = await _board_gateway(session, board)
     if config and client_config:
@@ -307,20 +343,31 @@ async def delete_board(
 
     if task_ids:
         await crud.delete_where(
-            session, ActivityEvent, col(ActivityEvent.task_id).in_(task_ids), commit=False
+            session,
+            ActivityEvent,
+            col(ActivityEvent.task_id).in_(task_ids),
+            commit=False,
         )
-    await crud.delete_where(session, TaskDependency, col(TaskDependency.board_id) == board.id)
-    await crud.delete_where(session, TaskFingerprint, col(TaskFingerprint.board_id) == board.id)
+    await crud.delete_where(
+        session, TaskDependency, col(TaskDependency.board_id) == board.id,
+    )
+    await crud.delete_where(
+        session, TaskFingerprint, col(TaskFingerprint.board_id) == board.id,
+    )
 
     # Approvals can reference tasks and agents, so delete before both.
     await crud.delete_where(session, Approval, col(Approval.board_id) == board.id)
 
     await crud.delete_where(session, BoardMemory, col(BoardMemory.board_id) == board.id)
     await crud.delete_where(
-        session, BoardOnboardingSession, col(BoardOnboardingSession.board_id) == board.id
+        session,
+        BoardOnboardingSession,
+        col(BoardOnboardingSession.board_id) == board.id,
     )
     await crud.delete_where(
-        session, OrganizationBoardAccess, col(OrganizationBoardAccess.board_id) == board.id
+        session,
+        OrganizationBoardAccess,
+        col(OrganizationBoardAccess.board_id) == board.id,
     )
     await crud.delete_where(
         session,
@@ -328,14 +375,17 @@ async def delete_board(
         col(OrganizationInviteBoardAccess.board_id) == board.id,
     )
 
-    # Tasks reference agents (assigned_agent_id) and have dependents (fingerprints/dependencies), so
+    # Tasks reference agents and have dependent records.
     # delete tasks before agents.
     await crud.delete_where(session, Task, col(Task.board_id) == board.id)
 
     if agents:
         agent_ids = [agent.id for agent in agents]
         await crud.delete_where(
-            session, ActivityEvent, col(ActivityEvent.agent_id).in_(agent_ids), commit=False
+            session,
+            ActivityEvent,
+            col(ActivityEvent.agent_id).in_(agent_ids),
+            commit=False,
         )
         await crud.delete_where(session, Agent, col(Agent.id).in_(agent_ids))
     await session.delete(board)