Recovered orphaned WIP before switching to a new task

Scaffolding only — FastAPI app, SQLAlchemy models, Alembic migrations,
and docker-compose from the original task description are still not
implemented. Committing what exists so it isn't lost; task ec0074121ca3
reset to pending to finish the rest.

backend/.env.example

@@ -0,0 +1,14 @@
+# Database
+DATABASE_URL=postgresql://agp_user:agp_password@localhost:5432/agp_db
+
+# Redis
+REDIS_URL=redis://localhost:6379/0
+
+# JWT
+SECRET_KEY=change-me-to-a-secure-random-string
+ALGORITHM=HS256
+ACCESS_TOKEN_EXPIRE_MINUTES=30
+
+# App
+DEBUG=true
+CORS_ORIGINS=http://localhost:8080,http://localhost:3000

backend/.gitignore

@@ -0,0 +1,4 @@
+.env
+__pycache__/
+*.pyc
+.venv/

backend/alembic.ini

@@ -0,0 +1,42 @@
+# Alembic configuration file.
+# Run: alembic upgrade head  (to apply migrations)
+# Run: alembic revision --autogenerate -m "description"  (to generate migration)
+
+[alembic]
+script_location = alembic
+prepend_sys_path = .
+sqlalchemy.url = postgresql+asyncpg://agp_user:agp_password@localhost:5432/agp_db
+
+[loggers]
+keys = root,sqlalchemy,alembic
+
+[handlers]
+keys = console
+
+[formatters]
+keys = generic
+
+[logger_root]
+level = WARN
+handlers = console
+qualname =
+
+[logger_sqlalchemy]
+level = WARN
+handlers =
+qualname = sqlalchemy.engine
+
+[logger_alembic]
+level = INFO
+handlers =
+qualname = alembic
+
+[handler_console]
+class = StreamHandler
+args = (sys.stderr,)
+level = NOTSET
+formatter = generic
+
+[formatter_generic]
+format = %(levelname)-5.5s [%(name)s] %(message)s
+datefmt = %H:%M:%S

backend/alembic/env.py

@@ -0,0 +1,65 @@
+"""Alembic environment configuration."""
+
+import asyncio
+from logging.config import fileConfig
+
+from alembic import context
+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
+
+# this is the Alembic Config object, which provides
+# access to the values within the .ini file in use.
+config = context.config
+
+# Interpret the config file for Python logging.
+# This line sets up loggers basically.
+if config.config_file_name is not None:
+    fileConfig(config.config_file_name)
+
+# add your model's MetaData object here
+# for 'autogenerate' support
+target_metadata = Base.metadata
+
+
+def run_migrations_offline() -> None:
+    """Run migrations in 'offline' mode."""
+    url = settings.DATABASE_URL
+    context.configure(
+        url=url,
+        target_metadata=target_metadata,
+        literal_binds=True,
+        dialect_opts={"paramstyle": "named"},
+    )
+
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+def do_run_migrations(connection):
+    context.configure(connection=connection, target_metadata=target_metadata)
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+async def run_async_migrations():
+    """Run migrations in 'online' mode with async engine."""
+    connectable = create_async_engine(settings.DATABASE_URL, echo=False)
+
+    async with connectable.connect() as connection:
+        await connection.run_sync(do_run_migrations)
+
+    await connectable.dispose()
+
+
+def run_migrations_online() -> None:
+    """Run migrations in 'online' mode."""
+    asyncio.run(run_async_migrations())
+
+
+if context.is_offline_mode():
+    run_migrations_offline()
+else:
+    run_migrations_online()

backend/app/config.py

@@ -0,0 +1,48 @@
+"""Application configuration via pydantic-settings."""
+
+from pydantic_settings import BaseSettings
+from functools import lru_cache
+
+
+class Settings(BaseSettings):
+    # App
+    APP_NAME: str = "AGP Backend"
+    APP_VERSION: str = "0.1.0"
+    DEBUG: bool = True
+
+    # Database (async)
+    DATABASE_URL: str = "postgresql+asyncpg://agp_user:agp_password@localhost:5432/agp_db"
+
+    # Redis
+    REDIS_URL: str = "redis://localhost:6379/0"
+
+    # JWT / Auth
+    SECRET_KEY: str = "change-me-to-a-secure-random-string"
+    ALGORITHM: str = "HS256"
+    ACCESS_TOKEN_EXPIRE_MINUTES: int = 30
+
+    # CORS
+    CORS_ORIGINS: str = "http://localhost:8080,http://localhost:3000"
+
+    # File uploads
+    UPLOAD_DIR: str = "uploads"
+    MAX_UPLOAD_SIZE_MB: int = 100
+
+    @property
+    def cors_origins_list(self) -> list[str]:
+        return [origin.strip() for origin in self.CORS_ORIGINS.split(",")]
+
+    class Config:
+        env_file = ".env"
+        env_file_encoding = "utf-8"
+        case_sensitive = True
+
+
+@lru_cache()
+def get_settings() -> Settings:
+    """Return cached settings instance."""
+    return Settings()
+
+
+# Convenience singleton
+settings = get_settings()

backend/app/database.py

@@ -0,0 +1,38 @@
+"""Async database engine and session factory."""
+
+from sqlalchemy.ext.asyncio import (
+    AsyncSession,
+    async_sessionmaker,
+    create_async_engine,
+)
+from sqlalchemy.orm import DeclarativeBase
+
+from app.config import settings
+
+engine = create_async_engine(
+    settings.database_url,
+    echo=settings.DEBUG,
+    pool_size=10,
+    max_overflow=20,
+)
+
+async_session_factory = async_sessionmaker(
+    engine,
+    class_=AsyncSession,
+    expire_on_commit=False,
+)
+
+
+class Base(DeclarativeBase):
+    pass
+
+
+async def get_db() -> AsyncSession:
+    """Dependency that yields an async database session."""
+    async with async_session_factory() as session:
+        try:
+            yield session
+            await session.commit()
+        except Exception:
+            await session.rollback()
+            raise

backend/app/main.py

@@ -0,0 +1,36 @@
+"""FastAPI application entry point."""
+
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI
+
+from app.config import settings
+from app.routers import auth, users, worlds, assets
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """Application lifespan: startup and shutdown events."""
+    # Startup: initialize database, connect to Redis, etc.
+    yield
+    # Shutdown: close connections, cleanup
+
+
+app = FastAPI(
+    title=settings.app_name,
+    version=settings.app_version,
+    description="Agentic Game Platform - Backend API",
+    lifespan=lifespan,
+)
+
+# Include routers
+app.include_router(auth.router, prefix="/api/auth", tags=["auth"])
+app.include_router(users.router, prefix="/api/users", tags=["users"])
+app.include_router(worlds.router, prefix="/api/worlds", tags=["worlds"])
+app.include_router(assets.router, prefix="/api/assets", tags=["assets"])
+
+
+@app.get("/api/health")
+async def health_check():
+    """Simple health check endpoint."""
+    return {"status": "ok", "app": settings.app_name}

backend/app/models/__init__.py

@@ -0,0 +1,6 @@
+from app.models.user import User
+from app.models.session import Session
+from app.models.world import World
+from app.models.asset import Asset
+
+__all__ = ["User", "Session", "World", "Asset"]

backend/app/models/asset.py

