Add tree organization system with categories, tags, and folders

Features:
- Categories: Global and team-specific tree categorization (admin-managed)
- Tags: Flexible tree tagging with autocomplete (author + admin)
- User folders: Personal tree collections with subfolder support
  - Hierarchical structure (max 3 levels deep)
  - Right-click context menu for folder management
  - Cascade delete for subfolders
- Filter trees by category, tags, and folder in library view

Backend:
- New models: Category, Tag, UserFolder with relationships
- New API endpoints for categories, tags, and folders
- Tree organization migrations (005, 006)

Frontend:
- FolderSidebar with hierarchical folder tree
- FolderEditModal for create/edit with color picker
- AddToFolderMenu for quick tree organization
- TagInput with autocomplete and TagBadges display
- Updated TreeMetadataForm and TreeLibraryPage

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

backend/app/models/__init__.py

@@ -4,5 +4,20 @@ from .tree import Tree
 from .session import Session
 from .attachment import Attachment
 from .invite_code import InviteCode
+from .category import TreeCategory
+from .tag import TreeTag, tree_tag_assignments
+from .folder import UserFolder, user_folder_trees
 
-__all__ = ["User", "Team", "Tree", "Session", "Attachment", "InviteCode"]
+__all__ = [
+    "User",
+    "Team",
+    "Tree",
+    "Session",
+    "Attachment",
+    "InviteCode",
+    "TreeCategory",
+    "TreeTag",
+    "tree_tag_assignments",
+    "UserFolder",
+    "user_folder_trees",
+]

backend/app/models/category.py

@@ -0,0 +1,66 @@
+import uuid
+from datetime import datetime, timezone
+from typing import Optional, TYPE_CHECKING
+from sqlalchemy import String, Text, DateTime, ForeignKey, Boolean, Integer, UniqueConstraint
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+from sqlalchemy.dialects.postgresql import UUID
+from app.core.database import Base
+
+if TYPE_CHECKING:
+    from app.models.tree import Tree
+    from app.models.team import Team
+    from app.models.user import User
+
+
+class TreeCategory(Base):
+    """Admin-managed categories for organizing trees.
+
+    Categories can be:
+    - Global (team_id=NULL): Created by Patherly admins, visible to all
+    - Team-specific (team_id set): Created by team admins, visible to team members
+    """
+    __tablename__ = "tree_categories"
+    __table_args__ = (
+        UniqueConstraint('slug', 'team_id', name='uq_tree_categories_slug_team'),
+    )
+
+    id: Mapped[uuid.UUID] = mapped_column(
+        UUID(as_uuid=True),
+        primary_key=True,
+        default=uuid.uuid4
+    )
+    name: Mapped[str] = mapped_column(String(100), nullable=False)
+    slug: Mapped[str] = mapped_column(String(100), nullable=False, index=True)
+    description: Mapped[Optional[str]] = mapped_column(Text, nullable=True)
+    team_id: Mapped[Optional[uuid.UUID]] = mapped_column(
+        UUID(as_uuid=True),
+        ForeignKey("teams.id", ondelete="CASCADE"),
+        nullable=True,
+        index=True
+    )
+    display_order: Mapped[int] = mapped_column(Integer, nullable=False, default=0, index=True)
+    is_active: Mapped[bool] = mapped_column(Boolean, nullable=False, default=True)
+    created_by: Mapped[Optional[uuid.UUID]] = mapped_column(
+        UUID(as_uuid=True),
+        ForeignKey("users.id", ondelete="SET NULL"),
+        nullable=True
+    )
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        default=lambda: datetime.now(timezone.utc)
+    )
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        default=lambda: datetime.now(timezone.utc),
+        onupdate=lambda: datetime.now(timezone.utc)
+    )
+
+    # Relationships
+    team: Mapped[Optional["Team"]] = relationship("Team", back_populates="categories")
+    creator: Mapped[Optional["User"]] = relationship("User", foreign_keys=[created_by])
+    trees: Mapped[list["Tree"]] = relationship("Tree", back_populates="category_rel")
+
+    @property
+    def is_global(self) -> bool:
+        """Returns True if this is a global category (not team-specific)."""
+        return self.team_id is None

backend/app/models/folder.py

