WIP checkpoint: Chat data models + migration (conversations, messages, reports)

backend/alembic/env.py

@@ -8,7 +8,7 @@ from sqlalchemy.ext.asyncio import create_async_engine
 
 from app.config import settings
 from app.database import Base
-from app.models import user, session, world, asset  # noqa: F401
+from app.models import user, session, world, asset, conversation, message  # noqa: F401
 
 # this is the Alembic Config object, which provides
 # access to the values within the .ini file in use.

backend/alembic/versions/1a1983be633a_chat_data_models.py

@@ -0,0 +1,228 @@
+"""chat data models
+
+Revision ID: 1a1983be633a
+Revises: 0001_initial
+Create Date: 2026-08-18 15:06:05.948446
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects import postgresql
+
+# revision identifiers, used by Alembic.
+revision: str = "1a1983be633a"
+down_revision: Union[str, None] = "0001_initial"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    """Create chat tables: conversations, conversation_participants,
+    messages, message_reports."""
+
+    # ── ENUM types ──────────────────────────────────────────────────
+
+    msg_report_reason = postgresql.ENUM(
+        "spam", "inappropriate", "off_topic", "other",
+        name="message_report_reason",
+    )
+    msg_report_reason.create(op.get_bind(), checkfirst=True)
+
+    msg_report_status = postgresql.ENUM(
+        "pending", "resolved", "dismissed",
+        name="message_report_status",
+    )
+    msg_report_status.create(op.get_bind(), checkfirst=True)
+
+    # ── conversations ───────────────────────────────────────────────
+
+    op.create_table(
+        "conversations",
+        sa.Column("id", sa.Integer(), primary_key=True),
+        sa.Column(
+            "latest_message_id",
+            sa.Integer(),
+            sa.ForeignKey("messages.id", ondelete="SET NULL"),
+            nullable=True,
+        ),
+        sa.Column(
+            "created_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.func.now(),
+        ),
+        sa.Column(
+            "updated_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.func.now(),
+            onupdate=sa.func.now(),
+        ),
+    )
+    op.create_index(op.f("ix_conversations_id"), "conversations", ["id"], unique=False)
+
+    # Unique pair constraint — populated later via participants
+    op.create_unique_constraint(
+        "uq_conversation_participants",
+        "conversations",
+        ["participant_1_id", "participant_2_id"],
+    )
+
+    # ── conversation_participants ───────────────────────────────────
+
+    op.create_table(
+        "conversation_participants",
+        sa.Column("id", sa.Integer(), primary_key=True),
+        sa.Column(
+            "conversation_id",
+            sa.Integer(),
+            sa.ForeignKey("conversations.id", ondelete="CASCADE"),
+            nullable=False,
+        ),
+        sa.Column(
+            "user_id",
+            sa.Integer(),
+            sa.ForeignKey("users.id", ondelete="CASCADE"),
+            nullable=False,
+        ),
+        sa.Column("left_at", sa.DateTime(timezone=True), nullable=True),
+        sa.Column("last_read_at", sa.DateTime(timezone=True), nullable=True),
+        sa.Column(
+            "created_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.func.now(),
+        ),
+    )
+    op.create_index(
+        op.f("ix_conversation_participants_id"),
+        "conversation_participants",
+        ["id"],
+        unique=False,
+    )
+    op.create_index(
+        op.f("ix_conversation_participants_user_id"),
+        "conversation_participants",
+        ["user_id"],
+        unique=False,
+    )
+    op.create_unique_constraint(
+        "uq_conversation_user",
+        "conversation_participants",
+        ["conversation_id", "user_id"],
+    )
+
+    # ── messages ────────────────────────────────────────────────────
+
+    op.create_table(
+        "messages",
+        sa.Column("id", sa.Integer(), primary_key=True),
+        sa.Column(
+            "sender_id",
+            sa.Integer(),
+            sa.ForeignKey("users.id", ondelete="CASCADE"),
+            nullable=False,
+        ),
+        sa.Column(
+            "conversation_id",
+            sa.Integer(),
+            sa.ForeignKey("conversations.id", ondelete="CASCADE"),
+            nullable=True,
+        ),
+        sa.Column(
+            "world_id",
+            sa.Integer(),
+            sa.ForeignKey("worlds.id", ondelete="CASCADE"),
+            nullable=True,
+        ),
+        sa.Column("room_id", sa.String(length=36), nullable=True),
+        sa.Column("body", sa.Text(), nullable=False),
+        sa.Column("is_filtered", sa.Boolean(), nullable=False, server_default="false"),
+        sa.Column(
+            "created_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.func.now(),
+        ),
+    )
+    op.create_index(op.f("ix_messages_id"), "messages", ["id"], unique=False)
+    op.create_index(
+        "ix_messages_conversation_created",
+        "messages",
+        ["conversation_id", "created_at"],
+    )
+    op.create_index(
+        "ix_messages_world_created",
+        "messages",
+        ["world_id", "created_at"],
+    )
+
+    # ── message_reports ─────────────────────────────────────────────
+
+    op.create_table(
+        "message_reports",
+        sa.Column("id", sa.Integer(), primary_key=True),
+        sa.Column(
+            "message_id",
+            sa.Integer(),
+            sa.ForeignKey("messages.id", ondelete="CASCADE"),
+            nullable=False,
+        ),
+        sa.Column(
+            "reporter_id",
+            sa.Integer(),
+            sa.ForeignKey("users.id", ondelete="SET NULL"),
+            nullable=False,
+        ),
+        sa.Column(
+            "reason",
+            postgresql.ENUM(
+                "spam", "inappropriate", "off_topic", "other",
+                name="message_report_reason",
+                create_type=False,
+            ),
+            nullable=False,
+        ),
+        sa.Column(
+            "status",
+            postgresql.ENUM(
+                "pending", "resolved", "dismissed",
+                name="message_report_status",
+                create_type=False,
+            ),
+            nullable=False,
+            server_default="pending",
+        ),
+        sa.Column(
+            "moderator_id",
+            sa.Integer(),
+            sa.ForeignKey("users.id", ondelete="SET NULL"),
+            nullable=True,
+        ),
+        sa.Column("resolved_at", sa.DateTime(timezone=True), nullable=True),
+        sa.Column(
+            "created_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.func.now(),
+        ),
+    )
+    op.create_index(op.f("ix_message_reports_id"), "message_reports", ["id"], unique=False)
+
+
+def downgrade() -> None:
+    """Drop chat tables in reverse dependency order."""
+    op.drop_index(op.f("ix_message_reports_id"), table_name="message_reports")
+    op.drop_table("message_reports")
+
+    op.drop_index(op.f("ix_messages_world_created"), table_name="messages")
+    op.drop_index(op.f("ix_messages_conversation_created"), table_name="messages")
+    op.drop_index(op.f("ix_messages_id"), table_name="messages")
+    op.drop_table("messages")
+
+    op.drop_index(op.f("ix_conversation_participants_user_id"), table_name="conversation_participants")
+    op.drop_index(op.f("ix_conversation_participants_id"), table_name="conversation_participants")
+    op.drop_table("conversation_participants")
+
+    op.drop_index(op.f("ix_conversations_id"), table_name="conversations")
+    op.drop_table("conversations")
+
+    # Drop ENUM types
+    postgresql.ENUM(name="message_report_status").drop(op.get_bind(), checkfirst=True)
+    postgresql.ENUM(name="message_report_reason").drop(op.get_bind(), checkfirst=True)

backend/app/models/__init__.py

@@ -2,5 +2,16 @@ from app.models.user import User
 from app.models.session import Session
 from app.models.world import World
 from app.models.asset import Asset
+from app.models.conversation import Conversation, ConversationParticipant
+from app.models.message import Message, MessageReport
 
-__all__ = ["User", "Session", "World", "Asset"]
+__all__ = [
+    "User",
+    "Session",
+    "World",
+    "Asset",
+    "Conversation",
+    "ConversationParticipant",
+    "Message",
+    "MessageReport",
+]

backend/app/models/conversation.py

@@ -0,0 +1,94 @@
+"""Conversation and participant models for DM chat."""
+
+from sqlalchemy import (
+    Column,
+    Integer,
+    String,
+    DateTime,
+    ForeignKey,
+    UniqueConstraint,
+    Index,
+)
+from sqlalchemy.orm import relationship
+from sqlalchemy.sql import func
+
+from app.database import Base
+
+
+class Conversation(Base):
+    """A DM conversation between two users.
+
+    Each conversation is uniquely identified by the pair of participant
+    user IDs (regardless of order).  A conversation is soft-deletable
+    via ``left_at`` on the participant row.
+    """
+
+    __tablename__ = "conversations"
+
+    id = Column(Integer, primary_key=True, index=True)
+    # The most recent message's ID in this conversation (denormalised
+    # for fast listing; updated by triggers or app logic).
+    latest_message_id = Column(
+        Integer, ForeignKey("messages.id", ondelete="SET NULL"), nullable=True
+    )
+    created_at = Column(DateTime(timezone=True), server_default=func.now())
+    updated_at = Column(DateTime(timezone=True), server_default=func.now(), onupdate=func.now())
+
+    # Relationships
+    latest_message = relationship(
+        "Message",
+        foreign_keys=[latest_message_id],
+        lazy="select",
+    )
+    participants = relationship(
+        "ConversationParticipant",
+        back_populates="conversation",
+        cascade="all, delete-orphan",
+        order_by="ConversationParticipant.id",
+    )
+
+    __table_args__ = (
+        # Ensure exactly one conversation per unique pair of users
+        UniqueConstraint("participant_1_id", "participant_2_id", name="uq_conversation_participants"),
+    )
+
+    def __repr__(self) -> str:
+        return f"<Conversation id={self.id}>"
+
+
+class ConversationParticipant(Base):
+    """Link table between conversations and users.
+
+    Stores per-participant metadata such as when they left the
+    conversation (for soft-delete / archival).
+    """
+
+    __tablename__ = "conversation_participants"
+
+    id = Column(Integer, primary_key=True, index=True)
+    conversation_id = Column(
+        Integer,
+        ForeignKey("conversations.id", ondelete="CASCADE"),
+        nullable=False,
+    )
+    user_id = Column(
+        Integer,
+        ForeignKey("users.id", ondelete="CASCADE"),
+        nullable=False,
+    )
+    # When the participant left (NULL = still active).
+    left_at = Column(DateTime(timezone=True), nullable=True)
+    # Timestamp of the last message read by this participant.
+    last_read_at = Column(DateTime(timezone=True), nullable=True)
+    created_at = Column(DateTime(timezone=True), server_default=func.now())
+
+    conversation = relationship("Conversation", back_populates="participants")
+    user = relationship("User")
+
+    __table_args__ = (
+        UniqueConstraint("conversation_id", "user_id", name="uq_conversation_user"),
+        Index("ix_conversation_participants_user_id", "user_id"),
+    )
+
+    def __repr__(self) -> str:
+        return f"<ConversationParticipant conversation_id={self.conversation_id} user_id={self.user_id}>"

backend/app/models/message.py

@@ -0,0 +1,96 @@
+"""Message models — messages, message reports."""
+
+from sqlalchemy import (
+    Column,
+    Integer,
+    String,
+    Text,
+    DateTime,
+    ForeignKey,
+    Boolean,
+    Index,
+)
+from sqlalchemy.dialects.postgresql import ENUM
+from sqlalchemy.orm import relationship
+from sqlalchemy.sql import func
+import enum
+
+from app.database import Base
+
+
+class MessageReportStatus(str, enum.Enum):
+    PENDING = "pending"
+    RESOLVED = "resolved"
+    DISMISSED = "dismissed"
+
+
+class MessageReportReason(str, enum.Enum):
+    SPAM = "spam"
+    INAPPROPRIATE = "inappropriate"
+    OFF_TOPIC = "off_topic"
+    OTHER = "other"
+
+
+class Message(Base):
+    __tablename__ = "messages"
+
+    id = Column(Integer, primary_key=True, index=True)
+    sender_id = Column(
+        Integer, ForeignKey("users.id", ondelete="CASCADE"), nullable=False
+    )
+    conversation_id = Column(
+        Integer, ForeignKey("conversations.id", ondelete="CASCADE"), nullable=True
+    )
+    world_id = Column(
+        Integer, ForeignKey("worlds.id", ondelete="CASCADE"), nullable=True
+    )
+    room_id = Column(String(36), nullable=True)
+    body = Column(Text, nullable=False)
+    is_filtered = Column(Boolean, default=False, nullable=False)
+    created_at = Column(DateTime(timezone=True), server_default=func.now())
+
+    # Relationships
+    sender = relationship("User", back_populates="sent_messages")
+    conversation = relationship("Conversation", back_populates="messages")
+    world = relationship("World")
+    reports = relationship(
+        "MessageReport", back_populates="message", cascade="all, delete-orphan"
+    )
+
+    # Indexes for history queries
+    __table_args__ = (
+        Index("ix_messages_conversation_created", "conversation_id", "created_at"),
+        Index("ix_messages_world_created", "world_id", "created_at"),
+    )
+
+
+class MessageReport(Base):
+    __tablename__ = "message_reports"
+
+    id = Column(Integer, primary_key=True, index=True)
+    message_id = Column(
+        Integer, ForeignKey("messages.id", ondelete="CASCADE"), nullable=False
+    )
+    reporter_id = Column(
+        Integer, ForeignKey("users.id", ondelete="SET NULL"), nullable=False
+    )
+    reason = Column(
+        ENUM(MessageReportReason, name="message_report_reason", create_type=False),
+        nullable=False,
+    )
+    details = Column(Text, nullable=True)
+    status = Column(
+        ENUM(MessageReportStatus, name="message_report_status", create_type=False),
+        default=MessageReportStatus.PENDING,
+        nullable=False,
+    )
+    moderator_id = Column(
+        Integer, ForeignKey("users.id", ondelete="SET NULL"), nullable=True
+    )
+    resolved_at = Column(DateTime(timezone=True), nullable=True)
+    created_at = Column(DateTime(timezone=True), server_default=func.now())
+
+    # Relationships
+    message = relationship("Message", back_populates="reports")
+    reporter = relationship("User", foreign_keys=[reporter_id])
+    moderator = relationship("User", foreign_keys=[moderator_id])

backend/app/models/user.py

@@ -19,3 +19,14 @@ class User(Base):
     sessions = relationship("Session", back_populates="user", cascade="all, delete-orphan")
     worlds = relationship("World", back_populates="owner")
     assets = relationship("Asset", back_populates="owner")
+    sent_messages = relationship("Message", back_populates="sender")
+    reported_messages = relationship(
+        "MessageReport",
+        foreign_keys="MessageReport.reporter_id",
+        back_populates="reporter",
+    )
+    moderated_reports = relationship(
+        "MessageReport",
+        foreign_keys="MessageReport.moderator_id",
+        back_populates="moderator",
+    )

docs/planning/social.md

@@ -0,0 +1,170 @@
+# Social — Friends, Chat & Groups — Plan
+
+> **Status:** Planned
+> **Owner:** Platform team
+> **Feature ID:** `social`
+> **Godot version:** 4.6.2 stable
+> **Backend:** FastAPI + SQLAlchemy (async) + PostgreSQL + Redis
+
+## 1. Overview
+
+This document breaks the **Social** feature into user stories and right-sized
+implementation tasks. The feature delivers:
+
+- **Friends & following** — a friend request/accept model plus a one-way follow
+  relationship, with block lists.
+- **Presence & status** — online/offline, custom status message, last-seen.
+- **Chat** — direct messages (DM) and in-experience (world/room) chat with
+  **first-class safety**: server-side text filtering, report-message, and rate
+  limiting.
+- **Groups** — named groups with roles (owner/admin/member) and a simple group
+  page.
+- **Public profiles** — avatar, bio, favorite experiences, and a friends list
+  that respects privacy settings.
+
+## 2. Why chat safety is the differentiator
+
+The platform is explicitly meant to pull adults away from a youth-oriented
+competitor. Chat is the highest-risk surface: it is real-time, user-generated,
+and where abuse happens fastest. Safety is therefore treated as a **blocking
+requirement**, not an add-on:
+
+- Every message passes a **server-side text filter** before it is stored or
+  delivered. The client filter is cosmetic only; the server is authoritative.
+- Every message can be **reported**; reports flow into a moderation queue with
+  actor + reason + audit trail (mirroring `content_moderation.md`).
+- Sending is **rate limited** per user (Redis token bucket) to stop flooding and
+  harassment-by-volume.
+- Report and block are always reachable from a message context in the UI.
+
+## 3. Existing constraints (do not re-build)
+
+- **Auth:** JWT bearer tokens; `get_current_user` / `CurrentUser` dependency in
+  `app/dependencies.py`. All social endpoints reuse this.
+- **DB:** async SQLAlchemy + Alembic; migration `0001_initial` is the head.
+- **Redis:** configured (`REDIS_URL`) but unused so far; adopted here for
+  presence and rate limiting.
+- **Models:** `User`, `World` (owner_id), `Asset` (owner_id, is_public). Avatars
+  and favorite-experience references point at existing rows.
+- **Client:** Godot 4.6.2, minimal `main_menu.gd`; no social UI yet.
+
+## 4. Key design decisions
+
+| Concern | Decision |
+|---|---|
+| Message transport | REST for send/history; **WebSocket** gateway for real-time delivery + presence (matches `networking.md`'s "WebSocket as secondary transport" for chat) |
+| Presence store | Redis (TTL heartbeat) + persisted `last_seen_at` on the user record |
+| Text filtering | Pluggable `TextFilter` interface with a deterministic default (profanity list + normalization) so it runs without external services; third-party hook later |
+| Rate limiting | Redis token-bucket dependency, reusable across all social endpoints |
+| Reports | `message_reports` table + moderation endpoints (list/review/resolve) with audit fields |
+| Friends vs. follow | Friends = mutual (request→accept). Follow = one-way (no approval). Block = hard deny that also hides content and prevents DMs |
+| Privacy | Per-user settings JSON (`profile_visibility`, `friends_list_visibility`, `favorites_visibility`) enforced server-side on every read |
+| Groups | `groups` + `group_members` (role: owner/admin/member) + group page aggregate endpoint |
+| Real-time | One WebSocket endpoint multiplexing presence, DM, and world-chat messages via Redis pub/sub |
+
+## 5. User stories
+
+### US-1 Friends & following
+As a player, I can send a friend request, accept/decline incoming requests,
+unfriend, follow/unfollow other players, and block users so they can't interact
+with me.
+
+**Acceptance criteria**
+- Friend requests are one-directional until accepted; accepted friendships are mutual.
+- Follow is one-way and requires no approval.
+- Block prevents DMs, hides the blocked user's profile/friends interactions, and
+  removes any existing friendship/follow between the two.
+- Duplicate/self requests are rejected idempotently.
+
+### US-2 Presence & status
+As a player, I can see whether my friends are online, their custom status, and
+when they were last seen.
+
+**Acceptance criteria**
+- Online/offline is derived from a server-side heartbeat (Redis TTL), not client claims.
+- `last_seen_at` persists and is visible (subject to privacy settings).
+- Custom status text is optional and length-limited.
+
+### US-3 Public profiles
+As a player, I can view a public profile page showing avatar, bio, favorite
+experiences, and a friends list that respects the owner's privacy settings.
+
+**Acceptance criteria**
+- Avatar and bio are editable by the owner only.
+- Favorite experiences reference existing `World` rows.
+- A viewer sees only the sections the owner's privacy settings allow; blocked
+  users see a restricted view.
+
+### US-4 Chat (DM + in-experience) with safety
+As a player, I can send direct messages and chat inside a world/room. Messages
+are filtered, rate limited, and reportable.
+
+**Acceptance criteria**
+- Server filters message text before storing/delivering; filtered content is either
+  rejected (blocking) or redacted (configurable per filter policy).
+- Send rate is limited per user (token bucket); excess sends get `429`.
+- Every message has a stable id, author, timestamp, and conversation/world scope.
+- Any message can be reported with a reason; reports are stored and reviewable.
+- Real-time delivery over WebSocket with REST fallback for history.
+
+### US-5 Groups
+As a player, I can create a group, join/leave groups, and (as owner/admin)
+manage roles and view a simple group page.
+
+**Acceptance criteria**
+- Each group has exactly one owner and any number of admins/members.
+- Role transitions are authorized (only owner can transfer ownership or promote/demote admins).
+- Group page lists name, description, member list with roles, and member count.
+
+### US-6 Godot client
+As a player, I can access friends, presence, chat, profiles, and groups from the
+game UI.
+
+**Acceptance criteria**
+- An API client handles JWT auth, HTTP, and WebSocket for all social calls.
+- Dedicated screens/panels: friends+presence, DM & world chat (with report),
+  profile page, group page.
+- Client-side filtering is cosmetic; server responses remain authoritative.
+
+## 6. Task breakdown
+
+Right-sized to 1–3 files / one coherent piece of functionality each. Task IDs
+are sequential for dependency chaining.
+
+| # | Task | Story | Depends on |
+|---|------|-------|-----------|
+| 1 | Friends/follow/block models + Alembic migration | US-1 | — |
+| 2 | Friends & follow API router | US-1 | 1 |
+| 3 | Presence & status model + endpoints (Redis heartbeat) | US-2 | — |
+| 4 | Profile model + migration + own-profile endpoints | US-3 | 1 |
+| 5 | Public profile view + favorites + privacy enforcement | US-3 | 2, 4 |
+| 6 | Chat data models + migration (conversations, messages, reports) | US-4 | — |
+| 7 | Text filtering service + profanity config | US-4 | — |
+| 8 | Redis rate-limiting dependency | US-4 | — |
+| 9 | DM chat send/list endpoints (filter + rate limit) | US-4 | 6, 7, 8 |
+| 10 | Report-message endpoint + moderation queue | US-4 | 6, 9 |
+| 11 | In-experience (world/room) chat endpoints | US-4 | 9 |
+| 12 | Real-time WebSocket gateway (presence + DM + world chat) | US-4 | 3, 9, 11 |
+| 13 | Group + membership models + migration | US-5 | — |
+| 14 | Groups API (CRUD, join/leave, roles, group page) | US-5 | 13 |
+| 15 | Godot API client (auth + HTTP + WebSocket) | US-6 | 2 |
+| 16 | Godot friends & presence UI | US-6 | 3, 15 |
+| 17 | Godot chat UI (DM + world chat + report) | US-6 | 12, 15 |
+| 18 | Godot profile page UI | US-6 | 5, 15 |
+| 19 | Godot groups UI + group page | US-6 | 14, 15 |
+
+## 7. Phasing
+
+- **Phase 1 (data + core APIs):** tasks 1–5 (friends, presence, profiles).
+- **Phase 2 (chat safety — the differentiator):** tasks 6–12 (chat + safety +
+  realtime). This is the critical path and highest priority.
+- **Phase 3 (groups):** tasks 13–14.
+- **Phase 4 (client):** tasks 15–19, each landing after its backend dependency.
+
+## 8. Out of scope for this feature
+
+- Age verification / maturity gating (covered by `content_moderation.md`).
+- Voice chat, media/image messages, message editing/deletion history.
+- Third-party profanity/toxicity vendors (the `TextFilter` interface leaves a
+  hook, but the default is deterministic and dependency-free).
+- Mobile push notifications.