WIP checkpoint: US-1: Asset Import Pipeline — glTF upload endpoint with metadata extraction

world_visibility and asset_type were each declared twice: once explicitly
via `.create(checkfirst=True)`, and again implicitly by SQLAlchemy when
create_table() compiled the inline postgresql.ENUM() column type (which
defaults create_type=True). On a genuinely empty database this raises
asyncpg.DuplicateObjectError mid-transaction and the migration never
completes -- verified this was true 100% of the time from a fresh
container, meaning the backend has never successfully bootstrapped from
scratch. Fixed by passing create_type=False on the inline column
declarations, since the type is already created explicitly above.

Also parameterized both services' host ports (POSTGRES_HOST_PORT /
REDIS_HOST_PORT, defaulting to the original 5432/6379) so concurrent
agent workspaces sharing this same docker-compose.yml can run isolated
databases without colliding on the host port.

backend/alembic/versions/0001_initial.py

@@ -69,7 +69,8 @@ def upgrade() -> None:
         sa.Column(
             "visibility",
             postgresql.ENUM(
-                "public", "private", "friends_only", name="world_visibility"
+                "public", "private", "friends_only", name="world_visibility",
+                create_type=False,
             ),
             nullable=True,
         ),
@@ -89,7 +90,7 @@ def upgrade() -> None:
             "asset_type",
             postgresql.ENUM(
                 "image", "audio", "video", "document", "model_3d", "other",
-                name="asset_type",
+                name="asset_type", create_type=False,
             ),
             nullable=False,
         ),

backend/alembic/versions/0003_trust_safety.py

