M0: backend skeleton — Quart factory, async DB, auth, ACL spine, migrations

Foundation & Identity backend for ThoughtSync:
- Quart app factory (create_app) with /api/health + SPA history-fallback
- async SQLAlchemy 2.0 + asyncpg engine/session (lazy; boots without a DB)
- native email+password auth via signed-cookie session (register/login/logout/me
  + login_required guard); bcrypt password hashing (72-byte safe)
- multi-user sharing-ACL spine (rule 47): users, groups, group_members, and a
  polymorphic shares table + visible_to_user() SQL predicate (owner OR direct
  share OR group share) that M1's notes will scope through
- Alembic async env (adapted from family pattern) + 0001 foundation migration
- DB-free unit tests (app/health/auth-guard, password roundtrip, ACL compile)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FRgehjoz7Yv8LkUfADxACm

src/thoughtsync/models/__init__.py

@@ -0,0 +1,7 @@
+from __future__ import annotations
+
+from sqlalchemy.orm import DeclarativeBase
+
+
+class Base(DeclarativeBase):
+    """Declarative base for all ORM models. Alembic reads Base.metadata."""

src/thoughtsync/models/all.py

@@ -0,0 +1,6 @@
+"""Import every model module so Base.metadata is fully populated for Alembic.
+
+Imported for side effects only (model registration on Base.metadata).
+"""
+
+from . import group, share, user  # noqa: F401

src/thoughtsync/models/group.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+import uuid
+from datetime import datetime
+
+from sqlalchemy import DateTime, ForeignKey, Text, UniqueConstraint, func
+from sqlalchemy.dialects.postgresql import UUID
+from sqlalchemy.orm import Mapped, mapped_column
+
+from . import Base
+
+
+class Group(Base):
+    """A named set of users. Sharing a resource with a group grants it to every
+    member (see thoughtsync.acl.visible_to_user)."""
+
+    __tablename__ = "groups"
+
+    id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    name: Mapped[str] = mapped_column(Text(), nullable=False)
+    owner_id: Mapped[uuid.UUID | None] = mapped_column(
+        UUID(as_uuid=True), ForeignKey("users.id", ondelete="SET NULL"), nullable=True
+    )
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False, server_default=func.now())
+
+
+class GroupMember(Base):
+    __tablename__ = "group_members"
+    __table_args__ = (UniqueConstraint("group_id", "user_id", name="uq_group_members_group_user"),)
+
+    id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    group_id: Mapped[uuid.UUID] = mapped_column(
+        UUID(as_uuid=True), ForeignKey("groups.id", ondelete="CASCADE"), nullable=False
+    )
+    user_id: Mapped[uuid.UUID] = mapped_column(
+        UUID(as_uuid=True), ForeignKey("users.id", ondelete="CASCADE"), nullable=False
+    )
+    role: Mapped[str] = mapped_column(Text(), nullable=False, server_default="member")
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False, server_default=func.now())

src/thoughtsync/models/share.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+import uuid
+from datetime import datetime
+
+from sqlalchemy import CheckConstraint, DateTime, ForeignKey, Text, func
+from sqlalchemy.dialects.postgresql import UUID
+from sqlalchemy.orm import Mapped, mapped_column
+
+from . import Base
+
+
+class Share(Base):
+    """An additional access grant on one resource (identified by type + id).
+
+    A resource's OWNER is tracked on the resource row itself (its owner_id column);
+    this table records grants BEYOND the owner — to a single user or to a whole
+    group. It is polymorphic (resource_type + resource_id) so every future
+    shareable entity (notes first, in M1) reuses one table and one ACL predicate.
+    Exactly one of shared_with_user_id / shared_with_group_id is set.
+    """
+
+    __tablename__ = "shares"
+    __table_args__ = (
+        CheckConstraint(
+            "(shared_with_user_id IS NOT NULL) <> (shared_with_group_id IS NOT NULL)",
+            name="ck_shares_one_target",
+        ),
+    )
+
+    id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    resource_type: Mapped[str] = mapped_column(Text(), nullable=False)
+    resource_id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), nullable=False)
+    shared_with_user_id: Mapped[uuid.UUID | None] = mapped_column(
+        UUID(as_uuid=True), ForeignKey("users.id", ondelete="CASCADE"), nullable=True
+    )
+    shared_with_group_id: Mapped[uuid.UUID | None] = mapped_column(
+        UUID(as_uuid=True), ForeignKey("groups.id", ondelete="CASCADE"), nullable=True
+    )
+    permission: Mapped[str] = mapped_column(Text(), nullable=False, server_default="view")
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False, server_default=func.now())

src/thoughtsync/models/user.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+import uuid
+from datetime import datetime
+
+from sqlalchemy import Boolean, DateTime, Text, func
+from sqlalchemy.dialects.postgresql import CITEXT, UUID
+from sqlalchemy.orm import Mapped, mapped_column
+
+from . import Base
+
+
+class User(Base):
+    __tablename__ = "users"
+
+    id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    # CITEXT so lookups/uniqueness are case-insensitive without lower() everywhere.
+    email: Mapped[str] = mapped_column(CITEXT(), nullable=False, unique=True)
+    email_verified: Mapped[bool] = mapped_column(Boolean(), nullable=False, server_default=func.false())
+    # Nullable: leaves room for external-identity-only accounts later (rule 26).
+    password_hash: Mapped[str | None] = mapped_column(Text(), nullable=True)
+    display_name: Mapped[str] = mapped_column(Text(), nullable=False)
+    avatar_path: Mapped[str | None] = mapped_column(Text(), nullable=True)
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False, server_default=func.now())
+    updated_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False, server_default=func.now())