phase 3.2 & 4.1

backend/app/api/boards.py

@@ -0,0 +1,180 @@
+"""Board management API endpoints."""
+
+from typing import Annotated
+from uuid import UUID
+
+from fastapi import APIRouter, Depends, HTTPException, Query, status
+from sqlalchemy.orm import Session
+
+from app.boards.repository import BoardRepository
+from app.boards.schemas import BoardCreate, BoardDetail, BoardSummary, BoardUpdate
+from app.core.deps import get_current_user, get_db
+from app.database.models.user import User
+
+router = APIRouter(prefix="/boards", tags=["boards"])
+
+
+@router.post("", response_model=BoardDetail, status_code=status.HTTP_201_CREATED)
+def create_board(
+    board_data: BoardCreate,
+    current_user: Annotated[User, Depends(get_current_user)],
+    db: Annotated[Session, Depends(get_db)],
+):
+    """
+    Create a new board.
+
+    Args:
+        board_data: Board creation data
+        current_user: Current authenticated user
+        db: Database session
+
+    Returns:
+        Created board details
+    """
+    repo = BoardRepository(db)
+
+    board = repo.create_board(
+        user_id=current_user.id,
+        title=board_data.title,
+        description=board_data.description,
+    )
+
+    return BoardDetail.model_validate(board)
+
+
+@router.get("", response_model=dict)
+def list_boards(
+    current_user: Annotated[User, Depends(get_current_user)],
+    db: Annotated[Session, Depends(get_db)],
+    limit: Annotated[int, Query(ge=1, le=100)] = 50,
+    offset: Annotated[int, Query(ge=0)] = 0,
+):
+    """
+    List all boards for the current user.
+
+    Args:
+        current_user: Current authenticated user
+        db: Database session
+        limit: Maximum number of boards to return
+        offset: Number of boards to skip
+
+    Returns:
+        Dictionary with boards list, total count, limit, and offset
+    """
+    repo = BoardRepository(db)
+
+    boards, total = repo.get_user_boards(user_id=current_user.id, limit=limit, offset=offset)
+
+    return {
+        "boards": [BoardSummary.model_validate(board) for board in boards],
+        "total": total,
+        "limit": limit,
+        "offset": offset,
+    }
+
+
+@router.get("/{board_id}", response_model=BoardDetail)
+def get_board(
+    board_id: UUID,
+    current_user: Annotated[User, Depends(get_current_user)],
+    db: Annotated[Session, Depends(get_db)],
+):
+    """
+    Get board details by ID.
+
+    Args:
+        board_id: Board UUID
+        current_user: Current authenticated user
+        db: Database session
+
+    Returns:
+        Board details
+
+    Raises:
+        HTTPException: 404 if board not found or not owned by user
+    """
+    repo = BoardRepository(db)
+
+    board = repo.get_board_by_id(board_id=board_id, user_id=current_user.id)
+
+    if not board:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Board {board_id} not found",
+        )
+
+    return BoardDetail.model_validate(board)
+
+
+@router.patch("/{board_id}", response_model=BoardDetail)
+def update_board(
+    board_id: UUID,
+    board_data: BoardUpdate,
+    current_user: Annotated[User, Depends(get_current_user)],
+    db: Annotated[Session, Depends(get_db)],
+):
+    """
+    Update board metadata.
+
+    Args:
+        board_id: Board UUID
+        board_data: Board update data
+        current_user: Current authenticated user
+        db: Database session
+
+    Returns:
+        Updated board details
+
+    Raises:
+        HTTPException: 404 if board not found or not owned by user
+    """
+    repo = BoardRepository(db)
+
+    # Convert viewport_state to dict if provided
+    viewport_dict = None
+    if board_data.viewport_state:
+        viewport_dict = board_data.viewport_state.model_dump()
+
+    board = repo.update_board(
+        board_id=board_id,
+        user_id=current_user.id,
+        title=board_data.title,
+        description=board_data.description,
+        viewport_state=viewport_dict,
+    )
+
+    if not board:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Board {board_id} not found",
+        )
+
+    return BoardDetail.model_validate(board)
+
+
+@router.delete("/{board_id}", status_code=status.HTTP_204_NO_CONTENT)
+def delete_board(
+    board_id: UUID,
+    current_user: Annotated[User, Depends(get_current_user)],
+    db: Annotated[Session, Depends(get_db)],
+):
+    """
+    Delete a board (soft delete).
+
+    Args:
+        board_id: Board UUID
+        current_user: Current authenticated user
+        db: Database session
+
+    Raises:
+        HTTPException: 404 if board not found or not owned by user
+    """
+    repo = BoardRepository(db)
+
+    success = repo.delete_board(board_id=board_id, user_id=current_user.id)
+
+    if not success:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Board {board_id} not found",
+        )

