phase 3.1

backend/app/api/__init__.py

@@ -1,2 +1 @@
 """API endpoints."""
-

backend/app/api/auth.py

@@ -0,0 +1,110 @@
+"""Authentication endpoints."""
+from fastapi import APIRouter, Depends, HTTPException, status
+from sqlalchemy.orm import Session
+
+from app.auth.jwt import create_access_token
+from app.auth.repository import UserRepository
+from app.auth.schemas import TokenResponse, UserCreate, UserLogin, UserResponse
+from app.auth.security import validate_password_strength, verify_password
+from app.core.deps import get_current_user, get_db
+from app.database.models.user import User
+
+router = APIRouter(prefix="/auth", tags=["auth"])
+
+
+@router.post("/register", response_model=UserResponse, status_code=status.HTTP_201_CREATED)
+def register_user(user_data: UserCreate, db: Session = Depends(get_db)):
+    """
+    Register a new user.
+    
+    Args:
+        user_data: User registration data
+        db: Database session
+        
+    Returns:
+        Created user information
+        
+    Raises:
+        HTTPException: If email already exists or password is weak
+    """
+    repo = UserRepository(db)
+    
+    # Check if email already exists
+    if repo.email_exists(user_data.email):
+        raise HTTPException(
+            status_code=status.HTTP_409_CONFLICT,
+            detail="Email already registered"
+        )
+    
+    # Validate password strength
+    is_valid, error_message = validate_password_strength(user_data.password)
+    if not is_valid:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=error_message
+        )
+    
+    # Create user
+    user = repo.create_user(email=user_data.email, password=user_data.password)
+    
+    return UserResponse.from_orm(user)
+
+
+@router.post("/login", response_model=TokenResponse)
+def login_user(login_data: UserLogin, db: Session = Depends(get_db)):
+    """
+    Login user and return JWT token.
+    
+    Args:
+        login_data: Login credentials
+        db: Database session
+        
+    Returns:
+        JWT access token and user information
+        
+    Raises:
+        HTTPException: If credentials are invalid
+    """
+    repo = UserRepository(db)
+    
+    # Get user by email
+    user = repo.get_user_by_email(login_data.email)
+    
+    # Verify user exists and password is correct
+    if not user or not verify_password(login_data.password, user.password_hash):
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Incorrect email or password",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+    
+    # Check if user is active
+    if not user.is_active:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="User account is deactivated"
+        )
+    
+    # Create access token
+    access_token = create_access_token(user_id=user.id, email=user.email)
+    
+    return TokenResponse(
+        access_token=access_token,
+        token_type="bearer",
+        user=UserResponse.from_orm(user)
+    )
+
+
+@router.get("/me", response_model=UserResponse)
+def get_current_user_info(current_user: User = Depends(get_current_user)):
+    """
+    Get current authenticated user information.
+    
+    Args:
+        current_user: Current authenticated user (from JWT)
+        
+    Returns:
+        Current user information
+    """
+    return UserResponse.from_orm(current_user)
+

backend/app/auth/__init__.py

@@ -0,0 +1,2 @@
+"""Authentication module."""
+

backend/app/auth/jwt.py

@@ -0,0 +1,55 @@
+"""JWT token generation and validation."""
+from datetime import datetime, timedelta
+from typing import Optional
+from uuid import UUID
+
+from jose import JWTError, jwt
+
+from app.core.config import settings
+
+
+def create_access_token(user_id: UUID, email: str, expires_delta: Optional[timedelta] = None) -> str:
+    """
+    Create a new JWT access token.
+    
+    Args:
+        user_id: User's UUID
+        email: User's email address
+        expires_delta: Optional custom expiration time
+        
+    Returns:
+        Encoded JWT token string
+    """
+    if expires_delta:
+        expire = datetime.utcnow() + expires_delta
+    else:
+        expire = datetime.utcnow() + timedelta(minutes=settings.ACCESS_TOKEN_EXPIRE_MINUTES)
+    
+    to_encode = {
+        "sub": str(user_id),
+        "email": email,
+        "exp": expire,
+        "iat": datetime.utcnow(),
+        "type": "access"
+    }
+    
+    encoded_jwt = jwt.encode(to_encode, settings.SECRET_KEY, algorithm=settings.ALGORITHM)
+    return encoded_jwt
+
+
+def decode_access_token(token: str) -> Optional[dict]:
+    """
+    Decode and validate a JWT access token.
+    
+    Args:
+        token: JWT token string to decode
+        
+    Returns:
+        Decoded token payload if valid, None otherwise
+    """
+    try:
+        payload = jwt.decode(token, settings.SECRET_KEY, algorithms=[settings.ALGORITHM])
+        return payload
+    except JWTError:
+        return None
+

