feat: add account-based subscription model with migrations

Transition from team-based to account-based multi-tenancy (Free/Pro/Team).
Migrations 016-020 create accounts, subscriptions, plan_limits, and
account_invites tables, then migrate existing users and content FKs.

New models: Account, Subscription, PlanLimits, AccountInvite.
Updated models add account_id alongside existing team_id (coexistence
for safe two-PR deployment). Permissions and deps refactored for
account_role instead of is_team_admin.

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

backend/app/models/__init__.py

@@ -1,5 +1,9 @@
 from .user import User
 from .team import Team
+from .account import Account
+from .subscription import Subscription
+from .plan_limits import PlanLimits
+from .account_invite import AccountInvite
 from .tree import Tree
 from .session import Session
 from .attachment import Attachment
@@ -15,6 +19,10 @@ from .audit_log import AuditLog
 __all__ = [
     "User",
     "Team",
+    "Account",
+    "Subscription",
+    "PlanLimits",
+    "AccountInvite",
     "Tree",
     "Session",
     "Attachment",

backend/app/models/account.py

@@ -0,0 +1,38 @@
+import uuid
+from datetime import datetime, timezone
+from typing import Optional, TYPE_CHECKING
+from sqlalchemy import String, DateTime, ForeignKey
+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.subscription import Subscription
+    from app.models.tree import Tree
+    from app.models.category import TreeCategory
+    from app.models.tag import TreeTag
+    from app.models.step_category import StepCategory
+    from app.models.step_library import StepLibrary
+
+
+class Account(Base):
+    __tablename__ = "accounts"
+
+    id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    name: Mapped[str] = mapped_column(String(255), nullable=False)
+    display_code: Mapped[str] = mapped_column(String(8), unique=True, nullable=False)
+    owner_id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), ForeignKey("users.id", ondelete="RESTRICT"), nullable=False)
+    stripe_customer_id: Mapped[Optional[str]] = mapped_column(String(255), 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
+    owner: Mapped["User"] = relationship("User", foreign_keys=[owner_id], back_populates="owned_account")
+    users: Mapped[list["User"]] = relationship("User", foreign_keys="[User.account_id]", back_populates="account")
+    subscription: Mapped[Optional["Subscription"]] = relationship("Subscription", back_populates="account", uselist=False)
+    trees: Mapped[list["Tree"]] = relationship("Tree", foreign_keys="[Tree.account_id]", back_populates="account")
+    categories: Mapped[list["TreeCategory"]] = relationship("TreeCategory", foreign_keys="[TreeCategory.account_id]", back_populates="account")
+    tags: Mapped[list["TreeTag"]] = relationship("TreeTag", foreign_keys="[TreeTag.account_id]", back_populates="account")
+    step_categories: Mapped[list["StepCategory"]] = relationship("StepCategory", foreign_keys="[StepCategory.account_id]", back_populates="account")
+    step_library: Mapped[list["StepLibrary"]] = relationship("StepLibrary", foreign_keys="[StepLibrary.account_id]", back_populates="account")

backend/app/models/account_invite.py

@@ -0,0 +1,48 @@
+import uuid
+from datetime import datetime, timezone
+from typing import Optional, TYPE_CHECKING
+from sqlalchemy import String, DateTime, ForeignKey, CheckConstraint
+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.account import Account
+    from app.models.user import User
+
+
+class AccountInvite(Base):
+    __tablename__ = "account_invites"
+    __table_args__ = (
+        CheckConstraint("role IN ('engineer', 'viewer')", name='ck_account_invites_role'),
+    )
+
+    id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    account_id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), ForeignKey("accounts.id", ondelete="CASCADE"), nullable=False)
+    invited_by_id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), ForeignKey("users.id"), nullable=False)
+    email: Mapped[str] = mapped_column(String(255), nullable=False)
+    code: Mapped[str] = mapped_column(String(32), unique=True, nullable=False)
+    role: Mapped[str] = mapped_column(String(50), nullable=False, default="engineer")
+    accepted_by_id: Mapped[Optional[uuid.UUID]] = mapped_column(UUID(as_uuid=True), ForeignKey("users.id"), nullable=True)
+    expires_at: Mapped[Optional[datetime]] = mapped_column(DateTime(timezone=True), nullable=True)
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=lambda: datetime.now(timezone.utc))
+    used_at: Mapped[Optional[datetime]] = mapped_column(DateTime(timezone=True), nullable=True)
+
+    # Relationships
+    account: Mapped["Account"] = relationship("Account")
+    invited_by: Mapped["User"] = relationship("User", foreign_keys=[invited_by_id])
+    accepted_by: Mapped[Optional["User"]] = relationship("User", foreign_keys=[accepted_by_id])
+
+    @property
+    def is_used(self) -> bool:
+        return self.accepted_by_id is not None
+
+    @property
+    def is_expired(self) -> bool:
+        if self.expires_at is None:
+            return False
+        return datetime.now(timezone.utc) > self.expires_at
+
+    @property
+    def is_valid(self) -> bool:
+        return not self.is_used and not self.is_expired