backend/app/boards/__init__.py

@@ -0,0 +1 @@
+"""Boards module for board management."""

backend/app/boards/permissions.py

@@ -0,0 +1,29 @@
+"""Permission validation middleware for boards."""
+
+from uuid import UUID
+
+from fastapi import HTTPException, status
+from sqlalchemy.orm import Session
+
+from app.boards.repository import BoardRepository
+
+
+def validate_board_ownership(board_id: UUID, user_id: UUID, db: Session) -> None:
+    """
+    Validate that the user owns the board.
+
+    Args:
+        board_id: Board UUID
+        user_id: User UUID
+        db: Database session
+
+    Raises:
+        HTTPException: 404 if board not found or not owned by user
+    """
+    repo = BoardRepository(db)
+
+    if not repo.board_exists(board_id, user_id):
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Board {board_id} not found or access denied",
+        )

backend/app/boards/repository.py

@@ -0,0 +1,197 @@
+"""Board repository for database operations."""
+
+from collections.abc import Sequence
+from uuid import UUID
+
+from sqlalchemy import func, select
+from sqlalchemy.orm import Session
+
+from app.database.models.board import Board
+from app.database.models.board_image import BoardImage
+
+
+class BoardRepository:
+    """Repository for Board database operations."""
+
+    def __init__(self, db: Session):
+        """
+        Initialize repository with database session.
+
+        Args:
+            db: SQLAlchemy database session
+        """
+        self.db = db
+
+    def create_board(
+        self,
+        user_id: UUID,
+        title: str,
+        description: str | None = None,
+        viewport_state: dict | None = None,
+    ) -> Board:
+        """
+        Create a new board.
+
+        Args:
+            user_id: Owner's user ID
+            title: Board title
+            description: Optional board description
+            viewport_state: Optional custom viewport state
+
+        Returns:
+            Created Board instance
+        """
+        if viewport_state is None:
+            viewport_state = {"x": 0, "y": 0, "zoom": 1.0, "rotation": 0}
+
+        board = Board(
+            user_id=user_id,
+            title=title,
+            description=description,
+            viewport_state=viewport_state,
+        )
+
+        self.db.add(board)
+        self.db.commit()
+        self.db.refresh(board)
+
+        return board
+
+    def get_board_by_id(self, board_id: UUID, user_id: UUID) -> Board | None:
+        """
+        Get board by ID for a specific user.
+
+        Args:
+            board_id: Board UUID
+            user_id: User UUID (for ownership check)
+
+        Returns:
+            Board if found and owned by user, None otherwise
+        """
+        stmt = select(Board).where(
+            Board.id == board_id,
+            Board.user_id == user_id,
+            Board.is_deleted == False,  # noqa: E712
+        )
+
+        return self.db.execute(stmt).scalar_one_or_none()
+
+    def get_user_boards(
+        self,
+        user_id: UUID,
+        limit: int = 50,
+        offset: int = 0,
+    ) -> tuple[Sequence[Board], int]:
+        """
+        Get all boards for a user with pagination.
+
+        Args:
+            user_id: User UUID
+            limit: Maximum number of boards to return
+            offset: Number of boards to skip
+
+        Returns:
+            Tuple of (list of boards, total count)
+        """
+        # Query for boards with image count
+        stmt = (
+            select(Board, func.count(BoardImage.id).label("image_count"))
+            .outerjoin(BoardImage, Board.id == BoardImage.board_id)
+            .where(Board.user_id == user_id, Board.is_deleted == False)  # noqa: E712
+            .group_by(Board.id)
+            .order_by(Board.updated_at.desc())
+            .limit(limit)
+            .offset(offset)
+        )
+
+        results = self.db.execute(stmt).all()
+        boards = [row[0] for row in results]
+
+        # Get total count
+        count_stmt = select(func.count(Board.id)).where(Board.user_id == user_id, Board.is_deleted == False)  # noqa: E712
+
+        total = self.db.execute(count_stmt).scalar_one()
+
+        return boards, total
+
+    def update_board(
+        self,
+        board_id: UUID,
+        user_id: UUID,
+        title: str | None = None,
+        description: str | None = None,
+        viewport_state: dict | None = None,
+    ) -> Board | None:
+        """
+        Update board metadata.
+
+        Args:
+            board_id: Board UUID
+            user_id: User UUID (for ownership check)
+            title: New title (if provided)
+            description: New description (if provided)
+            viewport_state: New viewport state (if provided)
+
+        Returns:
+            Updated Board if found and owned by user, None otherwise
+        """
+        board = self.get_board_by_id(board_id, user_id)
+
+        if not board:
+            return None
+
+        if title is not None:
+            board.title = title
+
+        if description is not None:
+            board.description = description
+
+        if viewport_state is not None:
+            board.viewport_state = viewport_state
+
+        self.db.commit()
+        self.db.refresh(board)
+
+        return board
+
+    def delete_board(self, board_id: UUID, user_id: UUID) -> bool:
+        """
+        Soft delete a board.
+
+        Args:
+            board_id: Board UUID
+            user_id: User UUID (for ownership check)
+
+        Returns:
+            True if deleted, False if not found or not owned
+        """
+        board = self.get_board_by_id(board_id, user_id)
+
+        if not board:
+            return False
+
+        board.is_deleted = True
+        self.db.commit()
+
+        return True
+
+    def board_exists(self, board_id: UUID, user_id: UUID) -> bool:
+        """
+        Check if board exists and is owned by user.
+
+        Args:
+            board_id: Board UUID
+            user_id: User UUID
+
+        Returns:
+            True if board exists and is owned by user
+        """
+        stmt = select(func.count(Board.id)).where(
+            Board.id == board_id,
+            Board.user_id == user_id,
+            Board.is_deleted == False,  # noqa: E712
+        )
+
+        count = self.db.execute(stmt).scalar_one()
+
+        return count > 0