backend/app/auth/repository.py

@@ -0,0 +1,87 @@
+"""User repository for database operations."""
+from typing import Optional
+from uuid import UUID
+
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy.orm import Session
+
+from app.auth.security import hash_password
+from app.database.models.user import User
+
+
+class UserRepository:
+    """Repository for user database operations."""
+
+    def __init__(self, db: Session):
+        """
+        Initialize repository.
+        
+        Args:
+            db: Database session
+        """
+        self.db = db
+
+    def create_user(self, email: str, password: str) -> User:
+        """
+        Create a new user.
+        
+        Args:
+            email: User email (will be lowercased)
+            password: Plain text password (will be hashed)
+            
+        Returns:
+            Created user instance
+        """
+        email = email.lower()
+        password_hash = hash_password(password)
+        
+        user = User(
+            email=email,
+            password_hash=password_hash
+        )
+        
+        self.db.add(user)
+        self.db.commit()
+        self.db.refresh(user)
+        
+        return user
+
+    def get_user_by_email(self, email: str) -> Optional[User]:
+        """
+        Get user by email address.
+        
+        Args:
+            email: User email to search for
+            
+        Returns:
+            User if found, None otherwise
+        """
+        email = email.lower()
+        return self.db.query(User).filter(User.email == email).first()
+
+    def get_user_by_id(self, user_id: UUID) -> Optional[User]:
+        """
+        Get user by ID.
+        
+        Args:
+            user_id: User UUID
+            
+        Returns:
+            User if found, None otherwise
+        """
+        return self.db.query(User).filter(User.id == user_id).first()
+
+    def email_exists(self, email: str) -> bool:
+        """
+        Check if email already exists.
+        
+        Args:
+            email: Email to check
+            
+        Returns:
+            True if email exists, False otherwise
+        """
+        email = email.lower()
+        return self.db.query(User).filter(User.email == email).first() is not None
+

backend/app/auth/schemas.py

@@ -0,0 +1,45 @@
+"""Authentication schemas for request/response validation."""
+from datetime import datetime
+from typing import Optional
+from uuid import UUID
+
+from pydantic import BaseModel, EmailStr, Field
+
+
+class UserBase(BaseModel):
+    """Base user schema."""
+
+    email: EmailStr
+
+
+class UserCreate(UserBase):
+    """Schema for user registration."""
+
+    password: str = Field(..., min_length=8, max_length=100)
+
+
+class UserLogin(BaseModel):
+    """Schema for user login."""
+
+    email: EmailStr
+    password: str
+
+
+class UserResponse(UserBase):
+    """Schema for user response."""
+
+    id: UUID
+    created_at: datetime
+    is_active: bool
+
+    class Config:
+        from_attributes = True
+
+
+class TokenResponse(BaseModel):
+    """Schema for JWT token response."""
+
+    access_token: str
+    token_type: str = "bearer"
+    user: UserResponse
+

backend/app/auth/security.py

@@ -0,0 +1,65 @@
+"""Password hashing utilities using passlib."""
+import re
+from passlib.context import CryptContext
+
+# Create password context for hashing and verification
+pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")
+
+
+def hash_password(password: str) -> str:
+    """
+    Hash a password using bcrypt.
+    
+    Args:
+        password: Plain text password
+        
+    Returns:
+        Hashed password string
+    """
+    return pwd_context.hash(password)
+
+
+def verify_password(plain_password: str, hashed_password: str) -> bool:
+    """
+    Verify a plain password against a hashed password.
+    
+    Args:
+        plain_password: Plain text password to verify
+        hashed_password: Hashed password from database
+        
+    Returns:
+        True if password matches, False otherwise
+    """
+    return pwd_context.verify(plain_password, hashed_password)
+
+
+def validate_password_strength(password: str) -> tuple[bool, str]:
+    """
+    Validate password meets complexity requirements.
+    
+    Requirements:
+    - At least 8 characters
+    - At least 1 uppercase letter
+    - At least 1 lowercase letter
+    - At least 1 number
+    
+    Args:
+        password: Plain text password to validate
+        
+    Returns:
+        Tuple of (is_valid, error_message)
+    """
+    if len(password) < 8:
+        return False, "Password must be at least 8 characters long"
+    
+    if not re.search(r"[A-Z]", password):
+        return False, "Password must contain at least one uppercase letter"
+    
+    if not re.search(r"[a-z]", password):
+        return False, "Password must contain at least one lowercase letter"
+    
+    if not re.search(r"\d", password):
+        return False, "Password must contain at least one number"
+    
+    return True, ""
+