@@ -0,0 +1,93 @@
+import uuid
+from datetime import datetime, timezone
+from typing import TYPE_CHECKING, Optional
+from sqlalchemy import String, DateTime, ForeignKey, Integer, UniqueConstraint, Table, Column
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+from sqlalchemy.dialects.postgresql import UUID
+from app.core.database import Base
+
+if TYPE_CHECKING:
+    from app.models.tree import Tree
+    from app.models.user import User
+
+
+# Junction table for folder-tree many-to-many relationship
+user_folder_trees = Table(
+    'user_folder_trees',
+    Base.metadata,
+    Column('folder_id', UUID(as_uuid=True), ForeignKey('user_folders.id', ondelete='CASCADE'), primary_key=True),
+    Column('tree_id', UUID(as_uuid=True), ForeignKey('trees.id', ondelete='CASCADE'), primary_key=True),
+    Column('added_at', DateTime(timezone=True), nullable=False, default=lambda: datetime.now(timezone.utc)),
+    Column('display_order', Integer, nullable=False, default=0)
+)
+
+
+class UserFolder(Base):
+    """User-specific folders for organizing trees.
+
+    - Each folder belongs to a single user
+    - Trees can be in multiple folders (like labels/tags)
+    - Folders are purely organizational - they don't affect tree visibility or permissions
+    """
+    __tablename__ = "user_folders"
+    __table_args__ = (
+        # Allow same name under different parents
+        UniqueConstraint('user_id', 'name', 'parent_id', name='uq_user_folders_user_name_parent'),
+    )
+
+    id: Mapped[uuid.UUID] = mapped_column(
+        UUID(as_uuid=True),
+        primary_key=True,
+        default=uuid.uuid4
+    )
+    user_id: Mapped[uuid.UUID] = mapped_column(
+        UUID(as_uuid=True),
+        ForeignKey("users.id", ondelete="CASCADE"),
+        nullable=False,
+        index=True
+    )
+    name: Mapped[str] = mapped_column(String(100), nullable=False)
+    color: Mapped[str] = mapped_column(String(7), nullable=False, default="#6366f1")
+    icon: Mapped[str] = mapped_column(String(50), nullable=False, default="folder")
+    display_order: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
+    parent_id: Mapped[Optional[uuid.UUID]] = mapped_column(
+        UUID(as_uuid=True),
+        ForeignKey("user_folders.id", ondelete="CASCADE"),
+        nullable=True,
+        index=True
+    )
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        default=lambda: datetime.now(timezone.utc)
+    )
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        default=lambda: datetime.now(timezone.utc),
+        onupdate=lambda: datetime.now(timezone.utc)
+    )
+
+    # Relationships
+    user: Mapped["User"] = relationship("User", back_populates="folders")
+    trees: Mapped[list["Tree"]] = relationship(
+        "Tree",
+        secondary=user_folder_trees,
+        back_populates="folders"
+    )
+    # Self-referential relationships for folder hierarchy
+    parent: Mapped[Optional["UserFolder"]] = relationship(
+        "UserFolder",
+        remote_side="UserFolder.id",
+        back_populates="children",
+        foreign_keys=[parent_id]
+    )
+    children: Mapped[list["UserFolder"]] = relationship(
+        "UserFolder",
+        back_populates="parent",
+        cascade="all, delete-orphan",
+        foreign_keys="UserFolder.parent_id"
+    )
+
+    @property
+    def tree_count(self) -> int:
+        """Returns the number of trees in this folder."""
+        return len(self.trees) if self.trees else 0

backend/app/models/tag.py