backend/app/boards/schemas.py

@@ -0,0 +1,67 @@
+"""Board Pydantic schemas for request/response validation."""
+
+from datetime import datetime
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+
+class ViewportState(BaseModel):
+    """Viewport state for canvas position and zoom."""
+
+    x: float = Field(default=0, description="Horizontal pan position")
+    y: float = Field(default=0, description="Vertical pan position")
+    zoom: float = Field(default=1.0, ge=0.1, le=5.0, description="Zoom level (0.1 to 5.0)")
+    rotation: float = Field(default=0, ge=0, le=360, description="Canvas rotation in degrees (0 to 360)")
+
+
+class BoardCreate(BaseModel):
+    """Schema for creating a new board."""
+
+    title: str = Field(..., min_length=1, max_length=255, description="Board title")
+    description: str | None = Field(default=None, description="Optional board description")
+
+
+class BoardUpdate(BaseModel):
+    """Schema for updating board metadata."""
+
+    title: str | None = Field(None, min_length=1, max_length=255, description="Board title")
+    description: str | None = Field(None, description="Board description")
+    viewport_state: ViewportState | None = Field(None, description="Viewport state")
+
+
+class BoardSummary(BaseModel):
+    """Summary schema for board list view."""
+
+    model_config = ConfigDict(from_attributes=True)
+
+    id: UUID
+    title: str
+    description: str | None = None
+    image_count: int = Field(default=0, description="Number of images on board")
+    thumbnail_url: str | None = Field(default=None, description="URL to board thumbnail")
+    created_at: datetime
+    updated_at: datetime
+
+
+class BoardDetail(BaseModel):
+    """Detailed schema for single board view with all data."""
+
+    model_config = ConfigDict(from_attributes=True)
+
+    id: UUID
+    user_id: UUID
+    title: str
+    description: str | None = None
+    viewport_state: ViewportState
+    created_at: datetime
+    updated_at: datetime
+    is_deleted: bool = False
+
+    @field_validator("viewport_state", mode="before")
+    @classmethod
+    def convert_viewport_state(cls, v):
+        """Convert dict to ViewportState if needed."""
+        if isinstance(v, dict):
+            return ViewportState(**v)
+        return v