backend/app/core/deps.py

@@ -1,12 +1,84 @@
 """Dependency injection utilities."""
 
 from typing import Annotated, Generator
+from uuid import UUID
 
-from fastapi import Depends
+from fastapi import Depends, HTTPException, status
+from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
 from sqlalchemy.orm import Session
 
+from app.auth.jwt import decode_access_token
+from app.database.models.user import User
 from app.database.session import get_db
 
 # Database session dependency
 DatabaseSession = Annotated[Session, Depends(get_db)]
 
+# Security scheme for JWT Bearer token
+security = HTTPBearer()
+
+
+def get_current_user(
+    credentials: HTTPAuthorizationCredentials = Depends(security),
+    db: Session = Depends(get_db)
+) -> User:
+    """
+    Get current authenticated user from JWT token.
+    
+    Args:
+        credentials: HTTP Authorization Bearer token
+        db: Database session
+        
+    Returns:
+        Current authenticated user
+        
+    Raises:
+        HTTPException: If token is invalid or user not found
+    """
+    # Decode token
+    token = credentials.credentials
+    payload = decode_access_token(token)
+    
+    if payload is None:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Invalid authentication credentials",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+    
+    # Extract user ID from token
+    user_id_str: str = payload.get("sub")
+    if user_id_str is None:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Invalid token payload",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+    
+    try:
+        user_id = UUID(user_id_str)
+    except ValueError:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Invalid user ID in token",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+    
+    # Get user from database
+    user = db.query(User).filter(User.id == user_id).first()
+    
+    if user is None:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="User not found",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+    
+    if not user.is_active:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="User account is deactivated"
+        )
+    
+    return user
+

backend/app/database/models/__init__.py

@@ -1,5 +1,18 @@
 """Database models."""
+from app.database.models.user import User
+from app.database.models.board import Board
+from app.database.models.image import Image
+from app.database.models.board_image import BoardImage
+from app.database.models.group import Group
+from app.database.models.share_link import ShareLink
+from app.database.models.comment import Comment
 
-# Import all models here for Alembic autogenerate
-# Models will be created in separate phases
-
+__all__ = [
+    "User",
+    "Board",
+    "Image",
+    "BoardImage",
+    "Group",
+    "ShareLink",
+    "Comment",
+]

backend/app/database/models/board.py

@@ -0,0 +1,38 @@
+"""Board model for reference boards."""
+import uuid
+from datetime import datetime
+from sqlalchemy import Boolean, Column, DateTime, ForeignKey, String, Text
+from sqlalchemy.dialects.postgresql import JSONB, UUID
+from sqlalchemy.orm import relationship
+
+from app.database.base import Base
+
+
+class Board(Base):
+    """Board model representing a reference board."""
+
+    __tablename__ = "boards"
+
+    id = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    user_id = Column(UUID(as_uuid=True), ForeignKey("users.id", ondelete="CASCADE"), nullable=False, index=True)
+    title = Column(String(255), nullable=False)
+    description = Column(Text, nullable=True)
+    viewport_state = Column(
+        JSONB,
+        nullable=False,
+        default={"x": 0, "y": 0, "zoom": 1.0, "rotation": 0}
+    )
+    created_at = Column(DateTime, nullable=False, default=datetime.utcnow)
+    updated_at = Column(DateTime, nullable=False, default=datetime.utcnow, onupdate=datetime.utcnow)
+    is_deleted = Column(Boolean, nullable=False, default=False)
+
+    # Relationships
+    user = relationship("User", back_populates="boards")
+    board_images = relationship("BoardImage", back_populates="board", cascade="all, delete-orphan")
+    groups = relationship("Group", back_populates="board", cascade="all, delete-orphan")
+    share_links = relationship("ShareLink", back_populates="board", cascade="all, delete-orphan")
+    comments = relationship("Comment", back_populates="board", cascade="all, delete-orphan")
+
+    def __repr__(self) -> str:
+        return f"<Board(id={self.id}, title={self.title})>"
+

backend/app/database/models/board_image.py