@@ -0,0 +1,36 @@
+from sqlalchemy import Column, Integer, String, ForeignKey, Text, DateTime, Enum as SAEnum
+from sqlalchemy.orm import relationship
+from sqlalchemy.sql import func
+import enum
+
+from app.database import Base
+
+
+class AssetType(str, enum.Enum):
+    IMAGE = "image"
+    AUDIO = "audio"
+    VIDEO = "video"
+    DOCUMENT = "document"
+    MODEL_3D = "model_3d"
+    OTHER = "other"
+
+
+class Asset(Base):
+    __tablename__ = "assets"
+
+    id = Column(Integer, primary_key=True, index=True)
+    name = Column(String(255), nullable=False)
+    description = Column(Text, nullable=True)
+    asset_type = Column(SAEnum(AssetType), nullable=False)
+    file_path = Column(String(512), nullable=False)
+    file_size = Column(Integer, nullable=True)
+    mime_type = Column(String(128), nullable=True)
+    metadata_json = Column(Text, nullable=True)
+    world_id = Column(Integer, ForeignKey("worlds.id"), nullable=True)
+    owner_id = Column(Integer, ForeignKey("users.id"), nullable=False)
+    is_public = Column(Integer, default=0, nullable=False)
+    created_at = Column(DateTime(timezone=True), server_default=func.now())
+    updated_at = Column(DateTime(timezone=True), server_default=func.now(), onupdate=func.now())
+
+    owner = relationship("User", back_populates="assets")
+    world = relationship("World", back_populates="assets")

backend/app/models/session.py

@@ -0,0 +1,18 @@
+from sqlalchemy import Column, String, DateTime, ForeignKey, Boolean
+from sqlalchemy.orm import relationship
+from sqlalchemy.sql import func
+from app.database import Base
+
+
+class Session(Base):
+    __tablename__ = "sessions"
+
+    id = Column(String, primary_key=True)
+    user_id = Column(String, ForeignKey("users.id", ondelete="CASCADE"), nullable=False)
+    token = Column(String, unique=True, index=True, nullable=False)
+    expires_at = Column(DateTime(timezone=True), nullable=False)
+    is_active = Column(Boolean, default=True)
+    created_at = Column(DateTime(timezone=True), server_default=func.now())
+    updated_at = Column(DateTime(timezone=True), server_default=func.now(), onupdate=func.now())
+
+    user = relationship("User", back_populates="sessions")

backend/app/models/user.py