backend/app/database/models/board.py

@@ -1,35 +1,62 @@
-"""Board model for reference boards."""
+"""Board database model."""
 
-import uuid
 from datetime import datetime
+from typing import TYPE_CHECKING
+from uuid import UUID, uuid4
 
-from sqlalchemy import Boolean, Column, DateTime, ForeignKey, String, Text
-from sqlalchemy.dialects.postgresql import JSONB, UUID
-from sqlalchemy.orm import relationship
+from sqlalchemy import Boolean, DateTime, ForeignKey, String, Text
+from sqlalchemy.dialects.postgresql import JSONB
+from sqlalchemy.dialects.postgresql import UUID as PGUUID
+from sqlalchemy.orm import Mapped, mapped_column, relationship
 
 from app.database.base import Base
 
+if TYPE_CHECKING:
+    from app.database.models.board_image import BoardImage
+    from app.database.models.group import Group
+    from app.database.models.share_link import ShareLink
+    from app.database.models.user import User
+
 
 class Board(Base):
-    """Board model representing a reference board."""
+    """
+    Board model representing a reference board (canvas) containing images.
+
+    A board is owned by a user and contains images arranged on an infinite canvas
+    with a specific viewport state (zoom, pan, rotation).
+    """
 
     __tablename__ = "boards"
 
-    id = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
-    user_id = Column(UUID(as_uuid=True), ForeignKey("users.id", ondelete="CASCADE"), nullable=False, index=True)
-    title = Column(String(255), nullable=False)
-    description = Column(Text, nullable=True)
-    viewport_state = Column(JSONB, nullable=False, default={"x": 0, "y": 0, "zoom": 1.0, "rotation": 0})
-    created_at = Column(DateTime, nullable=False, default=datetime.utcnow)
-    updated_at = Column(DateTime, nullable=False, default=datetime.utcnow, onupdate=datetime.utcnow)
-    is_deleted = Column(Boolean, nullable=False, default=False)
+    id: Mapped[UUID] = mapped_column(PGUUID(as_uuid=True), primary_key=True, default=uuid4)
+    user_id: Mapped[UUID] = mapped_column(
+        PGUUID(as_uuid=True), ForeignKey("users.id", ondelete="CASCADE"), nullable=False
+    )
+    title: Mapped[str] = mapped_column(String(255), nullable=False)
+    description: Mapped[str | None] = mapped_column(Text, nullable=True)
+
+    viewport_state: Mapped[dict] = mapped_column(
+        JSONB,
+        nullable=False,
+        default=lambda: {"x": 0, "y": 0, "zoom": 1.0, "rotation": 0},
+    )
+
+    created_at: Mapped[datetime] = mapped_column(DateTime, nullable=False, default=datetime.utcnow)
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime, nullable=False, default=datetime.utcnow, onupdate=datetime.utcnow
+    )
+    is_deleted: Mapped[bool] = mapped_column(Boolean, nullable=False, default=False)
 
     # Relationships