@@ -0,0 +1,48 @@
+"""BoardImage junction model."""
+import uuid
+from datetime import datetime
+from sqlalchemy import Column, DateTime, ForeignKey, Integer, UniqueConstraint
+from sqlalchemy.dialects.postgresql import JSONB, UUID
+from sqlalchemy.orm import relationship
+
+from app.database.base import Base
+
+
+class BoardImage(Base):
+    """Junction table connecting boards and images with position/transformation data."""
+
+    __tablename__ = "board_images"
+
+    id = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    board_id = Column(UUID(as_uuid=True), ForeignKey("boards.id", ondelete="CASCADE"), nullable=False, index=True)
+    image_id = Column(UUID(as_uuid=True), ForeignKey("images.id", ondelete="CASCADE"), nullable=False, index=True)
+    position = Column(JSONB, nullable=False)
+    transformations = Column(
+        JSONB,
+        nullable=False,
+        default={
+            "scale": 1.0,
+            "rotation": 0,
+            "opacity": 1.0,
+            "flipped_h": False,
+            "flipped_v": False,
+            "greyscale": False
+        }
+    )
+    z_order = Column(Integer, nullable=False, default=0, index=True)
+    group_id = Column(UUID(as_uuid=True), ForeignKey("groups.id", ondelete="SET NULL"), nullable=True, index=True)
+    created_at = Column(DateTime, nullable=False, default=datetime.utcnow)
+    updated_at = Column(DateTime, nullable=False, default=datetime.utcnow, onupdate=datetime.utcnow)
+
+    __table_args__ = (
+        UniqueConstraint("board_id", "image_id", name="uq_board_image"),
+    )
+
+    # Relationships
+    board = relationship("Board", back_populates="board_images")
+    image = relationship("Image", back_populates="board_images")
+    group = relationship("Group", back_populates="board_images")
+
+    def __repr__(self) -> str:
+        return f"<BoardImage(board_id={self.board_id}, image_id={self.image_id})>"
+

backend/app/database/models/comment.py

@@ -0,0 +1,31 @@
+"""Comment model for board comments."""
+import uuid
+from datetime import datetime
+from sqlalchemy import Boolean, Column, DateTime, ForeignKey, String, Text
+from sqlalchemy.dialects.postgresql import JSONB, UUID
+from sqlalchemy.orm import relationship
+
+from app.database.base import Base
+
+
+class Comment(Base):
+    """Comment model for viewer comments on shared boards."""
+
+    __tablename__ = "comments"
+
+    id = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    board_id = Column(UUID(as_uuid=True), ForeignKey("boards.id", ondelete="CASCADE"), nullable=False, index=True)
+    share_link_id = Column(UUID(as_uuid=True), ForeignKey("share_links.id", ondelete="SET NULL"), nullable=True, index=True)
+    author_name = Column(String(100), nullable=False)
+    content = Column(Text, nullable=False)
+    position = Column(JSONB, nullable=True)  # Optional canvas position
+    created_at = Column(DateTime, nullable=False, default=datetime.utcnow)
+    is_deleted = Column(Boolean, nullable=False, default=False)
+
+    # Relationships
+    board = relationship("Board", back_populates="comments")
+    share_link = relationship("ShareLink", back_populates="comments")
+
+    def __repr__(self) -> str:
+        return f"<Comment(id={self.id}, author={self.author_name})>"
+

backend/app/database/models/group.py

@@ -0,0 +1,30 @@
+"""Group model for image grouping."""
+import uuid
+from datetime import datetime
+from sqlalchemy import Column, DateTime, ForeignKey, String, Text
+from sqlalchemy.dialects.postgresql import UUID
+from sqlalchemy.orm import relationship
+
+from app.database.base import Base
+
+
+class Group(Base):
+    """Group model for organizing images with annotations."""
+
+    __tablename__ = "groups"
+
+    id = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    board_id = Column(UUID(as_uuid=True), ForeignKey("boards.id", ondelete="CASCADE"), nullable=False, index=True)
+    name = Column(String(255), nullable=False)
+    color = Column(String(7), nullable=False)  # Hex color #RRGGBB
+    annotation = Column(Text, nullable=True)
+    created_at = Column(DateTime, nullable=False, default=datetime.utcnow)
+    updated_at = Column(DateTime, nullable=False, default=datetime.utcnow, onupdate=datetime.utcnow)
+
+    # Relationships
+    board = relationship("Board", back_populates="groups")
+    board_images = relationship("BoardImage", back_populates="group")
+
+    def __repr__(self) -> str:
+        return f"<Group(id={self.id}, name={self.name})>"
+

backend/app/database/models/image.py