@@ -0,0 +1,86 @@
+import uuid
+from datetime import datetime, timezone
+from typing import Optional, TYPE_CHECKING
+from sqlalchemy import String, DateTime, ForeignKey, Integer, UniqueConstraint, Table, Column
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+from sqlalchemy.dialects.postgresql import UUID
+from app.core.database import Base
+
+if TYPE_CHECKING:
+    from app.models.tree import Tree
+    from app.models.team import Team
+    from app.models.user import User
+
+
+# Junction table for tree-tag many-to-many relationship
+tree_tag_assignments = Table(
+    'tree_tag_assignments',
+    Base.metadata,
+    Column('tree_id', UUID(as_uuid=True), ForeignKey('trees.id', ondelete='CASCADE'), primary_key=True),
+    Column('tag_id', UUID(as_uuid=True), ForeignKey('tree_tags.id', ondelete='CASCADE'), primary_key=True),
+    Column('assigned_by', UUID(as_uuid=True), ForeignKey('users.id', ondelete='SET NULL'), nullable=True),
+    Column('assigned_at', DateTime(timezone=True), nullable=False, default=lambda: datetime.now(timezone.utc))
+)
+
+
+class TreeTag(Base):
+    """Tags for categorizing and filtering trees.
+
+    Tags can be:
+    - Global (team_id=NULL): Available to all users
+    - Team-specific (team_id set): Only visible to team members
+
+    Tags are managed by tree authors and admins (global or team).
+    """
+    __tablename__ = "tree_tags"
+    __table_args__ = (
+        UniqueConstraint('slug', 'team_id', name='uq_tree_tags_slug_team'),
+    )
+
+    id: Mapped[uuid.UUID] = mapped_column(
+        UUID(as_uuid=True),
+        primary_key=True,
+        default=uuid.uuid4
+    )
+    name: Mapped[str] = mapped_column(String(50), nullable=False)
+    slug: Mapped[str] = mapped_column(String(50), nullable=False, index=True)
+    team_id: Mapped[Optional[uuid.UUID]] = mapped_column(
+        UUID(as_uuid=True),
+        ForeignKey("teams.id", ondelete="CASCADE"),
+        nullable=True,
+        index=True
+    )
+    usage_count: Mapped[int] = mapped_column(Integer, nullable=False, default=0, index=True)
+    created_by: Mapped[Optional[uuid.UUID]] = mapped_column(
+        UUID(as_uuid=True),
+        ForeignKey("users.id", ondelete="SET NULL"),
+        nullable=True
+    )
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        default=lambda: datetime.now(timezone.utc)
+    )
+
+    # Relationships
+    team: Mapped[Optional["Team"]] = relationship("Team", back_populates="tags")
+    creator: Mapped[Optional["User"]] = relationship("User", foreign_keys=[created_by])
+    trees: Mapped[list["Tree"]] = relationship(
+        "Tree",
+        secondary=tree_tag_assignments,
+        back_populates="tags"
+    )
+
+    @property
+    def is_global(self) -> bool:
+        """Returns True if this is a global tag (not team-specific)."""
+        return self.team_id is None
+
+    @classmethod
+    def slugify(cls, name: str) -> str:
+        """Convert a tag name to a URL-safe slug."""
+        import re
+        # Remove non-alphanumeric chars except spaces, convert to lowercase
+        slug = re.sub(r'[^a-zA-Z0-9 ]', '', name.lower())
+        # Replace spaces with hyphens
+        slug = re.sub(r' +', '-', slug.strip())
+        return slug

backend/app/models/team.py

@@ -1,10 +1,17 @@
 import uuid
 from datetime import datetime, timezone
+from typing import TYPE_CHECKING
 from sqlalchemy import String, DateTime
 from sqlalchemy.orm import Mapped, mapped_column, relationship
 from sqlalchemy.dialects.postgresql import UUID
 from app.core.database import Base
 
+if TYPE_CHECKING:
+    from app.models.user import User
+    from app.models.tree import Tree
+    from app.models.category import TreeCategory
+    from app.models.tag import TreeTag
+
 
 class Team(Base):
     __tablename__ = "teams"
@@ -23,3 +30,5 @@ class Team(Base):
     # Relationships
     users: Mapped[list["User"]] = relationship("User", back_populates="team")
     trees: Mapped[list["Tree"]] = relationship("Tree", back_populates="team")
+    categories: Mapped[list["TreeCategory"]] = relationship("TreeCategory", back_populates="team")
+    tags: Mapped[list["TreeTag"]] = relationship("TreeTag", back_populates="team")

backend/app/models/tree.py

@@ -1,11 +1,19 @@
 import uuid
 from datetime import datetime, timezone
-from typing import Optional, Any
+from typing import Optional, Any, TYPE_CHECKING
 from sqlalchemy import String, Text, DateTime, ForeignKey, Boolean, Integer, Index
 from sqlalchemy.orm import Mapped, mapped_column, relationship
 from sqlalchemy.dialects.postgresql import UUID, JSONB
 from app.core.database import Base
 