-    user = relationship("User", back_populates="boards")
-    board_images = relationship("BoardImage", back_populates="board", cascade="all, delete-orphan")
-    groups = relationship("Group", back_populates="board", cascade="all, delete-orphan")
-    share_links = relationship("ShareLink", back_populates="board", cascade="all, delete-orphan")
-    comments = relationship("Comment", back_populates="board", cascade="all, delete-orphan")
+    user: Mapped["User"] = relationship("User", back_populates="boards")
+    board_images: Mapped[list["BoardImage"]] = relationship(
+        "BoardImage", back_populates="board", cascade="all, delete-orphan"
+    )
+    groups: Mapped[list["Group"]] = relationship("Group", back_populates="board", cascade="all, delete-orphan")
+    share_links: Mapped[list["ShareLink"]] = relationship(
+        "ShareLink", back_populates="board", cascade="all, delete-orphan"
+    )
 
     def __repr__(self) -> str:
-        return f"<Board(id={self.id}, title={self.title})>"
+        """String representation of Board."""
+        return f"<Board(id={self.id}, title='{self.title}', user_id={self.user_id})>"

backend/app/database/models/board_image.py

@@ -1,28 +1,44 @@
-"""BoardImage junction model."""
+"""BoardImage database model - junction table for boards and images."""
 
-import uuid
 from datetime import datetime
+from typing import TYPE_CHECKING
+from uuid import UUID, uuid4
 
-from sqlalchemy import Column, DateTime, ForeignKey, Integer, UniqueConstraint
-from sqlalchemy.dialects.postgresql import JSONB, UUID
-from sqlalchemy.orm import relationship
+from sqlalchemy import DateTime, ForeignKey, Integer
+from sqlalchemy.dialects.postgresql import JSONB
+from sqlalchemy.dialects.postgresql import UUID as PGUUID
+from sqlalchemy.orm import Mapped, mapped_column, relationship
 
 from app.database.base import Base
 
+if TYPE_CHECKING:
+    from app.database.models.board import Board
+    from app.database.models.group import Group
+    from app.database.models.image import Image
+
 
 class BoardImage(Base):
-    """Junction table connecting boards and images with position/transformation data."""
+    """
+    BoardImage model - junction table connecting boards and images.
+
+    Stores position, transformations, and z-order for each image on a board.
+    """
 
     __tablename__ = "board_images"
 