@@ -0,0 +1,34 @@
+"""Image model for uploaded images."""
+import uuid
+from datetime import datetime
+from sqlalchemy import BigInteger, Column, DateTime, ForeignKey, Integer, String
+from sqlalchemy.dialects.postgresql import JSONB, UUID
+from sqlalchemy.orm import relationship
+
+from app.database.base import Base
+
+
+class Image(Base):
+    """Image model representing uploaded image files."""
+
+    __tablename__ = "images"
+
+    id = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    user_id = Column(UUID(as_uuid=True), ForeignKey("users.id", ondelete="CASCADE"), nullable=False, index=True)
+    filename = Column(String(255), nullable=False, index=True)
+    storage_path = Column(String(512), nullable=False)
+    file_size = Column(BigInteger, nullable=False)
+    mime_type = Column(String(100), nullable=False)
+    width = Column(Integer, nullable=False)
+    height = Column(Integer, nullable=False)
+    image_metadata = Column(JSONB, nullable=False)
+    created_at = Column(DateTime, nullable=False, default=datetime.utcnow)
+    reference_count = Column(Integer, nullable=False, default=0)
+
+    # Relationships
+    user = relationship("User", back_populates="images")
+    board_images = relationship("BoardImage", back_populates="image", cascade="all, delete-orphan")
+
+    def __repr__(self) -> str:
+        return f"<Image(id={self.id}, filename={self.filename})>"
+

backend/app/database/models/share_link.py

@@ -0,0 +1,32 @@
+"""ShareLink model for board sharing."""
+import uuid
+from datetime import datetime
+from sqlalchemy import Boolean, Column, DateTime, ForeignKey, Integer, String
+from sqlalchemy.dialects.postgresql import UUID
+from sqlalchemy.orm import relationship
+
+from app.database.base import Base
+
+
+class ShareLink(Base):
+    """ShareLink model for sharing boards with permission control."""
+
+    __tablename__ = "share_links"
+
+    id = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    board_id = Column(UUID(as_uuid=True), ForeignKey("boards.id", ondelete="CASCADE"), nullable=False, index=True)
+    token = Column(String(64), unique=True, nullable=False, index=True)
+    permission_level = Column(String(20), nullable=False)  # 'view-only' or 'view-comment'
+    created_at = Column(DateTime, nullable=False, default=datetime.utcnow)
+    expires_at = Column(DateTime, nullable=True)
+    last_accessed_at = Column(DateTime, nullable=True)
+    access_count = Column(Integer, nullable=False, default=0)
+    is_revoked = Column(Boolean, nullable=False, default=False, index=True)
+
+    # Relationships
+    board = relationship("Board", back_populates="share_links")
+    comments = relationship("Comment", back_populates="share_link")
+
+    def __repr__(self) -> str:
+        return f"<ShareLink(id={self.id}, token={self.token[:8]}...)>"
+

backend/app/database/models/user.py

@@ -0,0 +1,29 @@
+"""User model for authentication and ownership."""
+import uuid
+from datetime import datetime
+from sqlalchemy import Boolean, Column, DateTime, String
+from sqlalchemy.dialects.postgresql import UUID
+from sqlalchemy.orm import relationship
+
+from app.database.base import Base
+
+
+class User(Base):
+    """User model representing registered users."""
+
+    __tablename__ = "users"
+
+    id = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    email = Column(String(255), unique=True, nullable=False, index=True)
+    password_hash = Column(String(255), nullable=False)
+    created_at = Column(DateTime, nullable=False, default=datetime.utcnow)
+    updated_at = Column(DateTime, nullable=False, default=datetime.utcnow, onupdate=datetime.utcnow)
+    is_active = Column(Boolean, nullable=False, default=True)
+
+    # Relationships
+    boards = relationship("Board", back_populates="user", cascade="all, delete-orphan")
+    images = relationship("Image", back_populates="user", cascade="all, delete-orphan")
+
+    def __repr__(self) -> str:
+        return f"<User(id={self.id}, email={self.email})>"
+

backend/app/main.py

@@ -80,11 +80,13 @@ async def root():
     }
 
 
-# API routers will be added here in subsequent phases
-# Example:
-# from app.api import auth, boards, images
-# app.include_router(auth.router, prefix=f"{settings.API_V1_PREFIX}/auth", tags=["Auth"])
-# app.include_router(boards.router, prefix=f"{settings.API_V1_PREFIX}/boards", tags=["Boards"])
+# API routers
+from app.api import auth
+app.include_router(auth.router, prefix=f"{settings.API_V1_PREFIX}")
+# Additional routers will be added in subsequent phases
+# from app.api import boards, images
+# app.include_router(boards.router, prefix=f"{settings.API_V1_PREFIX}")
+# app.include_router(images.router, prefix=f"{settings.API_V1_PREFIX}")
 
 
 @app.on_event("startup")