feat: add user model and registration endpoint

backend/app/main.py

@@ -1,6 +1,21 @@
+from contextlib import asynccontextmanager
+
 from fastapi import FastAPI
 
-app = FastAPI(title="Quantumancy")
+import app.models  # noqa: F401 — registers models on Base.metadata before create_all
+from app.db import Base, engine
+from app.routes.auth import router as auth_router
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    async with engine.begin() as conn:
+        await conn.run_sync(Base.metadata.create_all)
+    yield
+
+
+app = FastAPI(title="Quantumancy", lifespan=lifespan)
+app.include_router(auth_router)
 
 
 @app.get("/healthz")

backend/app/models/__init__.py

@@ -0,0 +1,3 @@
+from app.models.user import User
+
+__all__ = ["User"]

backend/app/models/user.py

@@ -0,0 +1,19 @@
+import uuid
+from datetime import datetime, timezone
+
+from sqlalchemy import DateTime, String
+from sqlalchemy.orm import Mapped, mapped_column
+
+from app.db import Base
+
+
+class User(Base):
+    __tablename__ = "users"
+
+    id: Mapped[uuid.UUID] = mapped_column(primary_key=True, default=uuid.uuid4)
+    username: Mapped[str] = mapped_column(String(32), unique=True, index=True)
+    password_hash: Mapped[str] = mapped_column(String(255))
+    email: Mapped[str | None] = mapped_column(String(255), nullable=True)
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), default=lambda: datetime.now(timezone.utc)
+    )

backend/app/routes/auth.py

@@ -0,0 +1,27 @@
+from fastapi import APIRouter, Depends, HTTPException, status
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.db import get_db
+from app.models.user import User
+from app.schemas import RegisterRequest, UserOut
+from app.security import hash_password
+
+router = APIRouter(prefix="/auth", tags=["auth"])
+
+
+@router.post("/register", response_model=UserOut, status_code=status.HTTP_201_CREATED)
+async def register(payload: RegisterRequest, db: AsyncSession = Depends(get_db)):
+    existing = await db.scalar(select(User).where(User.username == payload.username))
+    if existing is not None:
+        raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail="username taken")
+
+    user = User(
+        username=payload.username,
+        password_hash=hash_password(payload.password),
+        email=payload.email,
+    )
+    db.add(user)
+    await db.commit()
+    await db.refresh(user)
+    return user

backend/app/schemas.py

@@ -0,0 +1,17 @@
+import uuid
+
+from pydantic import BaseModel, Field
+
+
+class RegisterRequest(BaseModel):
+    username: str = Field(min_length=3, max_length=32)
+    password: str = Field(min_length=8, max_length=128)
+    email: str | None = None
+
+
+class UserOut(BaseModel):
+    id: uuid.UUID
+    username: str
+
+    class Config:
+        from_attributes = True

backend/app/security.py

@@ -0,0 +1,15 @@
+from argon2 import PasswordHasher
+from argon2.exceptions import VerifyMismatchError
+
+_hasher = PasswordHasher()
+
+
+def hash_password(password: str) -> str:
+    return _hasher.hash(password)
+
+
+def verify_password(password: str, password_hash: str) -> bool:
+    try:
+        return _hasher.verify(password_hash, password)
+    except VerifyMismatchError:
+        return False