@@ -1,329 +0,0 @@
-"""trust & safety: reports, moderation_actions, appeals + user role/ban/suspend
-
-Revision ID: 0003_trust_safety
-Revises: 0002_add_date_of_birth_to_users
-Create Date: 2025-01-01 00:00:00.000000
-
-"""
-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 = "0003_trust_safety"
-down_revision: Union[str, None] = "0002_add_date_of_birth_to_users"
-branch_labels: Union[str, Sequence[str], None] = None
-depends_on: Union[str, Sequence[str], None] = None
-
-
-def upgrade() -> None:
-    """Create trust & safety tables and extend users table."""
-    bind = op.get_bind()
-
-    # ── ENUM types ──────────────────────────────────────────────────────
-
-    # user_role
-    user_role = postgresql.ENUM("user", "moderator", "admin", name="user_role")
-    user_role.create(bind, checkfirst=True)
-
-    # report_target_type
-    report_target_type = postgresql.ENUM(
-        "user", "world", "asset", "chat_message", name="report_target_type"
-    )
-    report_target_type.create(bind, checkfirst=True)
-
-    # reason_category
-    reason_category = postgresql.ENUM(
-        "harassment",
-        "hate_speech",
-        "sexual_content",
-        "violence",
-        "spam",
-        "self_harm",
-        "other",
-        name="reason_category",
-    )
-    reason_category.create(bind, checkfirst=True)
-
-    # report_status
-    report_status = postgresql.ENUM(
-        "open", "in_review", "resolved", "dismissed", name="report_status"
-    )
-    report_status.create(bind, checkfirst=True)
-
-    # resolution
-    resolution_enum = postgresql.ENUM(
-        "action_taken", "no_action", "false_positive", name="resolution"
-    )
-    resolution_enum.create(bind, checkfirst=True)
-
-    # moderation_action_type
-    moderation_action_type = postgresql.ENUM(
-        "warn", "suspend", "ban", "restrict", "remove", "restore",
-        name="moderation_action_type",
-    )
-    moderation_action_type.create(bind, checkfirst=True)
-
-    # moderation_target_type
-    moderation_target_type = postgresql.ENUM(
-        "user", "world", "asset", "chat_message", name="moderation_target_type"
-    )
-    moderation_target_type.create(bind, checkfirst=True)
-
-    # appeal_status
-    appeal_status = postgresql.ENUM(
-        "pending", "approved", "rejected", name="appeal_status"
-    )
-    appeal_status.create(bind, checkfirst=True)
-
-    # ── Extend users table ──────────────────────────────────────────────
-
-    op.add_column(
-        "users",
-        sa.Column(
-            "role",
-            postgresql.ENUM("user", "moderator", "admin", name="user_role"),
-            nullable=False,
-            server_default="user",
-        ),
-    )
-    op.add_column(
-        "users",
-        sa.Column("banned_until", sa.DateTime(timezone=True), nullable=True),
-    )
-    op.add_column(
-        "users",
-        sa.Column("suspended_until", sa.DateTime(timezone=True), nullable=True),
-    )
-
-    # ── reports table ───────────────────────────────────────────────────
-
-    op.create_table(
-        "reports",
-        sa.Column("id", sa.BigInteger(), primary_key=True, autoincrement=True),
-        sa.Column("reporter_id", sa.Integer(), nullable=False),
-        sa.Column(
-            "target_type",
-            postgresql.ENUM(
-                "user", "world", "asset", "chat_message", name="report_target_type"
-            ),
-            nullable=False,
-        ),
-        sa.Column("target_id", sa.String(length=64), nullable=False),
-        sa.Column(
-            "reason_category",
-            postgresql.ENUM(
-                "harassment",
-                "hate_speech",
-                "sexual_content",
-                "violence",
-                "spam",
-                "self_harm",
-                "other",
-                name="reason_category",
-            ),
-            nullable=False,
-        ),
-        sa.Column(
-            "details", sa.Text(), nullable=True,
-        ),
-        sa.Column(
-            "status",
-            postgresql.ENUM(
-                "open", "in_review", "resolved", "dismissed", name="report_status"
-            ),
-            nullable=False,
-            server_default="open",
-        ),
-        sa.Column("resolved_by", sa.Integer(), nullable=True),
-        sa.Column(
-            "resolution",
-            postgresql.ENUM(
-                "action_taken", "no_action", "false_positive", name="resolution"
-            ),
-            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(),
-            nullable=False,
-        ),
-        sa.Column(
-            "updated_at",
-            sa.DateTime(timezone=True),
-            onupdate=sa.func.now(),
-            nullable=True,
-        ),
-        sa.ForeignKeyConstraint(["reporter_id"], ["users.id"], ondelete="CASCADE"),
-        sa.ForeignKeyConstraint(["resolved_by"], ["users.id"], ondelete="SET NULL"),
-        sa.UniqueConstraint(
-            "reporter_id", "target_type", "target_id",
-            name="uq_reporter_target",
-        ),
-    )
-    op.create_index(op.f("ix_reports_id"), "reports", ["id"], unique=False)
-    op.create_index(
-        op.f("ix_reports_reporter_id"), "reports", ["reporter_id"], unique=False
-    )
-    op.create_index(
-        op.f("ix_reports_status"), "reports", ["status"], unique=False
-    )
-
-    # ── moderation_actions table ────────────────────────────────────────
-
-    op.create_table(
-        "moderation_actions",
-        sa.Column("id", sa.BigInteger(), primary_key=True, autoincrement=True),
-        sa.Column("moderator_id", sa.Integer(), nullable=False),
-        sa.Column("target_user_id", sa.Integer(), nullable=True),
-        sa.Column(
-            "target_type",
-            postgresql.ENUM(
-                "user", "world", "asset", "chat_message",
-                name="moderation_target_type",
-            ),
-            nullable=False,
-        ),
-        sa.Column("target_id", sa.String(length=64), nullable=True),
-        sa.Column(
-            "action",
-            postgresql.ENUM(
-                "warn", "suspend", "ban", "restrict", "remove", "restore",
-                name="moderation_action_type",
-            ),
-            nullable=False,
-        ),
-        sa.Column("reason", sa.Text(), nullable=True),
-        sa.Column("report_id", sa.Integer(), nullable=True),
-        sa.Column("expires_at", sa.DateTime(timezone=True), nullable=True),
-        sa.Column("revoked_at", sa.DateTime(timezone=True), nullable=True),
-        sa.Column(
-            "created_at",
-            sa.DateTime(timezone=True),
-            server_default=sa.func.now(),
-            nullable=False,
-        ),
-        sa.ForeignKeyConstraint(["moderator_id"], ["users.id"], ondelete="CASCADE"),
-        sa.ForeignKeyConstraint(
-            ["target_user_id"], ["users.id"], ondelete="CASCADE"
-        ),
-        sa.ForeignKeyConstraint(["report_id"], ["reports.id"], ondelete="SET NULL"),
-    )
-    op.create_index(
-        op.f("ix_moderation_actions_id"),
-        "moderation_actions",
-        ["id"],
-        unique=False,
-    )
-    op.create_index(
-        op.f("ix_moderation_actions_moderator_id"),
-        "moderation_actions",
-        ["moderator_id"],
-        unique=False,
-    )
-    op.create_index(
-        op.f("ix_moderation_actions_target_user_id"),
-        "moderation_actions",
-        ["target_user_id"],
-        unique=False,
-    )
-    op.create_index(
-        op.f("ix_moderation_actions_report_id"),
-        "moderation_actions",
-        ["report_id"],
-        unique=False,
-    )
-
-    # ── appeals table ───────────────────────────────────────────────────
-
-    op.create_table(
-        "appeals",
-        sa.Column("id", sa.BigInteger(), primary_key=True, autoincrement=True),
-        sa.Column(
-            "moderation_action_id", sa.Integer(), nullable=False
-        ),
-        sa.Column("user_id", sa.Integer(), nullable=False),
-        sa.Column("reason", sa.Text(), nullable=False),
-        sa.Column(
-            "status",
-            postgresql.ENUM(
-                "pending", "approved", "rejected", name="appeal_status"
-            ),
-            nullable=False,
-            server_default="pending",
-        ),
-        sa.Column("reviewed_by", sa.Integer(), nullable=True),
-        sa.Column("reviewed_at", sa.DateTime(timezone=True), nullable=True),
-        sa.Column(
-            "created_at",
-            sa.DateTime(timezone=True),
-            server_default=sa.func.now(),
-            nullable=False,
-        ),
-        sa.ForeignKeyConstraint(
-            ["moderation_action_id"],
-            ["moderation_actions.id"],
-            ondelete="CASCADE",
-        ),
-        sa.ForeignKeyConstraint(["user_id"], ["users.id"], ondelete="CASCADE"),
-        sa.ForeignKeyConstraint(
-            ["reviewed_by"], ["users.id"], ondelete="SET NULL"
-        ),
-    )
-    op.create_index(op.f("ix_appeals_id"), "appeals", ["id"], unique=False)
-    op.create_index(
-        op.f("ix_appeals_moderation_action_id"),
-        "appeals",
-        ["moderation_action_id"],
-        unique=False,
-    )
-    op.create_index(
-        op.f("ix_appeals_user_id"),
-        "appeals",
-        ["user_id"],
-        unique=False,
-    )
-    op.create_index(
-        op.f("ix_appeals_status"),
-        "appeals",
-        ["status"],
-        unique=False,
-    )
-
-
-def downgrade() -> None:
-    """Remove trust & safety tables and revert users table."""
-    op.drop_index(op.f("ix_appeals_status"), table_name="appeals")
-    op.drop_index(op.f("ix_appeals_user_id"), table_name="appeals")
-    op.drop_index(op.f("ix_appeals_moderation_action_id"), table_name="appeals")
-    op.drop_index(op.f("ix_appeals_id"), table_name="appeals")
-    op.drop_table("appeals")
-
-    op.drop_index(op.f("ix_moderation_actions_report_id"), table_name="moderation_actions")
-    op.drop_index(op.f("ix_moderation_actions_target_user_id"), table_name="moderation_actions")
-    op.drop_index(op.f("ix_moderation_actions_moderator_id"), table_name="moderation_actions")
-    op.drop_index(op.f("ix_moderation_actions_id"), table_name="moderation_actions")
-    op.drop_table("moderation_actions")
-
-    op.drop_index(op.f("ix_reports_status"), table_name="reports")
-    op.drop_index(op.f("ix_reports_reporter_id"), table_name="reports")
-    op.drop_index(op.f("ix_reports_id"), table_name="reports")
-    op.drop_table("reports")
-
-    op.drop_column("users", "suspended_until")
-    op.drop_column("users", "banned_until")
-    op.drop_column("users", "role")
-
-    # Drop ENUM types
-    postgresql.ENUM(name="appeal_status").drop(bind, checkfirst=True)
-    postgresql.ENUM(name="moderation_target_type").drop(bind, checkfirst=True)
-    postgresql.ENUM(name="moderation_action_type").drop(bind, checkfirst=True)
-    postgresql.ENUM(name="resolution").drop(bind, checkfirst=True)
-    postgresql.ENUM(name="report_status").drop(bind, checkfirst=True)
-    postgresql.ENUM(name="reason_category").drop(bind, checkfirst=True)
-    postgresql.ENUM(name="report_target_type").drop(bind, checkfirst=True)
-    postgresql.ENUM(name="user_role").drop(bind, checkfirst=True)