@@ -0,0 +1,21 @@
+from sqlalchemy import Column, Integer, String, Boolean, DateTime
+from sqlalchemy.orm import relationship
+from sqlalchemy.sql import func
+
+from app.database import Base
+
+
+class User(Base):
+    __tablename__ = "users"
+
+    id = Column(Integer, primary_key=True, index=True)
+    username = Column(String(50), unique=True, index=True, nullable=False)
+    email = Column(String(120), unique=True, index=True, nullable=False)
+    hashed_password = Column(String(255), nullable=False)
+    is_active = Column(Boolean, default=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")

backend/app/models/world.py

@@ -0,0 +1,27 @@
+from sqlalchemy import Column, Integer, String, Text, DateTime, ForeignKey, Enum
+from sqlalchemy.orm import relationship
+from sqlalchemy.sql import func
+import enum
+
+from app.database import Base
+
+
+class WorldVisibility(enum.Enum):
+    PUBLIC = "public"
+    PRIVATE = "private"
+    FRIENDS_ONLY = "friends_only"
+
+
+class World(Base):
+    __tablename__ = "worlds"
+
+    id = Column(Integer, primary_key=True, index=True)
+    name = Column(String(255), nullable=False)
+    description = Column(Text, nullable=True)
+    owner_id = Column(Integer, ForeignKey("users.id"), nullable=False)
+    visibility = Column(Enum(WorldVisibility), default=WorldVisibility.PUBLIC)
+    created_at = Column(DateTime(timezone=True), server_default=func.now())
+    updated_at = Column(DateTime(timezone=True), onupdate=func.now())
+
+    owner = relationship("User", back_populates="worlds")
+    assets = relationship("Asset", back_populates="world", cascade="all, delete-orphan")

backend/app/routers/assets.py

@@ -0,0 +1,181 @@
+"""Asset management router."""
+
+from typing import Optional
+
+from fastapi import APIRouter, Depends, HTTPException, UploadFile, File, Query
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy.orm import selectinload
+
+from app.database import get_db
+from app.models.asset import Asset, AssetType
+from app.models.user import User
+from app.models.world import World
+from app.routers.worlds import get_current_user
+from pydantic import BaseModel, Field
+
+router = APIRouter()
+
+
+# --- Pydantic schemas ---
+
+class AssetCreate(BaseModel):
+    """Schema for creating an asset reference."""
+    name: str = Field(..., min_length=1, max_length=255)
+    description: Optional[str] = None
+    asset_type: AssetType
+    world_id: Optional[int] = None
+
+
+class AssetResponse(BaseModel):
+    """Schema for asset responses."""
+    id: int
+    name: str
+    description: Optional[str]
+    asset_type: AssetType
+    file_path: str
+    file_size: Optional[int]
+    mime_type: Optional[str]
+    world_id: Optional[int]
+    owner_id: int
+    is_public: bool
+    created_at: str
+    updated_at: str
+
+    class Config:
+        from_attributes = True
+
+
+class AssetUpdate(BaseModel):
+    """Schema for updating an asset."""
+    name: Optional[str] = None
+    description: Optional[str] = None
+    is_public: Optional[bool] = None
+
+
+# --- Endpoints ---
+
+@router.post("/", response_model=AssetResponse, status_code=201)
+async def create_asset(
+    payload: AssetCreate,
+    db: AsyncSession = Depends(get_db),
+    current_user: User = Depends(get_current_user),
+):
+    """Create a new asset reference."""
+    # Verify world ownership if world_id is provided
+    if payload.world_id is not None:
+        world = await db.get(World, payload.world_id)
+        if world is None:
+            raise HTTPException(status_code=404, detail="World not found")
+        if world.owner_id != current_user.id:
+            raise HTTPException(status_code=403, detail="Not owner of this world")
+
+    asset = Asset(
+        name=payload.name,
+        description=payload.description,
+        asset_type=payload.asset_type,
+        file_path="",  # Will be set after upload
+        owner_id=current_user.id,
+        world_id=payload.world_id,
+        is_public=False,
+    )
+    db.add(asset)
+    await db.commit()
+    await db.refresh(asset)
+    return asset
+
+
+@router.get("/", response_model=list[AssetResponse])
+async def list_assets(
+    world_id: Optional[int] = Query(None, description="Filter by world"),
+    asset_type: Optional[AssetType] = Query(None),
+    limit: int = Query(50, ge=1, le=100),
+    offset: int = Query(0, ge=0),
+    db: AsyncSession = Depends(get_db),
+    current_user: User = Depends(get_current_user),
+):
+    """List assets with optional filters."""
+    stmt = select(Asset).where(Asset.owner_id == current_user.id)
+
+    if world_id is not None:
+        stmt = stmt.where(Asset.world_id == world_id)
+    if asset_type is not None:
+        stmt = stmt.where(Asset.asset_type == asset_type)
+
+    stmt = stmt.order_by(Asset.created_at.desc()).limit(limit).offset(offset)
+    result = await db.execute(stmt)
+    assets = result.scalars().all()
+    return assets
+
+
+@router.get("/{asset_id}", response_model=AssetResponse)
+async def get_asset(
+    asset_id: int,
+    db: AsyncSession = Depends(get_db),
+    current_user: User = Depends(get_current_user),
+):
+    """Get a single asset by ID."""
+    asset = await db.get(Asset, asset_id)
+    if asset is None or asset.owner_id != current_user.id:
+        raise HTTPException(status_code=404, detail="Asset not found")
+    return asset
+
+
+@router.patch("/{asset_id}", response_model=AssetResponse)
+async def update_asset(
+    asset_id: int,
+    payload: AssetUpdate,
+    db: AsyncSession = Depends(get_db),
+    current_user: User = Depends(get_current_user),
+):
+    """Update an asset."""
+    asset = await db.get(Asset, asset_id)
+    if asset is None or asset.owner_id != current_user.id:
+        raise HTTPException(status_code=404, detail="Asset not found")
+
+    update_data = payload.model_dump(exclude_unset=True)
+    for field, value in update_data.items():
+        setattr(asset, field, value)
+
+    await db.commit()
+    await db.refresh(asset)
+    return asset
+
+
+@router.delete("/{asset_id}", status_code=204)
+async def delete_asset(
+    asset_id: int,
+    db: AsyncSession = Depends(get_db),
+    current_user: User = Depends(get_current_user),
+):
+    """Delete an asset."""
+    asset = await db.get(Asset, asset_id)
+    if asset is None or asset.owner_id != current_user.id:
+        raise HTTPException(status_code=404, detail="Asset not found")
+
+    await db.delete(asset)
+    await db.commit()
+
+
+@router.post("/{asset_id}/upload")
+async def upload_asset_file(
+    asset_id: int,
+    file: UploadFile = File(...),
+    db: AsyncSession = Depends(get_db),
+    current_user: User = Depends(get_current_user),
+):
+    """Upload a file for an existing asset."""
+    asset = await db.get(Asset, asset_id)
+    if asset is None or asset.owner_id != current_user.id:
+        raise HTTPException(status_code=404, detail="Asset not found")
+
+    # TODO: Implement actual file upload logic (S3, local filesystem, etc.)
+    file_path = f"uploads/{asset_id}_{file.filename}"
+    asset.file_path = file_path
+    asset.mime_type = file.content_type
+    asset.file_size = 0  # Will be updated after actual write
+
+    await db.commit()
+    await db.refresh(asset)
+
+    return {"message": "File upload endpoint", "asset_id": asset_id, "file_path": file_path}

backend/app/routers/auth.py

@@ -0,0 +1,133 @@
+"""Authentication router - login, register, token refresh."""
+
+from datetime import datetime, timedelta, timezone
+
+from fastapi import APIRouter, Depends, HTTPException, status
+from pydantic import BaseModel, EmailStr
+
+from jose import JWTError, jwt
+from passlib.context import CryptContext
+
+from app.config import settings
+from app.database import get_db
+from app.models.user import User
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy import select
+
+pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")
+
+router = APIRouter()
+
+
+# --- Pydantic schemas ---
+
+class TokenResponse(BaseModel):
+    access_token: str
+    token_type: str = "bearer"
+
+
+class RegisterRequest(BaseModel):
+    username: str
+    email: EmailStr
+    password: str
+
+
+class LoginRequest(BaseModel):
+    username: str
+    password: str
+
+
+# --- Helpers ---
+
+def _create_access_token(data: dict) -> str:
+    to_encode = data.copy()
+    expire = datetime.now(timezone.utc) + timedelta(
+        minutes=settings.ACCESS_TOKEN_EXPIRE_MINUTES
+    )
+    to_encode.update({"exp": expire})
+    return jwt.encode(to_encode, settings.SECRET_KEY, algorithm=settings.ALGORITHM)
+
+
+def verify_password(plain_password: str, hashed_password: str) -> bool:
+    """Verify a plain password against a hash."""
+    return pwd_context.verify(plain_password, hashed_password)
+
+
+def hash_password(password: str) -> str:
+    """Hash a password."""
+    return pwd_context.hash(password)
+
+
+# --- Endpoints ---
+
+@router.post("/register", response_model=TokenResponse, status_code=status.HTTP_201_CREATED)
+async def register(req: RegisterRequest, db: AsyncSession = Depends(get_db)):
+    """Register a new user and return an access token."""
+    # Check if username already exists
+    result = await db.execute(select(User).where(User.username == req.username))
+    if result.scalar_one_or_none():
+        raise HTTPException(
+            status_code=status.HTTP_409_CONFLICT,
+            detail="Username already registered",
+        )
+
+    # Check if email already exists
+    result = await db.execute(select(User).where(User.email == req.email))
+    if result.scalar_one_or_none():
+        raise HTTPException(
+            status_code=status.HTTP_409_CONFLICT,
+            detail="Email already registered",
+        )
+
+    user = User(
+        username=req.username,
+        email=req.email,
+        hashed_password=hash_password(req.password),
+    )
+    db.add(user)
+    await db.commit()
+    await db.refresh(user)
+
+    access_token = _create_access_token({"sub": str(user.id)})
+    return TokenResponse(access_token=access_token)
+
+
+@router.post("/login", response_model=TokenResponse)
+async def login(req: LoginRequest, db: AsyncSession = Depends(get_db)):
+    """Authenticate user and return an access token."""
+    result = await db.execute(select(User).where(User.username == req.username))
+    user = result.scalar_one_or_none()
+
+    if not user or not verify_password(req.password, user.hashed_password):
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Incorrect username or password",
+        )
+
+    if not user.is_active:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="User account is inactive",
+        )
+
+    access_token = _create_access_token({"sub": str(user.id)})
+    return TokenResponse(access_token=access_token)
+
+
+@router.get("/me")
+async def get_current_user(
+    user_id: int,
+    db: AsyncSession = Depends(get_db),
+):
+    """Get current user profile."""
+    result = await db.execute(select(User).where(User.id == user_id))
+    user = result.scalar_one_or_none()
+    if not user:
+        raise HTTPException(status_code=404, detail="User not found")
+    return {
+        "id": user.id,
+        "username": user.username,
+        "email": user.email,
+        "is_active": user.is_active,
+        "created_at": user.created_at,
+    }

backend/app/routers/users.py