-    id = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
-    board_id = Column(UUID(as_uuid=True), ForeignKey("boards.id", ondelete="CASCADE"), nullable=False, index=True)
-    image_id = Column(UUID(as_uuid=True), ForeignKey("images.id", ondelete="CASCADE"), nullable=False, index=True)
-    position = Column(JSONB, nullable=False)
-    transformations = Column(
+    id: Mapped[UUID] = mapped_column(PGUUID(as_uuid=True), primary_key=True, default=uuid4)
+    board_id: Mapped[UUID] = mapped_column(
+        PGUUID(as_uuid=True), ForeignKey("boards.id", ondelete="CASCADE"), nullable=False
+    )
+    image_id: Mapped[UUID] = mapped_column(
+        PGUUID(as_uuid=True), ForeignKey("images.id", ondelete="CASCADE"), nullable=False
+    )
+
+    position: Mapped[dict] = mapped_column(JSONB, nullable=False)
+    transformations: Mapped[dict] = mapped_column(
         JSONB,
         nullable=False,
-        default={
+        default=lambda: {
             "scale": 1.0,
             "rotation": 0,
             "opacity": 1.0,
@@ -31,17 +47,21 @@ class BoardImage(Base):
             "greyscale": False,
         },
     )
-    z_order = Column(Integer, nullable=False, default=0, index=True)
-    group_id = Column(UUID(as_uuid=True), ForeignKey("groups.id", ondelete="SET NULL"), nullable=True, index=True)
-    created_at = Column(DateTime, nullable=False, default=datetime.utcnow)
-    updated_at = Column(DateTime, nullable=False, default=datetime.utcnow, onupdate=datetime.utcnow)
+    z_order: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
+    group_id: Mapped[UUID | None] = mapped_column(
+        PGUUID(as_uuid=True), ForeignKey("groups.id", ondelete="SET NULL"), nullable=True
+    )
 
-    __table_args__ = (UniqueConstraint("board_id", "image_id", name="uq_board_image"),)
+    created_at: Mapped[datetime] = mapped_column(DateTime, nullable=False, default=datetime.utcnow)
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime, nullable=False, default=datetime.utcnow, onupdate=datetime.utcnow
+    )
 
     # Relationships
-    board = relationship("Board", back_populates="board_images")
-    image = relationship("Image", back_populates="board_images")
-    group = relationship("Group", back_populates="board_images")
+    board: Mapped["Board"] = relationship("Board", back_populates="board_images")
+    image: Mapped["Image"] = relationship("Image", back_populates="board_images")
+    group: Mapped["Group | None"] = relationship("Group", back_populates="board_images")
 
     def __repr__(self) -> str:
-        return f"<BoardImage(board_id={self.board_id}, image_id={self.image_id})>"
+        """String representation of BoardImage."""
+        return f"<BoardImage(id={self.id}, board_id={self.board_id}, image_id={self.image_id})>"

backend/app/database/models/group.py

@@ -1,31 +1,47 @@
-"""Group model for image grouping."""
+"""Group database model."""
 
-import uuid
 from datetime import datetime
+from typing import TYPE_CHECKING
+from uuid import UUID, uuid4
 
-from sqlalchemy import Column, DateTime, ForeignKey, String, Text
-from sqlalchemy.dialects.postgresql import UUID
-from sqlalchemy.orm import relationship
+from sqlalchemy import DateTime, ForeignKey, String, Text
+from sqlalchemy.dialects.postgresql import UUID as PGUUID
+from sqlalchemy.orm import Mapped, mapped_column, relationship
 
 from app.database.base import Base
 
+if TYPE_CHECKING:
+    from app.database.models.board import Board
+    from app.database.models.board_image import BoardImage
+
 
 class Group(Base):
-    """Group model for organizing images with annotations."""
+    """
+    Group model for organizing images with labels and annotations.
+
+    Groups contain multiple images that can be moved together and have
+    shared visual indicators (color, annotation text).
+    """
 
     __tablename__ = "groups"
 
-    id = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
-    board_id = Column(UUID(as_uuid=True), ForeignKey("boards.id", ondelete="CASCADE"), nullable=False, index=True)
-    name = Column(String(255), nullable=False)
-    color = Column(String(7), nullable=False)  # Hex color #RRGGBB
-    annotation = Column(Text, nullable=True)
-    created_at = Column(DateTime, nullable=False, default=datetime.utcnow)
-    updated_at = Column(DateTime, nullable=False, default=datetime.utcnow, onupdate=datetime.utcnow)
+    id: Mapped[UUID] = mapped_column(PGUUID(as_uuid=True), primary_key=True, default=uuid4)
+    board_id: Mapped[UUID] = mapped_column(
+        PGUUID(as_uuid=True), ForeignKey("boards.id", ondelete="CASCADE"), nullable=False
+    )
+    name: Mapped[str] = mapped_column(String(255), nullable=False)
+    color: Mapped[str] = mapped_column(String(7), nullable=False)  # Hex color #RRGGBB
+    annotation: Mapped[str | None] = mapped_column(Text, nullable=True)
+
+    created_at: Mapped[datetime] = mapped_column(DateTime, nullable=False, default=datetime.utcnow)
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime, nullable=False, default=datetime.utcnow, onupdate=datetime.utcnow
+    )
 
     # Relationships
-    board = relationship("Board", back_populates="groups")
-    board_images = relationship("BoardImage", back_populates="group")
+    board: Mapped["Board"] = relationship("Board", back_populates="groups")
+    board_images: Mapped[list["BoardImage"]] = relationship("BoardImage", back_populates="group")
 
     def __repr__(self) -> str:
-        return f"<Group(id={self.id}, name={self.name})>"
+        """String representation of Group."""
+        return f"<Group(id={self.id}, name='{self.name}', board_id={self.board_id})>"

backend/app/database/models/image.py

@@ -1,35 +1,52 @@
-"""Image model for uploaded images."""
+"""Image database model."""
 
-import uuid
 from datetime import datetime
+from typing import TYPE_CHECKING
+from uuid import UUID, uuid4
 
-from sqlalchemy import BigInteger, Column, DateTime, ForeignKey, Integer, String
-from sqlalchemy.dialects.postgresql import JSONB, UUID
-from sqlalchemy.orm import relationship
+from sqlalchemy import BigInteger, DateTime, ForeignKey, Integer, String
+from sqlalchemy.dialects.postgresql import JSONB
+from sqlalchemy.dialects.postgresql import UUID as PGUUID
+from sqlalchemy.orm import Mapped, mapped_column, relationship
 
 from app.database.base import Base
 
+if TYPE_CHECKING:
+    from app.database.models.board_image import BoardImage
+    from app.database.models.user import User
+
 
 class Image(Base):
-    """Image model representing uploaded image files."""
+    """
+    Image model representing uploaded image files.
+
+    Images are stored in MinIO and can be reused across multiple boards.
+    Reference counting tracks how many boards use each image.
+    """
 
     __tablename__ = "images"
 
-    id = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
-    user_id = Column(UUID(as_uuid=True), ForeignKey("users.id", ondelete="CASCADE"), nullable=False, index=True)
-    filename = Column(String(255), nullable=False, index=True)
-    storage_path = Column(String(512), nullable=False)
-    file_size = Column(BigInteger, nullable=False)
-    mime_type = Column(String(100), nullable=False)
-    width = Column(Integer, nullable=False)
-    height = Column(Integer, nullable=False)
-    image_metadata = Column(JSONB, nullable=False)
-    created_at = Column(DateTime, nullable=False, default=datetime.utcnow)
-    reference_count = Column(Integer, nullable=False, default=0)
+    id: Mapped[UUID] = mapped_column(PGUUID(as_uuid=True), primary_key=True, default=uuid4)
+    user_id: Mapped[UUID] = mapped_column(
+        PGUUID(as_uuid=True), ForeignKey("users.id", ondelete="CASCADE"), nullable=False
+    )
+    filename: Mapped[str] = mapped_column(String(255), nullable=False)
+    storage_path: Mapped[str] = mapped_column(String(512), nullable=False)
+    file_size: Mapped[int] = mapped_column(BigInteger, nullable=False)
+    mime_type: Mapped[str] = mapped_column(String(100), nullable=False)
+    width: Mapped[int] = mapped_column(Integer, nullable=False)
+    height: Mapped[int] = mapped_column(Integer, nullable=False)
+    metadata: Mapped[dict] = mapped_column(JSONB, nullable=False)
+
+    created_at: Mapped[datetime] = mapped_column(DateTime, nullable=False, default=datetime.utcnow)
+    reference_count: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
 
     # Relationships
-    user = relationship("User", back_populates="images")
-    board_images = relationship("BoardImage", back_populates="image", cascade="all, delete-orphan")
+    user: Mapped["User"] = relationship("User", back_populates="images")
+    board_images: Mapped[list["BoardImage"]] = relationship(
+        "BoardImage", back_populates="image", cascade="all, delete-orphan"
+    )
 
     def __repr__(self) -> str:
-        return f"<Image(id={self.id}, filename={self.filename})>"
+        """String representation of Image."""
+        return f"<Image(id={self.id}, filename='{self.filename}', user_id={self.user_id})>"

backend/app/database/models/share_link.py

@@ -1,33 +1,45 @@
-"""ShareLink model for board sharing."""
+"""ShareLink database model."""
 