+if TYPE_CHECKING:
+    from app.models.user import User
+    from app.models.team import Team
+    from app.models.session import Session
+    from app.models.category import TreeCategory
+    from app.models.tag import TreeTag
+    from app.models.folder import UserFolder
+
 
 class Tree(Base):
     __tablename__ = "trees"
@@ -17,7 +25,16 @@ class Tree(Base):
     )
     name: Mapped[str] = mapped_column(String(255), nullable=False)
     description: Mapped[Optional[str]] = mapped_column(Text, nullable=True)
+    # Legacy category field - kept for backward compatibility
+    # New code should use category_id instead
     category: Mapped[Optional[str]] = mapped_column(String(100), nullable=True, index=True)
+    # New category relationship
+    category_id: Mapped[Optional[uuid.UUID]] = mapped_column(
+        UUID(as_uuid=True),
+        ForeignKey("tree_categories.id", ondelete="SET NULL"),
+        nullable=True,
+        index=True
+    )
     tree_structure: Mapped[dict[str, Any]] = mapped_column(JSONB, nullable=False)
     author_id: Mapped[Optional[uuid.UUID]] = mapped_column(
         UUID(as_uuid=True),
@@ -50,4 +67,22 @@ class Tree(Base):
     team: Mapped[Optional["Team"]] = relationship("Team", back_populates="trees")
     sessions: Mapped[list["Session"]] = relationship("Session", back_populates="tree")
 
+    # New organization relationships
+    category_rel: Mapped[Optional["TreeCategory"]] = relationship("TreeCategory", back_populates="trees")
+    tags: Mapped[list["TreeTag"]] = relationship(
+        "TreeTag",
+        secondary="tree_tag_assignments",
+        back_populates="trees"
+    )
+    folders: Mapped[list["UserFolder"]] = relationship(
+        "UserFolder",
+        secondary="user_folder_trees",
+        back_populates="trees"
+    )
+
     # Full-text search index will be created in migration
+
+    @property
+    def tag_names(self) -> list[str]:
+        """Returns list of tag names for this tree."""
+        return [tag.name for tag in self.tags] if self.tags else []

backend/app/models/user.py

@@ -1,11 +1,17 @@
 import uuid
 from datetime import datetime, timezone
-from typing import Optional
-from sqlalchemy import String, DateTime, ForeignKey
+from typing import Optional, TYPE_CHECKING
+from sqlalchemy import String, DateTime, ForeignKey, Boolean
 from sqlalchemy.orm import Mapped, mapped_column, relationship
 from sqlalchemy.dialects.postgresql import UUID
 from app.core.database import Base
 
+if TYPE_CHECKING:
+    from app.models.team import Team
+    from app.models.tree import Tree
+    from app.models.session import Session
+    from app.models.folder import UserFolder
+
 
 class User(Base):
     __tablename__ = "users"
@@ -19,6 +25,7 @@ class User(Base):
     password_hash: Mapped[str] = mapped_column(String(255), nullable=False)
     name: Mapped[str] = mapped_column(String(255), nullable=False)
     role: Mapped[str] = mapped_column(String(50), nullable=False, default="engineer")
+    is_team_admin: Mapped[bool] = mapped_column(Boolean, nullable=False, default=False)
     team_id: Mapped[Optional[uuid.UUID]] = mapped_column(
         UUID(as_uuid=True),
         ForeignKey("teams.id"),
@@ -38,4 +45,15 @@ class User(Base):
     # Relationships
     team: Mapped[Optional["Team"]] = relationship("Team", back_populates="users")
     trees: Mapped[list["Tree"]] = relationship("Tree", back_populates="author")
-    sessions: Mapped[list["Session"]] = relationship("Session", back_populates="user")
+    sessions: Mapped[list["Session"]] = relationship("Session", back_populates="user")
+    folders: Mapped[list["UserFolder"]] = relationship("UserFolder", back_populates="user")
+
+    @property
+    def is_admin(self) -> bool:
+        """Returns True if user is a global (Patherly) admin."""
+        return self.role == "admin"
+
+    @property
+    def can_manage_team(self) -> bool:
+        """Returns True if user can manage their team (team admin or global admin)."""
+        return self.is_admin or (self.is_team_admin and self.team_id is not None)