@@ -0,0 +1,130 @@
+"""User management router."""
+
+from typing import Annotated
+
+from fastapi import APIRouter, Depends, HTTPException, status
+from pydantic import BaseModel, EmailStr
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.database import get_db
+from app.models.user import User
+
+router = APIRouter()
+
+
+# ── Pydantic schemas ──────────────────────────────────────────────────────
+
+class UserCreate(BaseModel):
+    username: str
+    email: EmailStr
+    password: str
+
+
+class UserResponse(BaseModel):
+    id: int
+    username: str
+    email: str
+    is_active: bool
+
+    model_config = {"from_attributes": True}
+
+
+class UserUpdate(BaseModel):
+    email: EmailStr | None = None
+    is_active: bool | None = None
+
+
+# ── Endpoints ─────────────────────────────────────────────────────────────
+
+@router.post(
+    "/",
+    response_model=UserResponse,
+    status_code=status.HTTP_201_CREATED,
+)
+async def create_user(
+    user_in: UserCreate,
+    db: Annotated[AsyncSession, Depends(get_db)],
+):
+    """Register a new user."""
+    # Check uniqueness of username
+    existing = await db.execute(select(User).where(User.username == user_in.username))
+    if existing.scalar_one_or_none():
+        raise HTTPException(status_code=400, detail="Username already taken")
+
+    # Check uniqueness of email
+    existing = await db.execute(select(User).where(User.email == user_in.email))
+    if existing.scalar_one_or_none():
+        raise HTTPException(status_code=400, detail="Email already registered")
+
+    from app.routers.auth import hash_password
+
+    hashed = hash_password(user_in.password)
+
+    user = User(
+        username=user_in.username,
+        email=user_in.email,
+        hashed_password=hashed,
+    )
+    db.add(user)
+    await db.commit()
+    await db.refresh(user)
+    return user
+
+
+@router.get("/me", response_model=UserResponse)
+async def get_current_user(
+    db: Annotated[AsyncSession, Depends(get_db)],
+    # current_user would come from JWT dependency in real usage
+):
+    """Get the currently authenticated user (placeholder)."""
+    raise HTTPException(status_code=501, detail="Not implemented")
+
+
+@router.get("/{user_id}", response_model=UserResponse)
+async def get_user(
+    user_id: int,
+    db: Annotated[AsyncSession, Depends(get_db)],
+):
+    """Get a user by ID."""
+    result = await db.execute(select(User).where(User.id == user_id))
+    user = result.scalar_one_or_none()
+    if not user:
+        raise HTTPException(status_code=404, detail="User not found")
+    return user
+
+
+@router.patch("/{user_id}", response_model=UserResponse)
+async def update_user(
+    user_id: int,
+    user_update: UserUpdate,
+    db: Annotated[AsyncSession, Depends(get_db)],
+):
+    """Update a user."""
+    result = await db.execute(select(User).where(User.id == user_id))
+    user = result.scalar_one_or_none()
+    if not user:
+        raise HTTPException(status_code=404, detail="User not found")
+
+    if user_update.email is not None:
+        user.email = user_update.email
+    if user_update.is_active is not None:
+        user.is_active = user_update.is_active
+
+    await db.commit()
+    await db.refresh(user)
+    return user
+
+
+@router.delete("/{user_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_user(
+    user_id: int,
+    db: Annotated[AsyncSession, Depends(get_db)],
+):
+    """Delete a user."""
+    result = await db.execute(select(User).where(User.id == user_id))
+    user = result.scalar_one_or_none()
+    if not user:
+        raise HTTPException(status_code=404, detail="User not found")
+    await db.delete(user)
+    await db.commit()

backend/app/routers/worlds.py

@@ -0,0 +1,151 @@
+"""Worlds router - CRUD for game worlds."""
+
+from typing import Annotated
+
+from fastapi import APIRouter, Depends, HTTPException, Query
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy.orm import selectinload
+
+from app.database import get_db
+from app.models.world import World, WorldVisibility
+
+router = APIRouter()
+
+
+async def get_current_user():
+    """Placeholder dependency for current user auth."""
+    # TODO: Implement JWT auth dependency
+    return {"id": 1, "username": "testuser", "email": "test@example.com"}
+
+
+@router.get("/")
+async def list_worlds(
+    skip: int = Query(0, ge=0),
+    limit: int = Query(50, ge=1, le=100),
+    visibility: WorldVisibility | None = None,
+    db: Annotated[AsyncSession, Depends(get_db)] = Depends(),
+):
+    """List worlds with optional visibility filter."""
+    query = select(World).options(selectinload(World.owner))
+    if visibility:
+        query = query.where(World.visibility == visibility)
+    query = query.offset(skip).limit(limit).order_by(World.created_at.desc())
+    result = await db.execute(query)
+    worlds = result.scalars().all()
+    return [
+        {
+            "id": w.id,
+            "name": w.name,
+            "description": w.description,
+            "visibility": w.visibility.value if w.visibility else None,
+            "owner_id": w.owner_id,
+            "created_at": w.created_at.isoformat() if w.created_at else None,
+        }
+        for w in worlds
+    ]
+
+
+@router.get("/{world_id}")
+async def get_world(
+    world_id: int,
+    db: Annotated[AsyncSession, Depends(get_db)] = Depends(),
+):
+    """Get a single world by ID."""
+    result = await db.execute(
+        select(World).where(World.id == world_id).options(selectinload(World.owner))
+    )
+    world = result.scalar_one_or_none()
+    if not world:
+        raise HTTPException(status_code=404, detail="World not found")
+    return {
+        "id": world.id,
+        "name": world.name,
+        "description": world.description,
+        "visibility": world.visibility.value if world.visibility else None,
+        "owner_id": world.owner_id,
+        "created_at": world.created_at.isoformat() if world.created_at else None,
+    }
+
+
+@router.post("/")
+async def create_world(
+    world_data: dict,
+    current_user=Depends(get_current_user),
+    db: Annotated[AsyncSession, Depends(get_db)] = Depends(),
+):
+    """Create a new world."""
+    name = world_data.get("name")
+    if not name:
+        raise HTTPException(status_code=400, detail="World name is required")
+
+    world = World(
+        name=name,
+        description=world_data.get("description"),
+        owner_id=current_user["id"],
+        visibility=WorldVisibility(
+            world_data.get("visibility", "public")
+        ),
+    )
+    db.add(world)
+    await db.commit()
+    await db.refresh(world)
+
+    return {
+        "id": world.id,
+        "name": world.name,
+        "description": world.description,
+        "visibility": world.visibility.value,
+        "owner_id": world.owner_id,
+        "created_at": world.created_at.isoformat() if world.created_at else None,
+    }
+
+
+@router.put("/{world_id}")
+async def update_world(
+    world_id: int,
+    world_data: dict,
+    current_user=Depends(get_current_user),
+    db: Annotated[AsyncSession, Depends(get_db)] = Depends(),
+):
+    """Update an existing world."""
+    result = await db.execute(select(World).where(World.id == world_id))
+    world = result.scalar_one_or_none()
+    if not world:
+        raise HTTPException(status_code=404, detail="World not found")
+
+    if world_data.get("name"):
+        world.name = world_data["name"]
+    if world_data.get("description") is not None:
+        world.description = world_data["description"]
+    if world_data.get("visibility"):
+        world.visibility = WorldVisibility(world_data["visibility"])
+
+    await db.commit()
+    await db.refresh(world)
+
+    return {
+        "id": world.id,
+        "name": world.name,
+        "description": world.description,
+        "visibility": world.visibility.value if world.visibility else None,
+        "owner_id": world.owner_id,
+        "created_at": world.created_at.isoformat() if world.created_at else None,
+    }
+
+
+@router.delete("/{world_id}")
+async def delete_world(
+    world_id: int,
+    current_user=Depends(get_current_user),
+    db: Annotated[AsyncSession, Depends(get_db)] = Depends(),
+):
+    """Delete a world."""
+    result = await db.execute(select(World).where(World.id == world_id))
+    world = result.scalar_one_or_none()
+    if not world:
+        raise HTTPException(status_code=404, detail="World not found")
+
+    await db.delete(world)
+    await db.commit()
+    return {"detail": "World deleted"}

backend/requirements.txt

@@ -0,0 +1,16 @@
+fastapi==0.115.6
+uvicorn[standard]==0.34.0
+sqlalchemy==2.0.36
+alembic==1.14.0
+psycopg2-binary==2.9.10
+redis==5.2.1
+pydantic==2.10.3
+pydantic-settings==2.7.0
+python-jose[cryptography]==3.3.0
+passlib[bcrypt]==1.7.4
+python-multipart==0.0.20
+email-validator==2.2.0
+httpx==0.28.1
+pytest==8.3.4
+pytest-asyncio==0.25.0
+pytest-cov==6.0.0

docs/architecture/avatar.md