-import uuid
 from datetime import datetime
+from typing import TYPE_CHECKING
+from uuid import UUID, uuid4
 
-from sqlalchemy import Boolean, Column, DateTime, ForeignKey, Integer, String
-from sqlalchemy.dialects.postgresql import UUID
-from sqlalchemy.orm import relationship
+from sqlalchemy import Boolean, DateTime, ForeignKey, Integer, String
+from sqlalchemy.dialects.postgresql import UUID as PGUUID
+from sqlalchemy.orm import Mapped, mapped_column, relationship
 
 from app.database.base import Base
 
+if TYPE_CHECKING:
+    from app.database.models.board import Board
+
 
 class ShareLink(Base):
-    """ShareLink model for sharing boards with permission control."""
+    """
+    ShareLink model for sharing boards with configurable permissions.
+
+    Share links allow users to share boards with others without requiring
+    authentication, with permission levels controlling what actions are allowed.
+    """
 
     __tablename__ = "share_links"
 
-    id = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
-    board_id = Column(UUID(as_uuid=True), ForeignKey("boards.id", ondelete="CASCADE"), nullable=False, index=True)
-    token = Column(String(64), unique=True, nullable=False, index=True)
-    permission_level = Column(String(20), nullable=False)  # 'view-only' or 'view-comment'
-    created_at = Column(DateTime, nullable=False, default=datetime.utcnow)
-    expires_at = Column(DateTime, nullable=True)
-    last_accessed_at = Column(DateTime, nullable=True)
-    access_count = Column(Integer, nullable=False, default=0)
-    is_revoked = Column(Boolean, nullable=False, default=False, index=True)
+    id: Mapped[UUID] = mapped_column(PGUUID(as_uuid=True), primary_key=True, default=uuid4)
+    board_id: Mapped[UUID] = mapped_column(
+        PGUUID(as_uuid=True), ForeignKey("boards.id", ondelete="CASCADE"), nullable=False
+    )
+    token: Mapped[str] = mapped_column(String(64), unique=True, nullable=False, index=True)
+    permission_level: Mapped[str] = mapped_column(String(20), nullable=False)  # 'view-only' or 'view-comment'
+
+    created_at: Mapped[datetime] = mapped_column(DateTime, nullable=False, default=datetime.utcnow)
+    expires_at: Mapped[datetime | None] = mapped_column(DateTime, nullable=True)
+    last_accessed_at: Mapped[datetime | None] = mapped_column(DateTime, nullable=True)
+    access_count: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
+    is_revoked: Mapped[bool] = mapped_column(Boolean, nullable=False, default=False)
 
     # Relationships
-    board = relationship("Board", back_populates="share_links")
-    comments = relationship("Comment", back_populates="share_link")
+    board: Mapped["Board"] = relationship("Board", back_populates="share_links")
 
     def __repr__(self) -> str:
-        return f"<ShareLink(id={self.id}, token={self.token[:8]}...)>"
+        """String representation of ShareLink."""
+        return f"<ShareLink(id={self.id}, token={self.token[:8]}..., board_id={self.board_id})>"

backend/app/main.py

@@ -5,7 +5,7 @@ import logging
 from fastapi import FastAPI, Request
 from fastapi.responses import JSONResponse
 
-from app.api import auth
+from app.api import auth, boards
 from app.core.config import settings
 from app.core.errors import WebRefException
 from app.core.logging import setup_logging
@@ -83,9 +83,9 @@ async def root():
 
 # API routers
 app.include_router(auth.router, prefix=f"{settings.API_V1_PREFIX}")
+app.include_router(boards.router, prefix=f"{settings.API_V1_PREFIX}")
 # Additional routers will be added in subsequent phases
-# from app.api import boards, images
-# app.include_router(boards.router, prefix=f"{settings.API_V1_PREFIX}")
+# from app.api import images
 # app.include_router(images.router, prefix=f"{settings.API_V1_PREFIX}")