backend/app/config.py

@@ -30,6 +30,7 @@ class Settings(BaseSettings):
     # File uploads
     UPLOAD_DIR: str = "uploads"
     MAX_UPLOAD_SIZE_MB: int = 100
+    GLTF_MAX_FILE_SIZE_MB: int = 200
 
     model_config = SettingsConfigDict(
         env_file=".env",

backend/app/models/__init__.py

@@ -2,8 +2,5 @@ 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.report import Report
-from app.models.moderation_action import ModerationAction
-from app.models.appeal import Appeal
 
-__all__ = ["User", "Session", "World", "Asset", "Report", "ModerationAction", "Appeal"]
+__all__ = ["User", "Session", "World", "Asset"]

backend/app/models/appeal.py

@@ -1,47 +0,0 @@
-"""Appeal model for Trust & Safety."""
-
-from datetime import datetime
-from typing import Optional
-
-from sqlalchemy import (
-    Column,
-    Integer,
-    Text,
-    DateTime,
-    ForeignKey,
-)
-from sqlalchemy.dialects.postgresql import ENUM
-from sqlalchemy.orm import relationship
-from sqlalchemy.sql import func
-import enum
-
-from app.database import Base
-
-
-class AppealStatus(str, enum.Enum):
-    PENDING = "pending"
-    APPROVED = "approved"
-    REJECTED = "rejected"
-
-
-class Appeal(Base):
-    __tablename__ = "appeals"
-
-    id = Column(Integer, primary_key=True, autoincrement=True)
-    moderation_action_id = Column(
-        Integer, ForeignKey("moderation_actions.id", ondelete="CASCADE"), nullable=False
-    )
-    user_id = Column(Integer, ForeignKey("users.id", ondelete="CASCADE"), nullable=False)
-    reason = Column(Text, nullable=False)
-    status = Column(
-        ENUM(AppelStatus, name="appeal_status", create_type=False),
-        default=AppealStatus.PENDING,
-    )
-    reviewed_by = Column(Integer, ForeignKey("users.id", ondelete="SET NULL"), nullable=True)
-    reviewed_at = Column(DateTime(timezone=True), nullable=True)
-    created_at = Column(DateTime(timezone=True), server_default=func.now(), nullable=False)
-
-    # Relationships
-    moderation_action = relationship("ModerationAction", back_populates="appeals")
-    user = relationship("User", foreign_keys=[user_id])
-    reviewer = relationship("User", foreign_keys=[reviewed_by])

backend/app/models/moderation_action.py

@@ -1,63 +0,0 @@
-"""ModerationAction model for Trust & Safety."""
-
-from datetime import datetime
-from typing import Optional
-
-from sqlalchemy import (
-    Column,
-    Integer,
-    String,
-    Text,
-    DateTime,
-    ForeignKey,
-)
-from sqlalchemy.dialects.postgresql import ENUM
-from sqlalchemy.orm import relationship
-from sqlalchemy.sql import func
-import enum
-
-from app.database import Base
-
-
-class ModerationActionType(str, enum.Enum):
-    WARN = "warn"
-    SUSPEND = "suspend"
-    BAN = "ban"
-    RESTRICT = "restrict"
-    REMOVE = "remove"
-    RESTORE = "restore"
-
-
-class ModerationTargetType(str, enum.Enum):
-    USER = "user"
-    WORLD = "world"
-    ASSET = "asset"
-    CHAT_MESSAGE = "chat_message"
-
-
-class ModerationAction(Base):
-    __tablename__ = "moderation_actions"
-
-    id = Column(Integer, primary_key=True, autoincrement=True)
-    moderator_id = Column(Integer, ForeignKey("users.id", ondelete="CASCADE"), nullable=False)
-    target_user_id = Column(Integer, ForeignKey("users.id", ondelete="CASCADE"), nullable=True)
-    target_type = Column(
-        ENUM(ModerationTargetType, name="moderation_target_type", create_type=False),
-        nullable=False,
-    )
-    target_id = Column(String(64), nullable=True)
-    action = Column(
-        ENUM(ModerationActionType, name="moderation_action_type", create_type=False),
-        nullable=False,
-    )
-    reason = Column(Text, nullable=True)
-    report_id = Column(Integer, ForeignKey("reports.id", ondelete="SET NULL"), nullable=True)
-    expires_at = Column(DateTime(timezone=True), nullable=True)
-    revoked_at = Column(DateTime(timezone=True), nullable=True)
-    created_at = Column(DateTime(timezone=True), server_default=func.now(), nullable=False)
-
-    # Relationships
-    moderator = relationship("User", foreign_keys=[moderator_id])
-    target_user = relationship("User", foreign_keys=[target_user_id])
-    report = relationship("Report", foreign_keys=[report_id])
-    appeals = relationship("Appeal", back_populates="moderation_action", cascade="all, delete-orphan")

backend/app/models/report.py

@@ -1,88 +0,0 @@
-"""Report model for Trust & Safety."""
-
-from datetime import datetime
-from typing import Optional
-
-from sqlalchemy import (
-    Column,
-    Integer,
-    String,
-    Text,
-    DateTime,
-    ForeignKey,
-    UniqueConstraint,
-)
-from sqlalchemy.dialects.postgresql import ENUM
-from sqlalchemy.orm import relationship
-from sqlalchemy.sql import func
-import enum
-
-from app.database import Base
-
-
-class ReportTargetType(str, enum.Enum):
-    USER = "user"
-    WORLD = "world"
-    ASSET = "asset"
-    CHAT_MESSAGE = "chat_message"
-
-
-class ReasonCategory(str, enum.Enum):
-    HARASSMENT = "harassment"
-    HATE_SPEECH = "hate_speech"
-    SEXUAL_CONTENT = "sexual_content"
-    VIOLENCE = "violence"
-    SPAM = "spam"
-    SELF_HARM = "self_harm"
-    OTHER = "other"
-
-
-class ReportStatus(str, enum.Enum):
-    OPEN = "open"
-    IN_REVIEW = "in_review"
-    RESOLVED = "resolved"
-    DISMISSED = "dismissed"
-
-
-class Resolution(str, enum.Enum):
-    ACTION_TAKEN = "action_taken"
-    NO_ACTION = "no_action"
-    FALSE_POSITIVE = "false_positive"
-
-
-class Report(Base):
-    __tablename__ = "reports"
-
-    id = Column(Integer, primary_key=True, autoincrement=True)
-    reporter_id = Column(Integer, ForeignKey("users.id"), nullable=False)
-    target_type = Column(
-        ENUM(ReportTargetType, name="report_target_type", create_type=False),
-        nullable=False,
-    )
-    target_id = Column(String(64), nullable=False)
-    reason_category = Column(
-        ENUM(ReasonCategory, name="reason_category", create_type=False),
-        nullable=False,
-    )
-    details = Column(Text, nullable=True)
-    status = Column(
-        ENUM(ReportStatus, name="report_status", create_type=False),
-        default=ReportStatus.OPEN,
-    )
-    resolved_by = Column(Integer, ForeignKey("users.id"), nullable=True)
-    resolution = Column(
-        ENUM(Resolution, name="resolution", create_type=False),
-        nullable=True,
-    )
-    resolved_at = Column(DateTime(timezone=True), nullable=True)
-    created_at = Column(DateTime(timezone=True), server_default=func.now())
-    updated_at = Column(DateTime(timezone=True), onupdate=func.now())
-
-    # Relationships
-    reporter = relationship("User", foreign_keys=[reporter_id])
-    resolved_by_user = relationship("User", foreign_keys=[resolved_by])
-
-    __table_args__ = (
-        UniqueConstraint("reporter_id", "target_type", "target_id",
-                         name="uq_reporter_target"),
-    )

backend/app/models/user.py

@@ -1,20 +1,13 @@
 from datetime import date
 from typing import Optional
 
-from sqlalchemy import Column, Integer, String, Boolean, DateTime, Date, Enum
+from sqlalchemy import Column, Integer, String, Boolean, DateTime, Date
 from sqlalchemy.orm import relationship
 from sqlalchemy.sql import func
-import enum
 
 from app.database import Base
 
 
-class UserRole(str, enum.Enum):
-    USER = "user"
-    MODERATOR = "moderator"
-    ADMIN = "admin"
-
-
 class User(Base):
     __tablename__ = "users"
 
@@ -24,24 +17,12 @@ class User(Base):
     hashed_password = Column(String(255), nullable=False)
     date_of_birth = Column(Date, nullable=True)
     is_active = Column(Boolean, default=True)
-    role = Column(
-        Enum(UserRole, name="user_role"),
-        nullable=False,
-        server_default="user",
-    )
-    banned_until = Column(DateTime(timezone=True), nullable=True)
-    suspended_until = Column(DateTime(timezone=True), nullable=True)
     created_at = Column(DateTime(timezone=True), server_default=func.now())
     updated_at = Column(DateTime(timezone=True), onupdate=func.now())
 
     sessions = relationship("Session", back_populates="user", cascade="all, delete-orphan")
     worlds = relationship("World", back_populates="owner")
     assets = relationship("Asset", back_populates="owner")
-    reports_made = relationship("Report", foreign_keys="Report.reporter_id", back_populates="reporter")
-    reports_resolved = relationship("Report", foreign_keys="Report.resolved_by", back_populates="resolved_by_user")
-    moderation_actions_as_moderator = relationship("ModerationAction", foreign_keys="ModerationAction.moderator_id", back_populates="moderator")
-    moderation_actions_as_target = relationship("ModerationAction", foreign_keys="ModerationAction.target_user_id", back_populates="target_user")
-    appeals = relationship("Appeal", foreign_keys="Appeal.user_id", back_populates="user")
 
     @property
     def is_adult(self) -> bool:

backend/app/routers/assets.py

@@ -1,5 +1,6 @@
 """Asset management router."""
 
+import json
 import os
 from pathlib import Path
 from typing import Optional
@@ -13,6 +14,7 @@ from app.database import get_db
 from app.dependencies import CurrentUser
 from app.models.asset import Asset, AssetType
 from app.models.world import World
+from app.services import gltf as gltf_service
 from pydantic import BaseModel, Field
 
 router = APIRouter()
@@ -64,6 +66,14 @@ def _sanitize_filename(filename: str) -> str:
     return safe or "file"
 
 
+def _detect_asset_type(filename: Optional[str], content: bytes) -> AssetType:
+    """Detect the asset type from filename and content."""
+    if filename and gltf_service.looks_like_gltf(content, filename):
+        return AssetType.MODEL_3D
+    # Fallback: let the caller decide based on mime_type or default.
+    return AssetType.OTHER
+
+
 # --- Endpoints ---
 
 @router.post("/", response_model=AssetResponse, status_code=201)
@@ -183,10 +193,16 @@ async def upload_asset_file(
     # Sanitize filename to prevent path traversal.
     safe_filename = _sanitize_filename(file.filename or f"asset_{asset_id}")
 
-    # Validate file size against configured maximum.
+    # Read the file content.
-    max_bytes = settings.MAX_UPLOAD_SIZE_MB * 1024 * 1024
     content = await file.read()
     file_size = len(content)
+
+    # Determine which size limit to apply.
+    if gltf_service.looks_like_gltf(content, file.filename):
+        max_bytes = settings.GLTF_MAX_FILE_SIZE_MB * 1024 * 1024
+    else:
+        max_bytes = settings.MAX_UPLOAD_SIZE_MB * 1024 * 1024
+
     if file_size > max_bytes:
         raise HTTPException(
             status_code=413,
@@ -200,10 +216,28 @@ async def upload_asset_file(
     file_path = upload_dir / stored_name
     file_path.write_bytes(content)
 
+    # Detect asset type from content/filename.
+    detected_type = _detect_asset_type(file.filename, content)
+
+    # Update asset record.
     asset.file_path = str(file_path)
     asset.mime_type = file.content_type
     asset.file_size = file_size
 
+    # If this is a glTF file, extract and store metadata.
+    if detected_type == AssetType.MODEL_3D:
+        try:
+            metadata = gltf_service.extract_gltf_metadata(content)
+            asset.metadata_json = json.dumps(metadata)
+            # Also set the asset type to model_3d if it was auto-detected.
+            if asset.asset_type == AssetType.OTHER:
+                asset.asset_type = AssetType.MODEL_3D
+        except ValueError as exc:
+            raise HTTPException(
+                status_code=400,
+                detail=f"Invalid glTF file: {exc}",
+            )
+
     await db.commit()
     await db.refresh(asset)
     return asset

backend/app/services/gltf.py

@@ -0,0 +1,197 @@
+"""Lightweight glTF / GLB metadata extraction.
+
+This module intentionally avoids heavyweight dependencies such as trimesh or
+pygltflib. For the metadata fields the asset upload pipeline needs (mesh and
+vertex counts, animation presence, texture references, and the bounding box)
+a small amount of glTF-specific parsing is sufficient and keeps the backend
+dependency-free.
+"""
+
+from __future__ import annotations
+
+import json
+import struct
+from typing import Any, Optional
+
+# GLB binary header magic bytes ("glTF").
+_GLB_MAGIC = b"glTF"
+_GLB_MAGIC_INT = 0x46546C67  # b"glTF" interpreted as little-endian uint32
+_GLB_JSON_CHUNK_TYPE = 0x4E4F534A  # "JSON"
+_GLB_BIN_CHUNK_TYPE = 0x004E4942  # "BIN\0"
+
+# Whitespace allowed around a GLB JSON chunk. The spec pads with spaces (0x20),
+# but be lenient with null bytes and other whitespace that real exporters emit.
+_JSON_CHUNK_TRIM = b" \t\r\n\x00"
+
+
+def looks_like_gltf(content: bytes, filename: Optional[str] = None) -> bool:
+    """Return True when the bytes or filename indicate a glTF/GLB asset."""
+    if content.startswith(_GLB_MAGIC):
+        return True
+
+    if filename:
+        lowered = filename.lower()
+        if lowered.endswith(".gltf") or lowered.endswith(".glb"):
+            return True
+
+    # A bare JSON buffer (e.g. uploaded without an extension) that has the
+    # glTF asset marker is also a glTF file.
+    stripped = content.lstrip()
+    if stripped.startswith(b"{"):
+        try:
+            payload = json.loads(stripped.decode("utf-8"))
+        except (ValueError, UnicodeDecodeError):
+            return False
+        return isinstance(payload, dict) and "asset" in payload and "version" in payload.get("asset", {})
+
+    return False
+
+
+def _parse_glb(content: bytes) -> dict[str, Any]:
+    """Parse the JSON chunk of a GLB binary container."""
+    if len(content) < 12:
+        raise ValueError("GLB file is too short")
+
+    magic, _version, _length = struct.unpack_from("<III", content, 0)
+    if magic != _GLB_MAGIC_INT:
+        raise ValueError("invalid GLB magic")
+
+    offset = 12
+    json_chunk: Optional[dict[str, Any]] = None
+
+    while offset + 8 <= len(content):
+        chunk_length, chunk_type = struct.unpack_from("<II", content, offset)
+        offset += 8
+        chunk_end = offset + chunk_length
+        if chunk_end > len(content):
+            raise ValueError("GLB chunk overruns file boundary")
+
+        chunk_data = content[offset:chunk_end]
+        if chunk_type == _GLB_JSON_CHUNK_TYPE:
+            try:
+                json_chunk = json.loads(chunk_data.strip(_JSON_CHUNK_TRIM).decode("utf-8"))
+            except (ValueError, UnicodeDecodeError) as exc:
+                raise ValueError(f"invalid GLB JSON chunk: {exc}") from exc
+
+        offset = chunk_end
+
+    if json_chunk is None:
+        raise ValueError("GLB file does not contain a JSON chunk")
+
+    return json_chunk
+
+
+def _parse_gltf_json(content: bytes) -> dict[str, Any]:
+    """Parse a plain .gltf JSON file."""
+    stripped = content.lstrip()
+    try:
+        payload = json.loads(stripped.decode("utf-8"))
+    except (ValueError, UnicodeDecodeError) as exc:
+        raise ValueError(f"invalid glTF JSON: {exc}") from exc
+
+    if not isinstance(payload, dict):
+        raise ValueError("glTF JSON root must be an object")
+    return payload
+
+
+def _position_accessor_counts(gltf: dict[str, Any]) -> list[int]:
+    """Return POSITION accessor counts for every mesh primitive."""
+    counts: list[int] = []
+    accessors = gltf.get("accessors", [])
+    for mesh in gltf.get("meshes", []):
+        for primitive in mesh.get("primitives", []):
+            attributes = primitive.get("attributes", {})
+            position_index = attributes.get("POSITION")
+            if position_index is None:
+                continue
+            try:
+                accessor = accessors[int(position_index)]
+            except (IndexError, TypeError, ValueError):
+                continue
+            count = accessor.get("count")
+            if isinstance(count, int):
+                counts.append(count)
+    return counts
+
+
+def _position_bounds(gltf: dict[str, Any]) -> list[list[float]]:
+    """Return min/max bounds for every POSITION accessor that declares them."""
+    bounds: list[list[float]] = []
+    accessors = gltf.get("accessors", [])
+    for mesh in gltf.get("meshes", []):
+        for primitive in mesh.get("primitives", []):
+            attributes = primitive.get("attributes", {})
+            position_index = attributes.get("POSITION")
+            if position_index is None:
+                continue
+            try:
+                accessor = accessors[int(position_index)]
+            except (IndexError, TypeError, ValueError):
+                continue
+            minimum = accessor.get("min")
+            maximum = accessor.get("max")
+            if isinstance(minimum, list) and isinstance(maximum, list):
+                bounds.append([float(x) for x in minimum])
+                bounds.append([float(x) for x in maximum])
+    return bounds
+
+
+def _texture_refs(gltf: dict[str, Any]) -> list[str]:
+    """Collect external texture source references from the image array."""
+    refs: list[str] = []
+    for index, image in enumerate(gltf.get("images", [])):
+        uri = image.get("uri")
+        if isinstance(uri, str) and not uri.startswith("data:"):
+            refs.append(uri)
+            continue
+
+        name = image.get("name")
+        if isinstance(name, str) and name:
+            refs.append(name)
+            continue
+
+        if isinstance(uri, str):
+            # Embedded data URI; keep a stable, non-huge reference.
+            refs.append(f"data:{index}")
+            continue
+
+        buffer_view = image.get("bufferView")
+        if buffer_view is not None:
+            refs.append(f"bufferView:{buffer_view}")
+            continue
+
+        refs.append(f"image:{index}")
+
+    return refs
+
+
+def extract_gltf_metadata(content: bytes) -> dict[str, Any]:
+    """Extract upload-relevant metadata from glTF/GLB bytes.
+
+    Raises ValueError for malformed glTF content. The returned dict contains:
+        mesh_count, vertex_count, has_animation, texture_refs,
+        bounding_box_min, bounding_box_max.
+    """
+    if content.startswith(_GLB_MAGIC):
+        gltf = _parse_glb(content)
+    else:
+        gltf = _parse_gltf_json(content)
+
+    position_counts = _position_accessor_counts(gltf)
+    bounds = _position_bounds(gltf)
+
+    if bounds:
+        bounding_box_min = [min(axis) for axis in zip(*bounds[::2])]
+        bounding_box_max = [max(axis) for axis in zip(*bounds[1::2])]
+    else:
+        bounding_box_min = [0.0, 0.0, 0.0]
+        bounding_box_max = [0.0, 0.0, 0.0]
+
+    return {
+        "mesh_count": len(gltf.get("meshes", [])),
+        "vertex_count": sum(position_counts),
+        "has_animation": bool(gltf.get("animations")),
+        "texture_refs": _texture_refs(gltf),
+        "bounding_box_min": bounding_box_min,
+        "bounding_box_max": bounding_box_max,
+    }

backend/docker-compose.yml

@@ -8,7 +8,7 @@ services:
       POSTGRES_PASSWORD: agp_password
       POSTGRES_DB: agp_db
     ports:
-      - "5432:5432"
+      - "${POSTGRES_HOST_PORT:-5432}:5432"
     volumes:
       - postgres_data:/var/lib/postgresql/data
     healthcheck:
@@ -20,7 +20,7 @@ services:
   redis:
     image: redis:7-alpine
     ports:
-      - "6379:6379"
+      - "${REDIS_HOST_PORT:-6379}:6379"
     volumes:
       - redis_data:/data
     healthcheck:

backend/tests/test_gltf_metadata.py

@@ -0,0 +1,220 @@
+"""Tests for the lightweight glTF metadata extraction service."""
+
+import json
+import struct
+import pytest
+
+from app.services.gltf import (
+    extract_gltf_metadata,
+    looks_like_gltf,
+    _parse_glb,
+    _parse_gltf_json,
+)
+
+
+# ---------------------------------------------------------------------------
+# Test data helpers
+# ---------------------------------------------------------------------------
+
+def _make_gltf_json(
+    meshes: int = 1,
+    vertices_per_mesh: int = 24,
+    has_animations: bool = False,
+    images: list[dict] | None = None,
+) -> dict:
+    """Build a minimal glTF JSON structure."""
+    accessors = []
+    meshes_data = []
+    for i in range(meshes):
+        acc_index = len(accessors)
+        accessors.append({
+            "bufferView": 0,
+            "componentType": 5126,  # FLOAT
+            "count": vertices_per_mesh,
+            "type": "VEC3",
+            "max": [1.0, 1.0, 1.0],
+            "min": [-1.0, -1.0, -1.0],
+        })
+        meshes_data.append({
+            "primitives": [{
+                "attributes": {"POSITION": acc_index},
+            }],
+        })
+    gltf = {
+        "asset": {"version": "2.0"},
+        "accessors": accessors,
+        "meshes": meshes_data,
+    }
+    if has_animations:
+        gltf["animations"] = [{"name": "anim1", "channels": [], "samplers": []}]
+    if images:
+        gltf["images"] = images
+    return gltf
+
+
+def _make_glb(gltf_json: dict) -> bytes:
+    """Wrap *gltf_json* in a minimal GLB binary container."""
+    json_bytes = json.dumps(gltf_json).encode("utf-8")
+    json_length = len(json_bytes)
+    # Pad JSON chunk to 4-byte boundary.
+    json_padding = (4 - json_length % 4) % 4
+    json_chunk = json_bytes + b"\x00" * json_padding
+    json_chunk_type = 0x4E4F534A  # "JSON"
+    # No BIN chunk.
+    bin_length = 0
+    bin_chunk_type = 0x004E4942
+    total_length = 12 + 8 + len(json_chunk) + 8 + bin_length
+    header = struct.pack("<III", 0x46546C67, 2, total_length)  # magic, version, length
+    json_header = struct.pack("<II", len(json_chunk), json_chunk_type)
+    if bin_length > 0:
+        bin_header = struct.pack("<II", bin_length, bin_chunk_type)
+    else:
+        bin_header = b""
+    return header + json_header + json_chunk + bin_header
+
+
+# ---------------------------------------------------------------------------
+# looks_like_gltf
+# ---------------------------------------------------------------------------
+
+class TestLooksLikeGltf:
+    def test_glb_magic(self):
+        assert looks_like_gltf(b"glTF\x00\x00\x00\x00") is True
+
+    def test_gltf_extension(self):
+        assert looks_like_gltf(b'{"asset":{"version":"2.0"}}', "model.gltf") is True
+
+    def test_glb_extension(self):
+        assert looks_like_gltf(b"some binary", "model.glb") is True
+
+    def test_json_with_asset_version(self):
+        payload = json.dumps({"asset": {"version": "2.0"}}).encode()
+        assert looks_like_gltf(payload) is True
+
+    def test_plain_json_no_asset(self):
+        payload = json.dumps({"foo": "bar"}).encode()
+        assert looks_like_gltf(payload) is False
+
+    def test_non_json_bytes(self):
+        assert looks_like_gltf(b"\x89PNG\r\n\x1a\n") is False
+
+
+# ---------------------------------------------------------------------------
+# _parse_glb
+# ---------------------------------------------------------------------------
+
+class TestParseGlb:
+    def test_parses_valid_glb(self):
+        gltf_json = _make_gltf_json()
+        glb = _make_glb(gltf_json)
+        result = _parse_glb(glb)
+        assert result["asset"]["version"] == "2.0"
+        assert len(result["meshes"]) == 1
+
+    def test_rejects_too_short(self):
+        with pytest.raises(ValueError, match="too short"):
+            _parse_glb(b"glTF\x00\x00")
+
+    def test_rejects_invalid_magic(self):
+        with pytest.raises(ValueError, match="invalid GLB magic"):
+            _parse_glb(b"NOTglTF\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00")
+
+
+# ---------------------------------------------------------------------------
+# _parse_gltf_json
+# ---------------------------------------------------------------------------
+
+class TestParseGltfJson:
+    def test_parses_valid_gltf(self):
+        gltf_json = _make_gltf_json()
+        result = _parse_gltf_json(json.dumps(gltf_json).encode())
+        assert result["asset"]["version"] == "2.0"
+
+    def test_rejects_non_object(self):
+        with pytest.raises(ValueError, match="root must be an object"):
+            _parse_gltf_json(b"[1, 2, 3]")
+
+
+# ---------------------------------------------------------------------------
+# extract_gltf_metadata  (GLB path)
+# ---------------------------------------------------------------------------
+
+class TestExtractGltfMetadataGlb:
+    def test_basic_glb(self):
+        gltf_json = _make_gltf_json(meshes=1, vertices_per_mesh=24)
+        glb = _make_glb(gltf_json)
+        meta = extract_gltf_metadata(glb)
+        assert meta["mesh_count"] == 1
+        assert meta["vertex_count"] == 24
+        assert meta["has_animation"] is False
+        assert meta["bounding_box_min"] == [-1.0, -1.0, -1.0]
+        assert meta["bounding_box_max"] == [1.0, 1.0, 1.0]
+        assert meta["texture_refs"] == []
+
+    def test_multiple_meshes(self):
+        gltf_json = _make_gltf_json(meshes=3, vertices_per_mesh=12)
+        glb = _make_glb(gltf_json)
+        meta = extract_gltf_metadata(glb)
+        assert meta["mesh_count"] == 3
+        assert meta["vertex_count"] == 36
+
+    def test_with_animation(self):
+        gltf_json = _make_gltf_json(has_animations=True)
+        glb = _make_glb(gltf_json)
+        meta = extract_gltf_metadata(glb)
+        assert meta["has_animation"] is True
+
+    def test_with_external_texture(self):
+        gltf_json = _make_gltf_json(images=[{"uri": "textures/rock.png"}])
+        glb = _make_glb(gltf_json)
+        meta = extract_gltf_metadata(glb)
+        assert meta["texture_refs"] == ["textures/rock.png"]
+
+    def test_with_named_texture(self):
+        gltf_json = _make_gltf_json(images=[{"name": "my_texture"}])
+        glb = _make_glb(gltf_json)
+        meta = extract_gltf_metadata(glb)
+        assert meta["texture_refs"] == ["my_texture"]
+
+    def test_empty_meshes(self):
+        gltf_json = _make_gltf_json(meshes=0)
+        glb = _make_glb(gltf_json)
+        meta = extract_gltf_metadata(glb)
+        assert meta["mesh_count"] == 0
+        assert meta["vertex_count"] == 0
+        assert meta["bounding_box_min"] == [0.0, 0.0, 0.0]
+        assert meta["bounding_box_max"] == [0.0, 0.0, 0.0]
+
+
+# ---------------------------------------------------------------------------
+# extract_gltf_metadata  (plain .gltf JSON path)
+# ---------------------------------------------------------------------------
+
+class TestExtractGltfMetadataGltfJson:
+    def test_plain_gltf(self):
+        gltf_json = _make_gltf_json(meshes=2, vertices_per_mesh=8)
+        raw = json.dumps(gltf_json).encode()
+        meta = extract_gltf_metadata(raw)
+        assert meta["mesh_count"] == 2
+        assert meta["vertex_count"] == 16
+        assert meta["has_animation"] is False
+
+    def test_plain_gltf_with_animation(self):
+        gltf_json = _make_gltf_json(has_animations=True)
+        raw = json.dumps(gltf_json).encode()
+        meta = extract_gltf_metadata(raw)
+        assert meta["has_animation"] is True
+
+
+# ---------------------------------------------------------------------------
+# Error handling
+# ---------------------------------------------------------------------------
+
+class TestExtractGltfMetadataErrors:
+    def test_invalid_glb(self):
+        with pytest.raises(ValueError):
+            extract_gltf_metadata(b"not a glb")
+
+    def test_invalid_gltf_json(self):
+        with pytest.raises(ValueError):
+            _parse_gltf_json(b"[1, 2, 3]")