@@ -0,0 +1,462 @@
+# Avatar Component System & glTF Attachment Spec
+
+> **Status:** Proposed
+> **Owner:** Platform team
+> **Related:** Server authority + client prediction, world chunk data format
+
+## 1. Overview
+
+This document specifies the **avatar component system** for **agp-game**, a
+Godot-based multiplayer game. It defines:
+
+- How an avatar is decomposed into **body parts** and **attachment slots**.
+- How **cosmetic attachments** (clothing, accessories, gear) mount onto the
+  base body.
+- The **glTF/GLB format requirements** that all avatar assets must satisfy so
+  they can be loaded, skinned, and networked consistently.
+
+The goal is a **modular, data-driven avatar pipeline**: a single base body rig
+plus swappable attachments, all authored in glTF and consumed by a shared Godot
+runtime. This enables player customization, cosmetic monetization, and
+server-authoritative validation of what a player is wearing.
+
+### 1.1 Design Goals
+
+- **Modularity:** Body parts and attachments are independent assets that can be
+  combined at runtime without re-exporting.
+- **Consistency:** A single, well-defined skeleton and slot convention so any
+  attachment fits any base body.
+- **Networkability:** The avatar's composition is expressed as a compact,
+  serializable **loadout** that the server can validate and replicate.
+- **Performance:** Attachments are skinned to the same skeleton and share
+  materials where possible to minimize draw calls and skinning cost.
+- **Tooling-friendly:** Assets are authored in standard glTF 2.0 and validated
+  by a build-time checker.
+
+---
+
+## 2. Avatar Decomposition
+
+### 2.1 The Base Body
+
+Every avatar is built on a **base body** — a single glTF asset containing:
+
+- A **skeleton** (the canonical rig, see §3).
+- A **base mesh** for the skin/body (head, torso, arms, legs).
+- **Attachment points** (empty nodes) that define where accessories mount.
+
+The base body is the only asset that carries the skeleton. Attachments reference
+the skeleton by **bone name** and are skinned to it; they never carry their own
+rig.
+
+### 2.2 Body Parts vs. Attachments
+
+Two distinct concepts:
+
+| Concept        | Definition                                                              | Example                          |
+|----------------|-------------------------------------------------------------------------|----------------------------------|
+| **Body part**  | A mesh that replaces part of the base body's skin (e.g., a different head, a tail, wings). | Alternate head, cybernetic arm |
+| **Attachment** | A mesh that mounts *on top of* the body without replacing it (clothing, accessories). | Shirt, hat, glasses, backpack |
+
+The distinction matters for **slot exclusivity** and **layering**:
+
+- **Body parts** are *exclusive* per slot — only one head can be equipped.
+- **Attachments** are *layered* — a hat and glasses can coexist, and both sit
+  above the head mesh.
+
+---
+
+## 3. Skeleton & Slot Convention
+
+### 3.1 Canonical Skeleton
+
+All avatars share a **canonical skeleton** with a fixed set of bone names. This
+is the contract that lets any attachment fit any body. The skeleton follows a
+humanoid convention (Godot's `Humanoid` profile / glTF VRM-style naming).
+
+Required bones (subset of the full rig):
+
+```
+Root
+├── Hips
+│   ├── Spine
+│   │   ├── Chest
+│   │   │   ├── Neck
+│   │   │   │   └── Head
+│   │   │   │       ├── HeadTop          # hat / hair mount
+│   │   │   │       ├── Jaw              # face accessories
+│   │   │   │       └── LeftEye / RightEye
+│   │   │   ├── LeftShoulder
+│   │   │   │   └── LeftUpperArm
+│   │   │   │       └── LeftLowerArm
+│   │   │   │           └── LeftHand
+│   │   │   └── RightShoulder
+│   │   │       └── RightUpperArm
+│   │   │           └── RightLowerArm
+│   │   │               └── RightHand
+│   │   └── (Chest children for torso attachments)
+│   ├── LeftUpperLeg
+│   │   └── LeftLowerLeg
+│   │       └── LeftFoot
+│   └── RightUpperLeg
+│       └── RightLowerLeg
+│           └── RightFoot
+```
+
+**Rules:**
+
+- Bone names are **case-sensitive** and must match exactly.
+- The skeleton is **T-pose** at rest for consistent skinning.
+- Attachments must be skinned to **at least** the bones they deform; static
+  accessories may be parented to a single bone (e.g., a hat parented to `Head`).
+
+### 3.2 Attachment Slots
+
+Slots are the **logical mount points** for body parts and attachments. Each slot
+maps to one or more bones and defines what can be equipped there.
+
+| Slot ID        | Category     | Mount bone(s)      | Exclusivity | Example assets                |
+|----------------|--------------|--------------------|-------------|-------------------------------|
+| `head`         | body part    | `Head`             | exclusive   | alternate head, face          |
+| `hair`         | attachment   | `HeadTop`          | exclusive   | hairstyles, hats              |
+| `face`         | attachment   | `Jaw`              | exclusive   | glasses, masks, beards        |
+| `torso`        | body part    | `Chest`            | exclusive   | alternate torso               |
+| `chest`        | attachment   | `Chest`            | exclusive   | shirts, armor, chest gear     |
+| `back`         | attachment   | `Chest` (back)     | exclusive   | backpacks, wings, capes       |
+| `left_arm`     | body part    | `LeftUpperArm`     | exclusive   | alternate arm                 |
+| `right_arm`    | body part    | `RightUpperArm`    | exclusive   | alternate arm                 |
+| `left_hand`    | attachment   | `LeftHand`         | exclusive   | gloves, weapons (held)        |
+| `right_hand`   | attachment   | `RightHand`        | exclusive   | gloves, weapons (held)        |
+| `legs`         | body part    | `Hips`             | exclusive   | alternate legs                |
+| `pants`        | attachment   | `Hips`             | exclusive   | pants, skirts                 |
+| `left_foot`    | attachment   | `LeftFoot`         | exclusive   | shoes                         |
+| `right_foot`   | attachment   | `RightFoot`        | exclusive   | shoes                         |
+| `accessory`    | attachment   | `Root` (free)      | multiple    | belts, jewelry, floating items|
+
+**Slot semantics:**
+
+- **`exclusive`** slots allow at most one equipped item at a time.
+- The **`accessory`** slot is *multi-slot* — multiple accessories may be equipped
+  simultaneously (bounded by a configurable limit, e.g., 8).
+- **Body-part slots** (`head`, `torso`, `legs`, `left_arm`, `right_arm`) replace
+  the corresponding base mesh. When a body part is equipped, the base mesh for
+  that region is hidden.
+- **Attachment slots** layer on top of the base mesh and never hide it.
+
+### 3.3 Slot → Bone Mapping
+
+Each slot declares a **primary mount bone** and an optional **secondary bone
+list** for skinning. The runtime uses this to:
+
+1. Parent static accessories to the mount bone.
+2. Skin skinned attachments to the union of the slot's bones.
+
+---
+
+## 4. glTF/GLB Format Requirements
+
+All avatar assets (base bodies, body parts, attachments) are distributed as
+**glTF 2.0** (`.gltf` + external buffers/textures) or **GLB** (`.glb`, binary
+container). GLB is the preferred distribution format for runtime loading.
+
+### 4.1 Required Conventions
+
+| Concern            | Requirement                                                                 |
+|--------------------|------------------------------------------------------------------------------|
+| **Format**         | glTF 2.0 (`.gltf` or `.glb`). GLB preferred for runtime.                     |
+| **Coordinate system** | glTF standard: **+Y up, +Z forward, right-handed**. Godot converts to its own convention on import. |
+| **Units**          | Meters. Avatar height ~1.8 m at the `Root` bone.                              |
+| **Skeleton**       | Single skeleton per asset; bone names per §3.1.                              |
+| **Skinning**       | `skins` + `nodes` with `JOINTS_0` / `WEIGHTS_0` accessors.                    |
+| **Pose**           | T-pose at rest.                                                              |
+| **Materials**      | PBR metallic-roughness. Use `KHR_materials_unlit` for emissive/UI-only items. |
+| **Textures**       | Max 2048×2048; power-of-two preferred. Use `KHR_texture_basisu` (BasisU) for runtime. |
+| **Animation**      | Optional. If present, must not rename or remove canonical bones.             |
+
+### 4.2 Asset Metadata (extras)
+
+Each asset **must** declare its slot and identity in the glTF `asset.extras`
+object. This is the machine-readable contract consumed by the build pipeline and
+runtime.
+
+```json
+{
+  "asset": {
+    "version": "2.0",
+    "extras": {
+      "agp": {
+        "type": "attachment",          // "base_body" | "body_part" | "attachment"
+        "slot": "chest",               // slot ID from §3.2
+        "id": "shirt_bandit_01",       // globally unique asset id
+        "display_name": "Bandit Shirt",
+        "version": "1.0.0",
+        "mount_bone": "Chest",         // primary mount bone
+        "skin_bones": ["Chest", "Spine", "LeftUpperArm", "RightUpperArm"],
+        "exclusive": true,             // matches slot exclusivity
+        "tags": ["cloth", "common"],
+        "author": "platform-team"
+      }
+    }
+  }
+}
+```
+
+**Validation rules for `extras.agp`:**
+
+- `type` must be one of `base_body`, `body_part`, `attachment`.
+- `slot` must be a known slot ID (§3.2).
+- `mount_bone` must exist in the canonical skeleton.
+- `skin_bones` must all exist in the canonical skeleton.
+- `exclusive` must match the slot's declared exclusivity.
+- `id` must be unique across the asset catalog.
+
+### 4.3 Node Naming Convention
+
+To make assets self-describing and mergeable, nodes follow a convention:
+
+- **Base body:** the mesh node is named `Body`; the skeleton root is `Root`.
+- **Body part:** the mesh node is named `<SlotID>_Mesh` (e.g., `head_Mesh`).
+- **Attachment:** the mesh node is named `<SlotID>_<AssetID>` (e.g.,
+  `chest_shirt_bandit_01`).
+- **Attachment points** (empty nodes) on the base body are named
+  `attach_<slot>` (e.g., `attach_head`, `attach_left_hand`).
+
+### 4.4 Material & Texture Requirements
+
+- All materials use the **metallic-roughness** PBR model.
+- Textures are embedded in the GLB or referenced as external files; external
+  references must be relative paths within the asset package.
+- **Color customization** is supported via a `baseColorFactor` tint applied at
+  runtime (multiplied over the albedo). Assets should use a neutral albedo
+  (white/gray) where tinting is intended.
+- **Masked/transparent** materials must set the correct alpha mode
+  (`MASK` or `BLEND`) and `alphaCutoff`.
+
+### 4.5 Skeleton Merging at Runtime
+
+When an attachment is loaded, the runtime **merges** it onto the base body:
+
+1. Load the base body (skeleton + base meshes).
+2. Load each equipped attachment.
+3. For each attachment, **re-target its skin** to the base body's skeleton by
+   bone name (no re-export needed).
+4. Parent static accessories to their `mount_bone`.
+5. Hide base meshes for any equipped body-part slots.
+6. Apply material tints and merge into the render tree.
+
+The merge is **name-based** — bone names must match exactly (§3.1). This is the
+core reason for the strict naming contract.
+
+---
+
+## 5. Loadout Model (Network & Persistence)
+
+The avatar's composition is serialized as a **loadout** — a compact, ordered
+list of equipped asset IDs. This is what the server validates, persists, and
+replicates.
+
+### 5.1 Loadout JSON
+
+```json
+{
+  "base_body": "base_human_male_01",
+  "slots": {
+    "head":   "head_cyber_01",
+    "hair":   "hair_mohawk_01",
+    "face":   null,
+    "torso":  null,
+    "chest":  "chest_bandit_01",
+    "back":   "backpack_01",
+    "left_arm":  null,
+    "right_arm": null,
+    "left_hand": "glove_leather_01",
+    "right_hand": "glove_leather_01",
+    "legs":   null,
+    "pants":  "pants_cargo_01",
+    "left_foot":  "shoe_boot_01",
+    "right_foot": "shoe_boot_01",
+    "accessory": ["belt_01", "necklace_01"]
+  }
+}
+```
+
+**Rules:**
+
+- `base_body` is required and must reference a valid `base_body` asset.
+- Each exclusive slot holds **at most one** asset id (or `null`).
+- `accessory` is an array (0..N, bounded).
+- The server validates that every id exists in the catalog and that slot
+  exclusivity is respected.
+
+### 5.2 Network Replication
+
+The loadout is replicated as part of the player's spawn/state data:
+
+```
+spawn_entity:
+  entity_id: uint32
+  type: player
+  transform: { x, y, rot }
+  props:
+    loadout_hash: uint32      # hash of the loadout for change detection
+    loadout: { ... }          # full loadout on spawn / on change
+```
+
+- The **full loadout** is sent on spawn and whenever it changes (reliable).
+- A **`loadout_hash`** lets clients skip re-resolving assets if unchanged.
+- The server is the **authority** on the loadout; clients send *requests* to
+  change equipment, and the server validates and broadcasts the result.
+
+### 5.3 Server-Side Validation
+
+The server rejects a loadout if:
+
+- `base_body` is missing or unknown.
+- Any slot references an unknown asset id.
+- An exclusive slot has more than one item.
+- An asset's declared `slot` does not match the slot it is placed in.
+- The accessory list exceeds the configured limit.
+- The asset is not owned/unlocked by the player (for gated cosmetics).
+
+---
+
+## 6. Godot Runtime Architecture
+
+### 6.1 Node Structure
+
+```
+Avatar (Node3D)
+├── Skeleton3D            # canonical skeleton (from base body)
+├── BodyMeshes            # base body meshes (skinned to Skeleton3D)
+│   ├── head_Mesh
+│   ├── torso_Mesh
+│   └── ...
+├── Attachments           # equipped attachments
+│   ├── chest_shirt_bandit_01
+│   ├── hair_mohawk_01
+│   └── ...
+└── AttachmentPoints      # empty nodes for dynamic mounting
+    ├── attach_head
+    ├── attach_left_hand
+    └── ...
+```
+
+### 6.2 Core Classes
+
+| Class                    | Responsibility                                              |
+|--------------------------|-------------------------------------------------------------|
+| `AvatarSystem`           | Loads base body + attachments, resolves loadouts, owns the avatar node. |
+| `AvatarLoader`           | glTF/GLB import, skeleton merge, skin re-targeting.          |
+| `AvatarSlotRegistry`     | Static registry of slot definitions (id, bones, exclusivity).|
+| `AvatarLoadout`          | Serializable loadout model + validation.                    |
+| `AvatarCatalog`          | Asset catalog (id → asset metadata + resource path).         |
+| `AvatarVisualizer`       | Builds the render tree from a loadout.                      |
+
+### 6.3 Loading Pipeline
+
+```
+loadout JSON
+   │
+   ▼
+AvatarCatalog.resolve(loadout)   # id → asset metadata + GLB path
+   │
+   ▼
+AvatarLoader.load_base_body()    # import GLB, extract skeleton + base meshes
+   │
+   ▼
+for each equipped slot:
+   AvatarLoader.load_attachment()# import GLB, re-target skin to skeleton
+   │
+   ▼
+AvatarVisualizer.assemble()      # parent, hide replaced parts, apply tints
+   │
+   ▼
+Avatar node ready for render
+```
+
+### 6.4 Performance Considerations
+
+- **Shared skeleton:** All meshes skin to one `Skeleton3D`, so skinning is
+  computed once per frame.
+- **Material batching:** Attachments that share a material are merged into a
+  single mesh where possible (static accessories).
+- **LOD:** Optional LOD variants per asset; the runtime selects based on
+  distance.
+- **Caching:** Resolved loadouts and imported GLB resources are cached by
+  `AvatarCatalog` to avoid re-importing on respawn or re-join.
+
+---
+
+## 7. Asset Pipeline & Validation
+
+### 7.1 Build-Time Validation
+
+A build-time checker validates every asset before it enters the catalog:
+
+1. **Format check:** valid glTF 2.0 / GLB.
+2. **Metadata check:** `extras.agp` present and valid (§4.2).
+3. **Skeleton check:** all `skin_bones` exist in the canonical skeleton.
+4. **Slot check:** `slot` is known and `exclusive` matches.
+5. **Mesh check:** meshes are skinned (or static accessories parented to a bone).
+6. **Texture check:** sizes, formats, and alpha modes are valid.
+7. **Uniqueness check:** `id` is unique.
+
+### 7.2 Catalog Manifest
+
+The catalog is a JSON manifest mapping asset ids to metadata and resource paths:
+
+```json
+{
+  "assets": {
+    "base_human_male_01": {
+      "type": "base_body",
+      "path": "res://assets/avatars/base_human_male_01.glb",
+      "version": "1.0.0"
+    },
+    "chest_bandit_01": {
+      "type": "attachment",
+      "slot": "chest",
+      "path": "res://assets/avatars/chest_bandit_01.glb",
+      "version": "1.0.0"
+    }
+  }
+}
+```
+
+---
+
+## 8. Security & Anti-Cheat
+
+- **Server-authoritative loadouts:** Clients only *request* equipment changes;
+  the server validates against the catalog and the player's owned items.
+- **No client asset injection:** Clients cannot send arbitrary GLB data; they
+  reference catalog ids only.
+- **Rate limiting:** Equipment-change requests are rate-limited per peer.
+- **Hash verification:** The `loadout_hash` lets the server detect tampered or
+  stale loadout state.
+
+---
+
+## 9. Open Questions / Future Work
+
+- **Morph targets / blendshapes:** Support for facial expressions and body
+  morphs (e.g., height, muscle) via glTF morph targets.
+- **Physics attachments:** Cloth simulation for capes/skirts (Godot cloth).
+- **Dynamic tinting UI:** A color-picker that writes `baseColorFactor` tints.
+- **VRM compatibility:** Consider supporting VRM (a glTF extension for
+  humanoid avatars) as an import source.
+- **Attachment LOD streaming:** Streaming high-res attachments on demand.
+
+---
+
+## 10. Summary
+
+| Concern                | Decision                                              |
+|------------------------|-------------------------------------------------------|
+| Format                 | glTF 2.0 / GLB (GLB preferred for runtime)            |
+| Skeleton               | Single canonical humanoid skeleton, name-based merge  |
+| Slots                  | Fixed slot registry; exclusive body parts + layered attachments |
+| Loadout                | Compact JSON; server-authoritative and validated      |
+| Replication            | Full loadout on spawn/change + `loadout_hash`         |
+| Runtime                | Godot `Skeleton3D` + name-based skin re-targeting     |
+| Validation             | Build-time asset checker + runtime catalog validation |

docs/architecture/networking.md

@@ -0,0 +1,286 @@
+# Multiplayer Networking Architecture
+
+> **Status:** Proposed
+> **Owner:** Platform team
+> **Related:** Server authority + client prediction
+
+## 1. Overview
+
+This document specifies the multiplayer networking architecture for **agp-game**,
+a Godot-based game built by autonomous agents. The architecture follows a
+**server-authoritative model with client-side prediction and reconciliation**,
+which is the industry standard for fast-paced, competitive multiplayer games.
+
+The goals of this architecture are:
+
+- **Fairness & anti-cheat:** The server is the single source of truth for all
+  gameplay state. Clients never directly mutate world state.
+- **Responsiveness:** Client-side prediction hides network latency so local input
+  feels immediate.
+- **Determinism:** The server runs a fixed-timestep simulation so that state is
+  reproducible and testable.
+- **Scalability:** A clear separation between transport, simulation, and
+  replication layers allows the server to be tuned independently.
+
+---
+
+## 2. Transport Choice: ENet over WebSocket
+
+### 2.1 Decision
+
+We choose **ENet** as the primary transport for gameplay traffic.
+
+### 2.2 Justification
+
+| Criterion            | ENet                                   | WebSocket (TCP)                     |
+|----------------------|----------------------------------------|-------------------------------------|
+| **Reliability model**| Reliable + unreliable channels         | Reliable only (TCP)                 |
+| **Latency**          | Low; unreliable packets skip retransmit| Head-of-line blocking on loss       |
+| **Packet ordering**  | Per-channel ordering                   | Global strict ordering              |
+| **Congestion control**| Lightweight, game-oriented            | TCP-style (slow start, backoff)     |
+| **Godot support**    | First-class (`ENetConnection`, `MultiplayerPeerENet`) | Supported but TCP-based |
+| **Use case fit**     | Real-time action game                  | Chat, lobby, HTTP-style messaging   |
+
+**Rationale:**
+
+- **Movement & state replication** are latency-sensitive and tolerate occasional
+  packet loss. ENet's *unreliable* channel lets us send position snapshots at high
+  frequency without head-of-line blocking.
+- **RPCs that must be delivered** (e.g., interactions, spawns) use ENet's
+  *reliable* channel, giving us exactly the semantics we need without TCP's
+  retransmission stalls.
+- Godot's `MultiplayerPeerENet` is mature and integrates directly with the
+  high-level multiplayer API (`MultiplayerAPI`, `rpc()`).
+
+### 2.3 WebSocket as a Secondary Transport
+
+WebSocket remains available as a **secondary transport** for:
+
+- **Lobby / matchmaking** messaging (low-frequency, must-be-reliable).
+- **Browser builds** where raw UDP/ENet is unavailable.
+- **Admin / telemetry** channels.
+
+The transport layer is abstracted behind an interface so gameplay code does not
+depend on the underlying protocol.
+
+---
+
+## 3. Server-Side Game Loop
+
+### 3.1 Tick Rate
+
+- **Simulation tick rate:** **30 Hz** (33.33 ms per tick).
+- **Replication / snapshot rate:** **30 Hz**, aligned with the simulation tick.
+
+**Justification:**
+
+- 30 Hz is sufficient for smooth movement and interaction in a top-down / 2D
+  action game while keeping CPU and bandwidth costs predictable.
+- A fixed timestep (rather than delta-time) makes the simulation deterministic
+  and testable.
+- The tick rate is a **configuration constant** so it can be raised (e.g., to
+  60 Hz) for competitive modes without architectural changes.
+
+### 3.2 Authority Model
+
+- **Server is authoritative** for:
+  - Player position, velocity, and physics state.
+  - Health, damage, and death.
+  - Item pickups, inventory, and world-object state.
+  - Spawning and despawning of entities.
+  - Game rules, scoring, and win/lose conditions.
+- **Client is authoritative** for:
+  - Its own *input* (which keys/buttons are pressed).
+  - Local camera and UI.
+  - Cosmetic / non-gameplay presentation.
+
+### 3.3 Server Loop Pseudocode
+
+```
+while server_running:
+    process_network_inbound()      # read client inputs & RPCs
+    for _ in range(ticks_to_advance):
+        simulate_tick()            # fixed 30 Hz step
+    broadcast_snapshots()          # replicate authoritative state
+    process_network_outbound()     # flush reliable/unreliable channels
+```
+
+The server accumulates real elapsed time and advances the simulation in fixed
+`TICK_DURATION` increments, decoupling simulation from frame rate.
+
+---
+
+## 4. RPC Call Patterns
+
+RPCs are grouped by direction and reliability. All gameplay RPCs are routed
+through the high-level `MultiplayerAPI` with explicit `rpc_id` targeting.
+
+### 4.1 Client → Server (Input & Requests)
+
+| RPC                          | Channel   | Payload                                   | Notes |
+|------------------------------|-----------|-------------------------------------------|-------|
+| `request_move_input`         | unreliable| `{ seq, input_state, timestamp }`         | Batched per tick; drives prediction |
+| `request_interact`           | reliable  | `{ target_id }`                           | Open door, pick up item, use object |
+| `request_attack`             | reliable  | `{ target_id, aim_dir }`                  | Combat action |
+| `request_join`               | reliable  | `{ player_name, profile }`                | Session setup |
+| `request_respawn`            | reliable  | `{}`                                      | After death |
+
+**Design notes:**
+
+- **Input is batched** per client tick and sent with a monotonically increasing
+  `seq` so the server can detect gaps and the client can reconcile.
+- **Interactions are reliable** because they are discrete, must-happen events
+  (opening a door, picking up an item). Losing them would corrupt world state.
+
+### 4.2 Server → Client (State & Events)
+
+| RPC                          | Channel   | Payload                                   | Notes |
+|------------------------------|-----------|-------------------------------------------|-------|
+| `snapshot_state`             | unreliable| `{ tick, entities[], player_states[] }`   | Periodic authoritative state |
+| `spawn_entity`               | reliable  | `{ entity_id, type, transform, props }`   | New entity enters world |
+| `despawn_entity`             | reliable  | `{ entity_id, reason }`                   | Entity removed |
+| `interact_result`            | reliable  | `{ request_seq, success, result }`        | Acknowledges interaction |
+| `damage_event`               | reliable  | `{ target_id, amount, source_id }`        | Combat feedback |
+| `game_event`                 | reliable  | `{ type, payload }`                       | Score, win, round start/end |
+
+### 4.3 Broadcast vs. Targeted
+
+- **Broadcast (all clients):** `snapshot_state`, `spawn_entity`,
+  `despawn_entity`, `game_event`.
+- **Targeted (single client):** `interact_result`, `damage_event` (to affected
+  players), and any player-private data.
+
+---
+
+## 5. Client-Side Prediction & Reconciliation
+
+### 5.1 Prediction
+
+- The client runs a **local copy of the movement simulation** using the same
+  physics constants as the server.
+- When the player provides input, the client:
+  1. Applies the input to its local player immediately.
+  2. Renders the predicted position.
+  3. Sends the input to the server (batched, with `seq`).
+
+### 5.2 Reconciliation
+
+- The server sends authoritative `snapshot_state` at 30 Hz containing the
+  server's tick number and authoritative player positions.
+- The client keeps a **ring buffer of predicted states** keyed by input `seq`.
+- On receiving a snapshot:
+  1. Find the last predicted state that matches the server's tick.
+  2. Compute the **error** between predicted and authoritative position.
+  3. If error exceeds a threshold, **snap or smoothly interpolate** the local
+     player to the authoritative position (error correction).
+  4. Re-simulate any inputs that occurred after the server's tick (rollback).
+
+### 5.3 Interpolation of Remote Entities
+
+- **Local player:** predicted + reconciled (see above).
+- **Remote players / entities:** rendered with **interpolation delay** of
+  `2 × TICK_DURATION` (≈ 66 ms) to smooth out snapshot jitter.
+- The client buffers the last N snapshots and interpolates between them.
+
+### 5.4 Prediction Buffer Sizing
+
+- Buffer size is adaptive based on measured RTT.
+- Default: hold up to `ceil(RTT / TICK_DURATION) + 2` predicted states.
+
+---
+
+## 6. Entity & World State Replication
+
+### 6.1 Entity Model
+
+Every networked entity has:
+
+- A globally unique `entity_id` (server-assigned).
+- An `EntityType` (player, enemy, item, projectile, door, ...).
+- A `Transform` (position, rotation).
+- A typed `props` dictionary of gameplay state (health, state machine, etc.).
+
+### 6.2 Snapshot Format
+
+```
+snapshot_state:
+  tick: uint32
+  entities:
+    - entity_id: uint32
+      type: uint8
+      transform: { x, y, rot }
+      props: { ... }        # delta-encoded where possible
+  player_states:
+    - peer_id: int
+      entity_id: uint32
+      health: int
+      state: uint8
+```
+
+### 6.3 Delta Compression
+
+- Only **changed** entity fields are sent per snapshot (dirty-flag per entity).
+- Static or unchanged entities are omitted from the snapshot.
+- This keeps bandwidth proportional to *activity*, not world size.
+
+---
+
+## 7. Connection & Session Lifecycle
+
+1. **Connect:** Client opens an ENet connection to the server.
+2. **Authenticate / Join:** Client sends `request_join`; server validates and
+   assigns a `peer_id` and spawns the player entity.
+3. **Spawn:** Server broadcasts `spawn_entity` for the new player to all clients.
+4. **Play:** Input → prediction → server simulation → snapshot → reconciliation.
+5. **Disconnect:** Server removes the player entity, broadcasts `despawn_entity`,
+   and cleans up session state.
+
+---
+
+## 8. Security & Anti-Cheat
+
+- **No client-authoritative gameplay values.** Clients only send *inputs* and
+  *requests*; the server computes all outcomes.
+- **Input validation:** Server clamps movement speed, rejects out-of-bounds
+  positions, and validates interaction targets.
+- **Rate limiting:** Per-peer input and RPC rate limits prevent flooding.
+- **Sequence validation:** Gaps or replays in input `seq` are detected and
+  rejected.
+
+---
+
+## 9. Testing & Determinism
+
+- The simulation is a **pure function of (state, inputs, tick)** so it can be
+  unit-tested headlessly.
+- A **replay system** records inputs and can re-simulate to verify server and
+  client produce identical results.
+- Network code is tested with a **mock transport** that can inject latency,
+  jitter, and packet loss.
+
+---
+
+## 10. Open Questions / Future Work
+
+- **Interest management / spatial partitioning:** For large worlds, restrict
+  snapshots to entities near each client (AOI culling).
+- **Server-side physics:** Decide whether to use Godot's physics server on the
+  host or a custom deterministic physics step.
+- **Dedicated server vs. listen server:** The architecture supports both; a
+  dedicated headless server is the target for production.
+- **WebSocket fallback:** Implement the transport abstraction for browser builds.
+
+---
+
+## 11. Summary
+
+| Concern                | Decision                                        |
+|------------------------|-------------------------------------------------|
+| Transport              | ENet (primary), WebSocket (secondary)           |
+| Tick rate              | 30 Hz fixed timestep                            |
+| Authority              | Server-authoritative; client sends input only   |
+| Prediction             | Client-side prediction + reconciliation         |
+| Remote interpolation   | 2-tick interpolation delay                      |
+| Replication            | Delta-compressed snapshots at 30 Hz             |
+| Interaction RPCs       | Reliable channel                                |
+| Movement input         | Unreliable channel, batched with sequence       |