backend/app/models/category.py

@@ -9,6 +9,7 @@ from app.core.database import Base
 if TYPE_CHECKING:
     from app.models.tree import Tree
     from app.models.team import Team
+    from app.models.account import Account
     from app.models.user import User
 
 
@@ -38,6 +39,12 @@ class TreeCategory(Base):
         nullable=True,
         index=True
     )
+    account_id: Mapped[Optional[uuid.UUID]] = mapped_column(
+        UUID(as_uuid=True),
+        ForeignKey("accounts.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(
@@ -57,10 +64,11 @@ class TreeCategory(Base):
 
     # Relationships
     team: Mapped[Optional["Team"]] = relationship("Team", back_populates="categories")
+    account: Mapped[Optional["Account"]] = relationship("Account", foreign_keys=[account_id], 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
+        """Returns True if this is a global category (not team or account-specific)."""
+        return self.team_id is None and self.account_id is None

backend/app/models/plan_limits.py

@@ -0,0 +1,16 @@
+from sqlalchemy import String, Integer, Boolean
+from sqlalchemy.orm import Mapped, mapped_column
+from sqlalchemy.dialects.postgresql import JSONB
+from app.core.database import Base
+
+
+class PlanLimits(Base):
+    __tablename__ = "plan_limits"
+
+    plan: Mapped[str] = mapped_column(String(50), primary_key=True)
+    max_trees: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    max_sessions_per_month: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    max_users: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    custom_branding: Mapped[bool] = mapped_column(Boolean, nullable=False, default=False)
+    priority_support: Mapped[bool] = mapped_column(Boolean, nullable=False, default=False)
+    export_formats: Mapped[list] = mapped_column(JSONB, nullable=False, default=lambda: ["markdown", "text"])

backend/app/models/step_category.py

@@ -8,6 +8,7 @@ from app.core.database import Base
 
 if TYPE_CHECKING:
     from app.models.team import Team
+    from app.models.account import Account
     from app.models.user import User
 
 
@@ -37,6 +38,12 @@ class StepCategory(Base):
         nullable=True,
         index=True
     )
+    account_id: Mapped[Optional[uuid.UUID]] = mapped_column(
+        UUID(as_uuid=True),
+        ForeignKey("accounts.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(
@@ -56,9 +63,10 @@ class StepCategory(Base):
 
     # Relationships
     team: Mapped[Optional["Team"]] = relationship("Team", back_populates="step_categories")
+    account: Mapped[Optional["Account"]] = relationship("Account", foreign_keys=[account_id], back_populates="step_categories")
     creator: Mapped[Optional["User"]] = relationship("User", foreign_keys=[created_by])
 
     @property
     def is_global(self) -> bool:
-        """Returns True if this is a global category (not team-specific)."""
-        return self.team_id is None
+        """Returns True if this is a global category (not team or account-specific)."""
+        return self.team_id is None and self.account_id is None

backend/app/models/step_library.py

@@ -10,6 +10,7 @@ from app.core.database import Base
 if TYPE_CHECKING:
     from app.models.user import User
     from app.models.team import Team
+    from app.models.account import Account
     from app.models.step_category import StepCategory
     from app.models.session import Session
 
@@ -43,6 +44,12 @@ class StepLibrary(Base):
         ForeignKey("teams.id", ondelete="CASCADE"),
         nullable=True
     )
+    account_id: Mapped[Optional[uuid.UUID]] = mapped_column(
+        UUID(as_uuid=True),
+        ForeignKey("accounts.id", ondelete="CASCADE"),
+        nullable=True,
+        index=True
+    )
 
     # Organization
     category_id: Mapped[Optional[uuid.UUID]] = mapped_column(
@@ -91,6 +98,7 @@ class StepLibrary(Base):
     # Relationships
     creator: Mapped["User"] = relationship("User", foreign_keys=[created_by])
     team: Mapped[Optional["Team"]] = relationship("Team")
+    account: Mapped[Optional["Account"]] = relationship("Account", foreign_keys=[account_id], back_populates="step_library")
     category: Mapped[Optional["StepCategory"]] = relationship("StepCategory")
     ratings: Mapped[list["StepRating"]] = relationship("StepRating", back_populates="step", cascade="all, delete-orphan")
     usage_logs: Mapped[list["StepUsageLog"]] = relationship("StepUsageLog", back_populates="step", cascade="all, delete-orphan")

backend/app/models/subscription.py

@@ -0,0 +1,39 @@
+import uuid
+from datetime import datetime, timezone
+from typing import Optional, TYPE_CHECKING
+from sqlalchemy import String, DateTime, ForeignKey, Boolean, Integer
+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.account import Account
+
+
+class Subscription(Base):
+    __tablename__ = "subscriptions"
+
+    id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    account_id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), ForeignKey("accounts.id", ondelete="CASCADE"), unique=True, nullable=False)
+    stripe_subscription_id: Mapped[Optional[str]] = mapped_column(String(255), nullable=True)
+    stripe_price_id: Mapped[Optional[str]] = mapped_column(String(255), nullable=True)
+    plan: Mapped[str] = mapped_column(String(50), nullable=False, default="free")
+    billing_interval: Mapped[Optional[str]] = mapped_column(String(20), nullable=True)
+    status: Mapped[str] = mapped_column(String(50), nullable=False, default="active")
+    seat_limit: Mapped[Optional[int]] = mapped_column(Integer, nullable=True)
+    current_period_start: Mapped[Optional[datetime]] = mapped_column(DateTime(timezone=True), nullable=True)
+    current_period_end: Mapped[Optional[datetime]] = mapped_column(DateTime(timezone=True), nullable=True)
+    cancel_at_period_end: Mapped[bool] = mapped_column(Boolean, nullable=False, default=False)
+    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
+    account: Mapped["Account"] = relationship("Account", back_populates="subscription")
+
+    @property
+    def is_active(self) -> bool:
+        return self.status in ("active", "trialing")
+
+    @property
+    def is_paid(self) -> bool:
+        return self.plan in ("pro", "team")

backend/app/models/tag.py

@@ -9,6 +9,7 @@ from app.core.database import Base
 if TYPE_CHECKING:
     from app.models.tree import Tree
     from app.models.team import Team
+    from app.models.account import Account
     from app.models.user import User
 
 
@@ -50,6 +51,12 @@ class TreeTag(Base):
         nullable=True,
         index=True
     )
+    account_id: Mapped[Optional[uuid.UUID]] = mapped_column(
+        UUID(as_uuid=True),
+        ForeignKey("accounts.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),
@@ -63,6 +70,7 @@ class TreeTag(Base):
 
     # Relationships
     team: Mapped[Optional["Team"]] = relationship("Team", back_populates="tags")
+    account: Mapped[Optional["Account"]] = relationship("Account", foreign_keys=[account_id], back_populates="tags")
     creator: Mapped[Optional["User"]] = relationship("User", foreign_keys=[created_by])
     trees: Mapped[list["Tree"]] = relationship(
         "Tree",
@@ -72,8 +80,8 @@ class TreeTag(Base):
 
     @property
     def is_global(self) -> bool:
-        """Returns True if this is a global tag (not team-specific)."""
-        return self.team_id is None
+        """Returns True if this is a global tag (not team or account-specific)."""
+        return self.team_id is None and self.account_id is None
 
     @classmethod
     def slugify(cls, name: str) -> str:

backend/app/models/tree.py

@@ -9,6 +9,7 @@ from app.core.database import Base
 if TYPE_CHECKING:
     from app.models.user import User
     from app.models.team import Team
+    from app.models.account import Account
     from app.models.session import Session
     from app.models.category import TreeCategory
     from app.models.tag import TreeTag
@@ -47,6 +48,12 @@ class Tree(Base):
         nullable=True,
         index=True
     )
+    account_id: Mapped[Optional[uuid.UUID]] = mapped_column(
+        UUID(as_uuid=True),
+        ForeignKey("accounts.id", ondelete="CASCADE"),
+        nullable=True,
+        index=True
+    )
     is_active: Mapped[bool] = mapped_column(Boolean, default=True)
     is_public: Mapped[bool] = mapped_column(Boolean, default=False, index=True)
     is_default: Mapped[bool] = mapped_column(Boolean, default=False, index=True)
@@ -75,6 +82,7 @@ class Tree(Base):
     # Relationships
     author: Mapped[Optional["User"]] = relationship("User", foreign_keys=[author_id], back_populates="trees")
     team: Mapped[Optional["Team"]] = relationship("Team", back_populates="trees")
+    account: Mapped[Optional["Account"]] = relationship("Account", foreign_keys=[account_id], back_populates="trees")
     sessions: Mapped[list["Session"]] = relationship("Session", back_populates="tree")
 
     # New organization relationships

backend/app/models/user.py

@@ -8,6 +8,7 @@ from app.core.database import Base
 
 if TYPE_CHECKING:
     from app.models.team import Team
+    from app.models.account import Account
     from app.models.tree import Tree
     from app.models.session import Session
     from app.models.folder import UserFolder
@@ -20,6 +21,10 @@ class User(Base):
             "role IN ('engineer', 'viewer')",
             name='ck_users_role_enum'
         ),
+        CheckConstraint(
+            "account_role IN ('owner', 'admin', 'engineer', 'viewer')",
+            name='ck_users_account_role_enum'
+        ),
     )
 
     id: Mapped[uuid.UUID] = mapped_column(
@@ -34,6 +39,17 @@ class User(Base):
     is_super_admin: Mapped[bool] = mapped_column(Boolean, nullable=False, default=False)
     is_team_admin: Mapped[bool] = mapped_column(Boolean, nullable=False, default=False)
     is_active: Mapped[bool] = mapped_column(Boolean, nullable=False, default=True, server_default="true")
+
+    # Account-based multi-tenancy (new)
+    account_id: Mapped[Optional[uuid.UUID]] = mapped_column(
+        UUID(as_uuid=True),
+        ForeignKey("accounts.id", ondelete="RESTRICT"),
+        nullable=True,
+        index=True
+    )
+    account_role: Mapped[str] = mapped_column(String(50), nullable=False, default="engineer")
+
+    # Legacy team columns (kept for PR A coexistence)
     team_id: Mapped[Optional[uuid.UUID]] = mapped_column(
         UUID(as_uuid=True),
         ForeignKey("teams.id"),
@@ -51,6 +67,8 @@ class User(Base):
     last_login: Mapped[Optional[datetime]] = mapped_column(DateTime(timezone=True), nullable=True)
 
     # Relationships
+    account: Mapped[Optional["Account"]] = relationship("Account", foreign_keys=[account_id], back_populates="users")
+    owned_account: Mapped[Optional["Account"]] = relationship("Account", foreign_keys="[Account.owner_id]", back_populates="owner", uselist=False)
     team: Mapped[Optional["Team"]] = relationship("Team", back_populates="users")
     trees: Mapped[list["Tree"]] = relationship("Tree", foreign_keys="[Tree.author_id]", back_populates="author")
     sessions: Mapped[list["Session"]] = relationship("Session", back_populates="user")
@@ -62,6 +80,11 @@ class User(Base):
         return self.is_super_admin
 
     @property
-    def can_manage_team(self) -> bool:
-        """Returns True if user can manage their team (team admin or super admin)."""
-        return self.is_super_admin or (self.is_team_admin and self.team_id is not None)
+    def is_account_owner(self) -> bool:
+        """Returns True if user owns their account."""
+        return self.account_role == "owner"
+
+    @property
+    def can_manage_account(self) -> bool:
+        """Returns True if user can manage their account (owner, admin, or super admin)."""
+        return self.is_super_admin or self.account_role in ("owner", "admin")