Initial deployment

.dockerignore

@@ -0,0 +1,45 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+env/
+venv/
+ENV/
+.venv
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+*.cover
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Environment
+.env
+.env.local
+.env.*.local
+
+# Database
+*.db
+*.sqlite
+
+# Logs
+*.log
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Alembic
+alembic/versions/*.pyc
+
+# Documentation
+docs/_build/

.env

@@ -0,0 +1,13 @@
+# Database Configuration
+# For local PostgreSQL: postgresql://user:password@localhost:5432/todo_db
+# For Neon: Use your Neon connection string from the dashboard
+DATABASE_URL=postgresql://neondb_owner:npg_MmFvJBHT8Y0k@ep-silent-thunder-ab0rbvrp-pooler.eu-west-2.aws.neon.tech/neondb?sslmode=require&channel_binding=require
+# Application Settings
+APP_NAME=Task CRUD API
+DEBUG=True
+CORS_ORIGINS=http://localhost:3000
+
+# Authentication
+BETTER_AUTH_SECRET=zMdW1P03wJvWJnLKzQ8YYO26vHeinqmR
+JWT_ALGORITHM=HS256
+JWT_EXPIRATION_DAYS=7

.env.example

@@ -0,0 +1,12 @@
+# Database Configuration
+DATABASE_URL=postgresql://user:password@host:5432/database
+
+# Application Settings
+APP_NAME=Task CRUD API
+DEBUG=True
+CORS_ORIGINS=http://localhost:3000
+
+# Authentication (Placeholder for Spec 2)
+# JWT_SECRET=your-secret-key-here
+# JWT_ALGORITHM=HS256
+# JWT_EXPIRATION_MINUTES=1440

Dockerfile

@@ -0,0 +1,26 @@
+# Use Python 3.11 slim image
+FROM python:3.11-slim
+
+# Set working directory
+WORKDIR /app
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y \
+    gcc \
+    postgresql-client \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy requirements first for better caching
+COPY requirements.txt .
+
+# Install Python dependencies
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy application code
+COPY . .
+
+# Expose port 7860 (Hugging Face Spaces default)
+EXPOSE 7860
+
+# Run database migrations and start the application
+CMD alembic upgrade head && uvicorn src.main:app --host 0.0.0.0 --port 7860

README.md

@@ -1,11 +1,309 @@
----
-title: Taskflow Api
-emoji: 🦀
-colorFrom: green
-colorTo: indigo
-sdk: docker
-pinned: false
-license: mit
----
-
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Task CRUD API - Backend
+
+FastAPI backend for the Task Manager application with full CRUD operations, filtering, and sorting.
+
+## Tech Stack
+
+- **Python**: 3.11+
+- **FastAPI**: 0.104+ (Web framework)
+- **SQLModel**: 0.0.14+ (ORM)
+- **Alembic**: 1.13.0 (Database migrations)
+- **PostgreSQL**: Neon Serverless or local PostgreSQL
+- **Pydantic**: 2.x (Data validation)
+
+## Project Structure
+
+```
+backend/
+├── src/
+│   ├── api/
+│   │   ├── deps.py           # Dependency injection (DB session, auth stub)
+│   │   └── routes/
+│   │       └── tasks.py      # Task CRUD endpoints
+│   ├── core/
+│   │   ├── config.py         # Application settings
+│   │   └── database.py       # Database connection
+│   ├── models/
+│   │   ├── user.py           # User model (stub)
+│   │   └── task.py           # Task model
+│   ├── schemas/
+│   │   └── task.py           # Pydantic schemas
+│   ├── services/
+│   │   └── task_service.py   # Business logic
+│   └── main.py               # FastAPI application
+├── alembic/
+│   ├── versions/
+│   │   └── 001_initial.py    # Initial migration
+│   └── env.py                # Alembic configuration
+├── tests/                     # Test directory (to be implemented)
+├── .env                       # Environment variables
+├── .env.example               # Environment template
+├── alembic.ini                # Alembic configuration
+└── requirements.txt           # Python dependencies
+```
+
+## Setup Instructions
+
+### 1. Install Dependencies
+
+```bash
+cd backend
+pip install -r requirements.txt
+```
+
+### 2. Configure Environment
+
+Copy `.env.example` to `.env` and configure:
+
+```bash
+cp .env.example .env
+```
+
+Edit `.env`:
+
+```env
+# For Neon PostgreSQL (recommended)
+DATABASE_URL=postgresql://user:password@ep-xxx.neon.tech/dbname?sslmode=require
+
+# OR for local PostgreSQL
+DATABASE_URL=postgresql://postgres:postgres@localhost:5432/todo_db
+
+APP_NAME=Task CRUD API
+DEBUG=True
+CORS_ORIGINS=http://localhost:3000
+
+# Authentication (REQUIRED)
+BETTER_AUTH_SECRET=<generate-32-char-random-string>
+JWT_ALGORITHM=HS256
+JWT_EXPIRATION_DAYS=7
+```
+
+**Generate BETTER_AUTH_SECRET:**
+```bash
+# Use Python to generate a secure random secret
+python -c "import secrets; print(secrets.token_urlsafe(32))"
+
+# IMPORTANT: Use the SAME secret in both backend/.env and frontend/.env.local
+```
+
+### 3. Run Database Migrations
+
+```bash
+# Apply migrations to create tables
+python -m alembic upgrade head
+```
+
+### 4. Start Development Server
+
+```bash
+# Start with auto-reload
+uvicorn src.main:app --reload
+
+# Server runs at http://localhost:8000
+```
+
+## API Endpoints
+
+### Authentication
+
+| Method | Endpoint | Description | Auth Required |
+|--------|----------|-------------|---------------|
+| POST | `/api/auth/signup` | Register new user account | No |
+| POST | `/api/auth/signin` | Authenticate and receive JWT token | No |
+| GET | `/api/auth/me` | Get current user profile | Yes |
+
+### Tasks
+
+| Method | Endpoint | Description | Auth Required |
+|--------|----------|-------------|---------------|
+| GET | `/api/tasks` | List tasks with filtering and sorting | Yes |
+| POST | `/api/tasks` | Create a new task | Yes |
+| GET | `/api/tasks/{id}` | Get a single task | Yes |
+| PUT | `/api/tasks/{id}` | Update task (replace all fields) | Yes |
+| PATCH | `/api/tasks/{id}` | Partially update task | Yes |
+| DELETE | `/api/tasks/{id}` | Delete a task | Yes |
+
+### Query Parameters (GET /api/tasks)
+
+- `completed`: Filter by status (true/false/null for all)
+- `sort`: Sort field (created_at or updated_at)
+- `order`: Sort order (asc or desc)
+- `limit`: Maximum number of results
+- `offset`: Number of results to skip
+
+### Example Requests
+
+**Sign Up:**
+```bash
+curl -X POST http://localhost:8000/api/auth/signup \
+  -H "Content-Type: application/json" \
+  -d '{
+    "email": "user@example.com",
+    "password": "SecurePass123",
+    "name": "John Doe"
+  }'
+```
+
+**Sign In:**
+```bash
+curl -X POST http://localhost:8000/api/auth/signin \
+  -H "Content-Type: application/json" \
+  -d '{
+    "email": "user@example.com",
+    "password": "SecurePass123"
+  }'
+```
+
+**Get Current User (requires JWT token):**
+```bash
+curl http://localhost:8000/api/auth/me \
+  -H "Authorization: Bearer <your-jwt-token>"
+```
+
+**Create Task (requires JWT token):**
+```bash
+curl -X POST http://localhost:8000/api/tasks \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer <your-jwt-token>" \
+  -d '{"title": "Buy groceries", "description": "Milk, eggs, bread"}'
+```
+
+**List Active Tasks:**
+```bash
+curl "http://localhost:8000/api/tasks?completed=false&sort=created_at&order=desc" \
+  -H "Authorization: Bearer <your-jwt-token>"
+```
+
+**Toggle Completion:**
+```bash
+curl -X PATCH http://localhost:8000/api/tasks/1 \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer <your-jwt-token>" \
+  -d '{"completed": true}'
+```
+
+## API Documentation
+
+Interactive API documentation available at:
+- **Swagger UI**: http://localhost:8000/docs
+- **ReDoc**: http://localhost:8000/redoc
+
+## Database Schema
+
+### Tasks Table
+
+| Column | Type | Description |
+|--------|------|-------------|
+| id | INTEGER | Primary key |
+| user_id | INTEGER | Foreign key to users |
+| title | VARCHAR(200) | Task title (required) |
+| description | VARCHAR(1000) | Task description (optional) |
+| completed | BOOLEAN | Completion status |
+| created_at | DATETIME | Creation timestamp |
+| updated_at | DATETIME | Last update timestamp |
+
+**Indexes:**
+- `ix_tasks_user_id` - User lookup
+- `ix_tasks_completed` - Status filtering
+- `ix_tasks_user_id_completed` - Combined user + status
+- `ix_tasks_created_at` - Date sorting
+
+## Authentication
+
+**Status**: JWT-based authentication with Better Auth integration
+
+### Authentication Flow
+
+1. **User Registration** (`POST /api/auth/signup`):
+   - Validates email format (RFC 5322)
+   - Validates password strength (min 8 chars, uppercase, lowercase, number)
+   - Hashes password with bcrypt (cost factor 12)
+   - Creates user account in database
+   - Returns user profile (no token issued)
+
+2. **User Sign In** (`POST /api/auth/signin`):
+   - Verifies email and password
+   - Creates JWT token with 7-day expiration
+   - Token includes: user_id (sub), email, issued_at (iat), expiration (exp)
+   - Returns token and user profile
+
+3. **Protected Endpoints**:
+   - All `/api/tasks/*` endpoints require JWT authentication
+   - Client must include `Authorization: Bearer <token>` header
+   - Backend verifies token signature using `BETTER_AUTH_SECRET`
+   - Extracts user_id from token and filters all queries by authenticated user
+   - Returns 401 Unauthorized for missing, invalid, or expired tokens
+
+### Security Features
+
+- **Stateless Authentication**: No server-side session storage
+- **User Data Isolation**: All task queries automatically filtered by authenticated user_id
+- **Password Security**: Bcrypt hashing with cost factor 12
+- **Token Expiration**: 7-day JWT expiration (configurable via JWT_EXPIRATION_DAYS)
+- **Shared Secret**: BETTER_AUTH_SECRET must match between frontend and backend
+- **Error Handling**: Generic error messages for invalid credentials (prevents user enumeration)
+
+### Token Structure
+
+```json
+{
+  "sub": "123",           // User ID
+  "email": "user@example.com",
+  "iat": 1704067200,      // Issued at timestamp
+  "exp": 1704672000,      // Expiration timestamp (7 days)
+  "iss": "better-auth"    // Issuer
+}
+```
+
+### Error Responses
+
+- **401 TOKEN_EXPIRED**: JWT token has expired
+- **401 TOKEN_INVALID**: Invalid signature or malformed token
+- **401 TOKEN_MISSING**: No Authorization header provided
+- **401 INVALID_CREDENTIALS**: Email or password incorrect (generic message)
+- **409 EMAIL_EXISTS**: Email already registered during signup
+
+## Development
+
+### Create New Migration
+
+```bash
+python -m alembic revision --autogenerate -m "description"
+```
+
+### Rollback Migration
+
+```bash
+python -m alembic downgrade -1
+```
+
+### Run Tests (when implemented)
+
+```bash
+pytest
+```
+
+## Troubleshooting
+
+### Database Connection Issues
+
+1. **Neon**: Ensure connection string includes `?sslmode=require`
+2. **Local PostgreSQL**: Verify PostgreSQL is running and database exists
+3. Check `.env` file has correct `DATABASE_URL`
+
+### Migration Errors
+
+```bash
+# Reset database (WARNING: deletes all data)
+python -m alembic downgrade base
+python -m alembic upgrade head
+```
+
+## Next Steps
+
+1. Implement JWT authentication (Spec 2)
+2. Add comprehensive test suite
+3. Add API rate limiting
+4. Implement pagination metadata
+5. Add task categories/tags
+6. Deploy to production (Vercel/Railway)

README_HF.md

@@ -0,0 +1,33 @@
+---
+title: TaskFlow API
+emoji: ✅
+colorFrom: blue
+colorTo: indigo
+sdk: docker
+pinned: false
+license: mit
+---
+
+# TaskFlow Backend API
+
+FastAPI backend for TaskFlow task management application.
+
+## Features
+
+- User authentication with JWT
+- Task CRUD operations
+- PostgreSQL database with SQLModel ORM
+- RESTful API design
+
+## Environment Variables
+
+Configure these in your Space settings:
+
+- `DATABASE_URL`: PostgreSQL connection string
+- `SECRET_KEY`: JWT secret key (generate a secure random string)
+- `ALGORITHM`: JWT algorithm (default: HS256)
+- `ACCESS_TOKEN_EXPIRE_MINUTES`: Token expiration time (default: 30)
+
+## API Documentation
+
+Once deployed, visit `/docs` for interactive API documentation.

alembic.ini

@@ -0,0 +1,112 @@
+# A generic, single database configuration.
+
+[alembic]
+# path to migration scripts
+script_location = alembic
+
+# template used to generate migration file names
+file_template = %%(year)d%%(month).2d%%(day).2d_%%(hour).2d%%(minute).2d_%%(rev)s_%%(slug)s
+
+# sys.path path, will be prepended to sys.path if present.
+prepend_sys_path = .
+
+# timezone to use when rendering the date within the migration file
+# as well as the filename.
+# If specified, requires the python-dateutil library that can be
+# installed by adding `alembic[tz]` to the pip requirements
+# string value is passed to dateutil.tz.gettz()
+# leave blank for localtime
+# timezone =
+
+# max length of characters to apply to the
+# "slug" field
+# truncate_slug_length = 40
+
+# set to 'true' to run the environment during
+# the 'revision' command, regardless of autogenerate
+# revision_environment = false
+
+# set to 'true' to allow .pyc and .pyo files without
+# a source .py file to be detected as revisions in the
+# versions/ directory
+# sourceless = false
+
+# version location specification; This defaults
+# to alembic/versions.  When using multiple version
+# directories, initial revisions must be specified with --version-path.
+# The path separator used here should be the separator specified by "version_path_separator" below.
+# version_locations = %(here)s/bar:%(here)s/bat:alembic/versions
+
+# version path separator; As mentioned above, this is the character used to split
+# version_locations. The default within new alembic.ini files is "os", which uses os.pathsep.
+# If this key is omitted entirely, it falls back to the legacy behavior of splitting on spaces and/or commas.
+# Valid values for version_path_separator are:
+#
+# version_path_separator = :
+# version_path_separator = ;
+# version_path_separator = space
+version_path_separator = os  # Use os.pathsep. Default configuration used for new projects.
+
+# set to 'true' to search source files recursively
+# in each "version_locations" directory
+# new in Alembic version 1.10
+# recursive_version_locations = false
+
+# the output encoding used when revision files
+# are written from script.py.mako
+# output_encoding = utf-8
+
+sqlalchemy.url = driver://user:pass@localhost/dbname
+
+
+[post_write_hooks]
+# post_write_hooks defines scripts or Python functions that are run
+# on newly generated revision scripts.  See the documentation for further
+# detail and examples
+
+# format using "black" - use the console_scripts runner, against the "black" entrypoint
+# hooks = black
+# black.type = console_scripts
+# black.entrypoint = black
+# black.options = -l 79 REVISION_SCRIPT_FILENAME
+
+# lint with attempts to fix using "ruff" - use the exec runner, execute a binary
+# hooks = ruff
+# ruff.type = exec
+# ruff.executable = %(here)s/.venv/bin/ruff
+# ruff.options = --fix REVISION_SCRIPT_FILENAME
+
+# Logging configuration
+[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

alembic/env.py

@@ -0,0 +1,63 @@
+from logging.config import fileConfig
+from sqlalchemy import engine_from_config
+from sqlalchemy import pool
+from alembic import context
+import sys
+from pathlib import Path
+
+# Add the src directory to the path
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent / "src"))
+
+from src.core.config import settings
+from src.models import User, Task
+from sqlmodel import SQLModel
+
+# this is the Alembic Config object
+config = context.config
+
+# Set the database URL from settings
+config.set_main_option("sqlalchemy.url", settings.DATABASE_URL)
+
+# Interpret the config file for Python logging
+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 = SQLModel.metadata
+
+
+def run_migrations_offline() -> None:
+    """Run migrations in 'offline' mode."""
+    url = config.get_main_option("sqlalchemy.url")
+    context.configure(
+        url=url,
+        target_metadata=target_metadata,
+        literal_binds=True,
+        dialect_opts={"paramstyle": "named"},
+    )
+
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+def run_migrations_online() -> None:
+    """Run migrations in 'online' mode."""
+    connectable = engine_from_config(
+        config.get_section(config.config_ini_section, {}),
+        prefix="sqlalchemy.",
+        poolclass=pool.NullPool,
+    )
+
+    with connectable.connect() as connection:
+        context.configure(
+            connection=connection, target_metadata=target_metadata
+        )
+
+        with context.begin_transaction():
+            context.run_migrations()
+
+
+if context.is_offline_mode():
+    run_migrations_offline()
+else:
+    run_migrations_online()

alembic/script.py.mako

@@ -0,0 +1,24 @@
+"""${message}
+
+Revision ID: ${up_revision}
+Revises: ${down_revision | comma,n}
+Create Date: ${create_date}
+
+"""
+from alembic import op
+import sqlalchemy as sa
+${imports if imports else ""}
+
+# revision identifiers, used by Alembic.
+revision = ${repr(up_revision)}
+down_revision = ${repr(down_revision)}
+branch_labels = ${repr(branch_labels)}
+depends_on = ${repr(depends_on)}
+
+
+def upgrade() -> None:
+    ${upgrades if upgrades else "pass"}
+
+
+def downgrade() -> None:
+    ${downgrades if downgrades else "pass"}

alembic/versions/001_initial.py

@@ -0,0 +1,63 @@
+"""Create users and tasks tables
+
+Revision ID: 001_initial
+Revises:
+Create Date: 2026-01-08
+
+"""
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects import postgresql
+
+# revision identifiers, used by Alembic.
+revision = '001_initial'
+down_revision = None
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    # Create users table
+    op.create_table(
+        'users',
+        sa.Column('id', sa.Integer(), nullable=False),
+        sa.Column('email', sa.String(length=255), nullable=False),
+        sa.Column('name', sa.String(length=100), nullable=False),
+        sa.Column('created_at', sa.DateTime(), nullable=False),
+        sa.Column('updated_at', sa.DateTime(), nullable=False),
+        sa.PrimaryKeyConstraint('id')
+    )
+    op.create_index('ix_users_email', 'users', ['email'], unique=True)
+
+    # Create tasks table
+    op.create_table(
+        'tasks',
+        sa.Column('id', sa.Integer(), nullable=False),
+        sa.Column('user_id', sa.Integer(), nullable=False),
+        sa.Column('title', sa.String(length=200), nullable=False),
+        sa.Column('description', sa.String(length=1000), nullable=True),
+        sa.Column('completed', sa.Boolean(), nullable=False, server_default='false'),
+        sa.Column('created_at', sa.DateTime(), nullable=False),
+        sa.Column('updated_at', sa.DateTime(), nullable=False),
+        sa.ForeignKeyConstraint(['user_id'], ['users.id'], ondelete='CASCADE'),
+        sa.PrimaryKeyConstraint('id')
+    )
+
+    # Create indexes for tasks table
+    op.create_index('ix_tasks_user_id', 'tasks', ['user_id'])
+    op.create_index('ix_tasks_completed', 'tasks', ['completed'])
+    op.create_index('ix_tasks_user_id_completed', 'tasks', ['user_id', 'completed'])
+    op.create_index('ix_tasks_created_at', 'tasks', ['created_at'])
+
+
+def downgrade() -> None:
+    # Drop indexes
+    op.drop_index('ix_tasks_created_at', table_name='tasks')
+    op.drop_index('ix_tasks_user_id_completed', table_name='tasks')
+    op.drop_index('ix_tasks_completed', table_name='tasks')
+    op.drop_index('ix_tasks_user_id', table_name='tasks')
+
+    # Drop tables
+    op.drop_table('tasks')
+    op.drop_index('ix_users_email', table_name='users')
+    op.drop_table('users')

alembic/versions/002_add_user_password.py

@@ -0,0 +1,26 @@
+"""Add password_hash to users table
+
+Revision ID: 002_add_user_password
+Revises: 001_initial
+Create Date: 2026-01-09
+
+"""
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision = '002_add_user_password'
+down_revision = '001_initial'
+branch_labels = None
+depends_on = None
+
+
+def upgrade():
+    """Add password_hash column to users table."""
+    op.add_column('users', sa.Column('password_hash', sa.String(length=255), nullable=False))
+
+
+def downgrade():
+    """Remove password_hash column from users table."""
+    op.drop_column('users', 'password_hash')

deploy-prepare.ps1

@@ -0,0 +1,129 @@
+# Quick Deployment Script for Hugging Face Spaces (PowerShell)
+# This script helps prepare your backend for deployment
+
+Write-Host "🚀 TaskFlow Backend - Hugging Face Deployment Preparation" -ForegroundColor Cyan
+Write-Host "==========================================================" -ForegroundColor Cyan
+Write-Host ""
+
+# Check if we're in the backend directory
+if (-not (Test-Path "requirements.txt")) {
+    Write-Host "❌ Error: Please run this script from the backend directory" -ForegroundColor Red
+    exit 1
+}
+
+Write-Host "✅ Found backend directory" -ForegroundColor Green
+Write-Host ""
+
+# Check required files
+Write-Host "📋 Checking required files..." -ForegroundColor Yellow
+$files = @("Dockerfile", "requirements.txt", "alembic.ini", "src/main.py")
+$missing_files = @()
+
+foreach ($file in $files) {
+    if (Test-Path $file) {
+        Write-Host "  ✅ $file" -ForegroundColor Green
+    } else {
+        Write-Host "  ❌ $file (missing)" -ForegroundColor Red
+        $missing_files += $file
+    }
+}
+
+if ($missing_files.Count -gt 0) {
+    Write-Host ""
+    Write-Host "❌ Missing required files. Please ensure all files are present." -ForegroundColor Red
+    exit 1
+}
+
+Write-Host ""
+Write-Host "🔐 Generating secrets..." -ForegroundColor Yellow
+
+# Generate BETTER_AUTH_SECRET (using .NET crypto)
+$bytes = New-Object byte[] 32
+$rng = [System.Security.Cryptography.RandomNumberGenerator]::Create()
+$rng.GetBytes($bytes)
+$SECRET = [System.BitConverter]::ToString($bytes).Replace("-", "").ToLower()
+
+Write-Host ""
+Write-Host "Your BETTER_AUTH_SECRET (save this!):" -ForegroundColor Cyan
+Write-Host "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" -ForegroundColor Cyan
+Write-Host $SECRET -ForegroundColor Yellow
+Write-Host "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" -ForegroundColor Cyan
+Write-Host ""
+
+# Create deployment notes
+$deploymentNotes = @"
+TaskFlow Backend - Deployment Information
+Generated: $(Get-Date)
+
+BETTER_AUTH_SECRET: $SECRET
+
+Required Environment Variables for Hugging Face:
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+1. DATABASE_URL
+   Get from: Neon PostgreSQL Dashboard
+   Format: postgresql://user:password@host/database
+
+2. BETTER_AUTH_SECRET
+   Value: $SECRET
+
+3. CORS_ORIGINS
+   Initial: http://localhost:3000
+   After frontend deploy: https://your-app.vercel.app,https://your-app-*.vercel.app
+
+4. DEBUG
+   Value: False
+
+5. JWT_ALGORITHM (optional)
+   Value: HS256
+
+6. JWT_EXPIRATION_DAYS (optional)
+   Value: 7
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Next Steps:
+1. Create Hugging Face Space at https://huggingface.co/new-space
+2. Choose Docker SDK
+3. Clone the Space repository
+4. Copy all backend files to the Space directory
+5. Rename README_HF.md to README.md
+6. Commit and push
+7. Add environment variables in Space Settings
+8. Wait for build to complete
+
+"@
+
+$deploymentNotes | Out-File -FilePath "DEPLOYMENT_NOTES.txt" -Encoding UTF8
+
+Write-Host "📝 Deployment notes saved to: DEPLOYMENT_NOTES.txt" -ForegroundColor Green
+Write-Host ""
+
+# Check if Docker is available
+$dockerInstalled = Get-Command docker -ErrorAction SilentlyContinue
+if ($dockerInstalled) {
+    Write-Host "🐳 Docker is installed" -ForegroundColor Green
+    Write-Host ""
+    $response = Read-Host "Would you like to test the Docker build locally? (y/n)"
+    if ($response -eq "y" -or $response -eq "Y") {
+        Write-Host "Building Docker image..." -ForegroundColor Yellow
+        docker build -t taskflow-backend-test .
+        if ($LASTEXITCODE -eq 0) {
+            Write-Host "✅ Docker build successful!" -ForegroundColor Green
+        } else {
+            Write-Host "❌ Docker build failed. Please check the errors above." -ForegroundColor Red
+        }
+    }
+} else {
+    Write-Host "ℹ️  Docker not found. Skipping local build test." -ForegroundColor Yellow
+}
+
+Write-Host ""
+Write-Host "✅ Preparation complete!" -ForegroundColor Green
+Write-Host ""
+Write-Host "📚 Next steps:" -ForegroundColor Cyan
+Write-Host "  1. Review DEPLOYMENT_NOTES.txt"
+Write-Host "  2. Follow the deployment guide in ../DEPLOYMENT_GUIDE.md"
+Write-Host "  3. Create your Hugging Face Space"
+Write-Host "  4. Push your code"
+Write-Host ""

deploy-prepare.sh

@@ -0,0 +1,125 @@
+#!/bin/bash
+
+# Quick Deployment Script for Hugging Face Spaces
+# This script helps prepare your backend for deployment
+
+echo "🚀 TaskFlow Backend - Hugging Face Deployment Preparation"
+echo "=========================================================="
+echo ""
+
+# Check if we're in the backend directory
+if [ ! -f "requirements.txt" ]; then
+    echo "❌ Error: Please run this script from the backend directory"
+    exit 1
+fi
+
+echo "✅ Found backend directory"
+echo ""
+
+# Check required files
+echo "📋 Checking required files..."
+files=("Dockerfile" "requirements.txt" "alembic.ini" "src/main.py")
+missing_files=()
+
+for file in "${files[@]}"; do
+    if [ -f "$file" ]; then
+        echo "  ✅ $file"
+    else
+        echo "  ❌ $file (missing)"
+        missing_files+=("$file")
+    fi
+done
+
+if [ ${#missing_files[@]} -ne 0 ]; then
+    echo ""
+    echo "❌ Missing required files. Please ensure all files are present."
+    exit 1
+fi
+
+echo ""
+echo "🔐 Generating secrets..."
+
+# Generate BETTER_AUTH_SECRET
+SECRET=$(openssl rand -hex 32)
+echo ""
+echo "Your BETTER_AUTH_SECRET (save this!):"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "$SECRET"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo ""
+
+# Create deployment notes
+cat > DEPLOYMENT_NOTES.txt << EOF
+TaskFlow Backend - Deployment Information
+Generated: $(date)
+
+BETTER_AUTH_SECRET: $SECRET
+
+Required Environment Variables for Hugging Face:
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+1. DATABASE_URL
+   Get from: Neon PostgreSQL Dashboard
+   Format: postgresql://user:password@host/database
+
+2. BETTER_AUTH_SECRET
+   Value: $SECRET
+
+3. CORS_ORIGINS
+   Initial: http://localhost:3000
+   After frontend deploy: https://your-app.vercel.app,https://your-app-*.vercel.app
+
+4. DEBUG
+   Value: False
+
+5. JWT_ALGORITHM (optional)
+   Value: HS256
+
+6. JWT_EXPIRATION_DAYS (optional)
+   Value: 7
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Next Steps:
+1. Create Hugging Face Space at https://huggingface.co/new-space
+2. Choose Docker SDK
+3. Clone the Space repository
+4. Copy all backend files to the Space directory
+5. Rename README_HF.md to README.md
+6. Commit and push
+7. Add environment variables in Space Settings
+8. Wait for build to complete
+
+EOF
+
+echo "📝 Deployment notes saved to: DEPLOYMENT_NOTES.txt"
+echo ""
+
+# Test if Docker is available
+if command -v docker &> /dev/null; then
+    echo "🐳 Docker is installed"
+    echo ""
+    echo "Would you like to test the Docker build locally? (y/n)"
+    read -r response
+    if [[ "$response" =~ ^[Yy]$ ]]; then
+        echo "Building Docker image..."
+        docker build -t taskflow-backend-test .
+        if [ $? -eq 0 ]; then
+            echo "✅ Docker build successful!"
+        else
+            echo "❌ Docker build failed. Please check the errors above."
+        fi
+    fi
+else
+    echo "ℹ️  Docker not found. Skipping local build test."
+fi
+
+echo ""
+echo "✅ Preparation complete!"
+echo ""
+echo "📚 Next steps:"
+echo "  1. Review DEPLOYMENT_NOTES.txt"
+echo "  2. Follow the deployment guide in ../DEPLOYMENT_GUIDE.md"
+echo "  3. Create your Hugging Face Space"
+echo "  4. Push your code"
+echo ""

requirements.txt

@@ -0,0 +1,12 @@
+fastapi==0.104.1
+sqlmodel==0.0.14
+pydantic==2.5.0
+uvicorn[standard]==0.24.0
+alembic==1.13.0
+psycopg2-binary==2.9.9
+python-dotenv==1.0.0
+pytest==7.4.3
+httpx==0.25.2
+PyJWT==2.8.0
+passlib[bcrypt]==1.7.4
+python-multipart==0.0.6

src/api/__init__.py

@@ -0,0 +1 @@
+"""API module initialization."""

src/api/deps.py

@@ -0,0 +1,55 @@
+from sqlmodel import Session
+from typing import Generator
+from fastapi import Depends, HTTPException, status
+from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials
+from src.core.database import get_session
+from src.core.security import verify_jwt_token
+from src.core.config import settings
+
+security = HTTPBearer()
+
+
+def get_db() -> Generator[Session, None, None]:
+    """Get database session dependency."""
+    yield from get_session()
+
+
+def get_current_user(
+    credentials: HTTPAuthorizationCredentials = Depends(security)
+) -> int:
+    """
+    Get current user ID from JWT token.
+
+    Extracts and verifies JWT from Authorization header.
+
+    Args:
+        credentials: HTTP Bearer credentials from Authorization header
+
+    Returns:
+        User ID extracted from validated token
+
+    Raises:
+        HTTPException: 401 if token is missing, invalid, or expired
+    """
+    if not credentials:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Not authenticated",
+            headers={"WWW-Authenticate": "Bearer"}
+        )
+
+    token = credentials.credentials
+
+    # Verify token and extract payload
+    payload = verify_jwt_token(token, settings.BETTER_AUTH_SECRET)
+
+    # Extract user ID from 'sub' claim
+    user_id = payload.get("sub")
+    if not user_id:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Invalid token payload",
+            headers={"WWW-Authenticate": "Bearer"}
+        )
+
+    return int(user_id)

src/api/routes/__init__.py

@@ -0,0 +1 @@
+"""API routes module initialization."""

src/api/routes/auth.py

@@ -0,0 +1,88 @@
+"""Authentication API routes."""
+from fastapi import APIRouter, Depends, HTTPException, status
+from sqlmodel import Session, select
+from src.api.deps import get_db, get_current_user
+from src.schemas.auth import SignupRequest, SigninRequest, SignupResponse, TokenResponse, UserProfile
+from src.services.auth_service import AuthService
+from src.models.user import User
+
+router = APIRouter(prefix="/api/auth", tags=["authentication"])
+
+
+@router.post("/signup", response_model=SignupResponse, status_code=status.HTTP_201_CREATED)
+def signup(
+    signup_data: SignupRequest,
+    db: Session = Depends(get_db)
+):
+    """
+    Register a new user account.
+
+    Args:
+        signup_data: User signup information (email, password, name)
+        db: Database session
+
+    Returns:
+        SignupResponse: Created user details
+
+    Raises:
+        HTTPException: 400 if validation fails
+        HTTPException: 409 if email already exists
+    """
+    service = AuthService(db)
+    return service.signup(signup_data)
+
+
+@router.post("/signin", response_model=TokenResponse)
+def signin(
+    signin_data: SigninRequest,
+    db: Session = Depends(get_db)
+):
+    """
+    Authenticate user and issue JWT token.
+
+    Args:
+        signin_data: User signin credentials (email, password)
+        db: Database session
+
+    Returns:
+        TokenResponse: JWT token and user profile
+
+    Raises:
+        HTTPException: 401 if credentials are invalid
+    """
+    service = AuthService(db)
+    return service.signin(signin_data)
+
+
+@router.get("/me", response_model=UserProfile)
+def get_current_user_profile(
+    current_user_id: int = Depends(get_current_user),
+    db: Session = Depends(get_db)
+):
+    """
+    Get current authenticated user's profile.
+
+    Args:
+        current_user_id: ID of authenticated user from JWT token
+        db: Database session
+
+    Returns:
+        UserProfile: Current user's profile information
+
+    Raises:
+        HTTPException: 404 if user not found
+    """
+    user = db.exec(select(User).where(User.id == current_user_id)).first()
+
+    if not user:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="User not found"
+        )
+
+    return UserProfile(
+        id=user.id,
+        email=user.email,
+        name=user.name,
+        created_at=user.created_at
+    )

src/api/routes/tasks.py

@@ -0,0 +1,179 @@
+"""Task API routes."""
+from typing import Optional
+from fastapi import APIRouter, Depends, HTTPException, status, Query
+from sqlmodel import Session
+from src.api.deps import get_db, get_current_user
+from src.schemas.task import TaskCreate, TaskUpdate, TaskPatch, TaskResponse, TaskListResponse
+from src.services.task_service import TaskService
+
+router = APIRouter(prefix="/api/tasks", tags=["tasks"])
+
+
+@router.get("", response_model=TaskListResponse)
+def get_tasks(
+    completed: Optional[bool] = Query(None, description="Filter by completion status"),
+    sort: str = Query("created_at", description="Sort field (created_at or updated_at)"),
+    order: str = Query("desc", description="Sort order (asc or desc)"),
+    limit: Optional[int] = Query(None, description="Maximum number of tasks to return"),
+    offset: int = Query(0, description="Number of tasks to skip"),
+    db: Session = Depends(get_db),
+    current_user_id: int = Depends(get_current_user)
+):
+    """
+    Get tasks for the current user with filtering and sorting.
+
+    Query Parameters:
+        - completed: Filter by completion status (true/false/null for all)
+        - sort: Sort field (created_at or updated_at)
+        - order: Sort order (asc or desc)
+        - limit: Maximum number of tasks to return
+        - offset: Number of tasks to skip
+
+    Returns:
+        TaskListResponse: List of tasks with total count
+    """
+    service = TaskService(db)
+    tasks = service.get_tasks(
+        user_id=current_user_id,
+        completed=completed,
+        sort=sort,
+        order=order,
+        limit=limit,
+        offset=offset
+    )
+    return TaskListResponse(tasks=tasks, total=len(tasks))
+
+
+@router.post("", response_model=TaskResponse, status_code=status.HTTP_201_CREATED)
+def create_task(
+    task_data: TaskCreate,
+    db: Session = Depends(get_db),
+    current_user_id: int = Depends(get_current_user)
+):
+    """
+    Create a new task for the current user.
+
+    Args:
+        task_data: Task creation data
+
+    Returns:
+        TaskResponse: Created task
+    """
+    service = TaskService(db)
+    task = service.create_task(user_id=current_user_id, task_data=task_data)
+    return task
+
+
+@router.get("/{task_id}", response_model=TaskResponse)
+def get_task(
+    task_id: int,
+    db: Session = Depends(get_db),
+    current_user_id: int = Depends(get_current_user)
+):
+    """
+    Get a single task by ID.
+
+    Args:
+        task_id: ID of the task
+
+    Returns:
+        TaskResponse: Task details
+
+    Raises:
+        HTTPException: 404 if task not found or doesn't belong to user
+    """
+    service = TaskService(db)
+    task = service.get_task(task_id=task_id, user_id=current_user_id)
+    if not task:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Task not found"
+        )
+    return task
+
+
+@router.put("/{task_id}", response_model=TaskResponse)
+def update_task(
+    task_id: int,
+    task_data: TaskUpdate,
+    db: Session = Depends(get_db),
+    current_user_id: int = Depends(get_current_user)
+):
+    """
+    Update a task (PUT - replaces all fields).
+
+    Args:
+        task_id: ID of the task
+        task_data: Task update data
+
+    Returns:
+        TaskResponse: Updated task
+
+    Raises:
+        HTTPException: 404 if task not found or doesn't belong to user
+    """
+    service = TaskService(db)
+    task = service.update_task(task_id=task_id, user_id=current_user_id, task_data=task_data)
+    if not task:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Task not found"
+        )
+    return task
+
+
+@router.patch("/{task_id}", response_model=TaskResponse)
+def patch_task(
+    task_id: int,
+    task_data: TaskPatch,
+    db: Session = Depends(get_db),
+    current_user_id: int = Depends(get_current_user)
+):
+    """
+    Partially update a task (PATCH - updates only provided fields).
+
+    Args:
+        task_id: ID of the task
+        task_data: Task patch data
+
+    Returns:
+        TaskResponse: Updated task
+
+    Raises:
+        HTTPException: 404 if task not found or doesn't belong to user
+    """
+    service = TaskService(db)
+    task = service.patch_task(task_id=task_id, user_id=current_user_id, task_data=task_data)
+    if not task:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Task not found"
+        )
+    return task
+
+
+@router.delete("/{task_id}", status_code=status.HTTP_204_NO_CONTENT)
+def delete_task(
+    task_id: int,
+    db: Session = Depends(get_db),
+    current_user_id: int = Depends(get_current_user)
+):
+    """
+    Delete a task.
+
+    Args:
+        task_id: ID of the task
+
+    Returns:
+        No content (204)
+
+    Raises:
+        HTTPException: 404 if task not found or doesn't belong to user
+    """
+    service = TaskService(db)
+    deleted = service.delete_task(task_id=task_id, user_id=current_user_id)
+    if not deleted:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Task not found"
+        )

src/core/__init__.py

@@ -0,0 +1 @@
+"""Core module initialization."""

src/core/config.py

@@ -0,0 +1,27 @@
+from pydantic_settings import BaseSettings
+
+
+class Settings(BaseSettings):
+    """Application settings."""
+
+    # Database
+    DATABASE_URL: str
+
+    # Application
+    APP_NAME: str = "Task CRUD API"
+    DEBUG: bool = True
+
+    # CORS
+    CORS_ORIGINS: str = "http://localhost:3000"
+
+    # Authentication
+    BETTER_AUTH_SECRET: str  # Required - must be set in .env
+    JWT_ALGORITHM: str = "HS256"
+    JWT_EXPIRATION_DAYS: int = 7
+
+    class Config:
+        env_file = ".env"
+        case_sensitive = True
+
+
+settings = Settings()

src/core/database.py

@@ -0,0 +1,17 @@
+from sqlmodel import create_engine, Session
+from .config import settings
+
+# Create database engine
+engine = create_engine(
+    settings.DATABASE_URL,
+    echo=settings.DEBUG,
+    pool_pre_ping=True,
+    pool_size=5,
+    max_overflow=10
+)
+
+
+def get_session():
+    """Get database session."""
+    with Session(engine) as session:
+        yield session

src/core/security.py

@@ -0,0 +1,110 @@
+"""Security utilities for authentication and authorization."""
+import jwt
+from datetime import datetime, timedelta
+from passlib.context import CryptContext
+from fastapi import HTTPException, status
+from typing import Optional
+
+# Password hashing context
+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 password against its hash.
+
+    Args:
+        plain_password: Plain text password to verify
+        hashed_password: Hashed password to compare against
+
+    Returns:
+        True if password matches, False otherwise
+    """
+    return pwd_context.verify(plain_password, hashed_password)
+
+
+def create_jwt_token(user_id: int, email: str, secret: str, expiration_days: int = 7) -> str:
+    """
+    Create a JWT token for a user.
+
+    Args:
+        user_id: User's unique identifier
+        email: User's email address
+        secret: Secret key for signing the token
+        expiration_days: Number of days until token expires (default: 7)
+
+    Returns:
+        Encoded JWT token string
+    """
+    now = datetime.utcnow()
+    payload = {
+        "sub": str(user_id),
+        "email": email,
+        "iat": now,
+        "exp": now + timedelta(days=expiration_days),
+        "iss": "better-auth"
+    }
+    return jwt.encode(payload, secret, algorithm="HS256")
+
+
+def verify_jwt_token(token: str, secret: str) -> dict:
+    """
+    Verify and decode a JWT token.
+
+    Args:
+        token: JWT token string to verify
+        secret: Secret key used to sign the token
+
+    Returns:
+        Decoded token payload as dictionary
+
+    Raises:
+        HTTPException: 401 if token is expired or invalid
+    """
+    try:
+        payload = jwt.decode(
+            token,
+            secret,
+            algorithms=["HS256"],
+            options={
+                "verify_signature": True,
+                "verify_exp": True,
+                "require": ["sub", "email", "iat", "exp", "iss"]
+            }
+        )
+
+        # Validate issuer
+        if payload.get("iss") != "better-auth":
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail="Invalid token issuer",
+                headers={"WWW-Authenticate": "Bearer"}
+            )
+
+        return payload
+
+    except jwt.ExpiredSignatureError:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Token has expired",
+            headers={"WWW-Authenticate": "Bearer"}
+        )
+    except jwt.InvalidTokenError:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Invalid token",
+            headers={"WWW-Authenticate": "Bearer"}
+        )

src/main.py

@@ -0,0 +1,34 @@
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+from .core.config import settings
+from .api.routes import tasks, auth
+
+app = FastAPI(
+    title=settings.APP_NAME,
+    debug=settings.DEBUG
+)
+
+# Configure CORS
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=settings.CORS_ORIGINS.split(","),
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# Register routes
+app.include_router(auth.router)
+app.include_router(tasks.router)
+
+
+@app.get("/")
+async def root():
+    """Root endpoint."""
+    return {"message": "Task CRUD API", "status": "running"}
+
+
+@app.get("/health")
+async def health():
+    """Health check endpoint."""
+    return {"status": "healthy"}

src/models/__init__.py

@@ -0,0 +1,5 @@
+"""Models module initialization."""
+from .user import User
+from .task import Task
+
+__all__ = ["User", "Task"]

src/models/task.py

@@ -0,0 +1,17 @@
+from sqlmodel import SQLModel, Field
+from datetime import datetime
+from typing import Optional
+
+
+class Task(SQLModel, table=True):
+    """Task entity representing a to-do item."""
+
+    __tablename__ = "tasks"
+
+    id: Optional[int] = Field(default=None, primary_key=True)
+    user_id: int = Field(foreign_key="users.id", nullable=False, index=True)
+    title: str = Field(max_length=200, nullable=False)
+    description: Optional[str] = Field(default=None, max_length=1000)
+    completed: bool = Field(default=False, nullable=False, index=True)
+    created_at: datetime = Field(default_factory=datetime.utcnow, nullable=False, index=True)
+    updated_at: datetime = Field(default_factory=datetime.utcnow, nullable=False)

src/models/user.py

@@ -0,0 +1,16 @@
+from sqlmodel import SQLModel, Field
+from datetime import datetime
+from typing import Optional
+
+
+class User(SQLModel, table=True):
+    """User entity with authentication support."""
+
+    __tablename__ = "users"
+
+    id: Optional[int] = Field(default=None, primary_key=True)
+    email: str = Field(max_length=255, unique=True, nullable=False, index=True)
+    name: str = Field(max_length=100, nullable=False)
+    password_hash: str = Field(max_length=255, nullable=False)
+    created_at: datetime = Field(default_factory=datetime.utcnow, nullable=False)
+    updated_at: datetime = Field(default_factory=datetime.utcnow, nullable=False)

src/schemas/__init__.py

@@ -0,0 +1 @@
+"""Pydantic schemas for request/response validation."""

src/schemas/auth.py

@@ -0,0 +1,47 @@
+"""Authentication schemas for request/response validation."""
+from pydantic import BaseModel, EmailStr, Field
+from datetime import datetime
+from typing import Optional
+
+
+class SignupRequest(BaseModel):
+    """Request schema for user signup."""
+    email: EmailStr = Field(..., description="User's email address")
+    password: str = Field(..., min_length=8, max_length=100, description="User's password")
+    name: str = Field(..., min_length=1, max_length=100, description="User's display name")
+
+
+class SigninRequest(BaseModel):
+    """Request schema for user signin."""
+    email: EmailStr = Field(..., description="User's email address")
+    password: str = Field(..., description="User's password")
+
+
+class UserProfile(BaseModel):
+    """User profile response schema."""
+    id: int
+    email: str
+    name: str
+    created_at: datetime
+
+    class Config:
+        from_attributes = True
+
+
+class TokenResponse(BaseModel):
+    """Response schema for authentication with JWT token."""
+    access_token: str = Field(..., description="JWT access token")
+    token_type: str = Field(default="bearer", description="Token type")
+    expires_in: int = Field(..., description="Token expiration time in seconds")
+    user: UserProfile
+
+
+class SignupResponse(BaseModel):
+    """Response schema for successful signup."""
+    id: int
+    email: str
+    name: str
+    created_at: datetime
+
+    class Config:
+        from_attributes = True

src/schemas/task.py

@@ -0,0 +1,102 @@
+"""Pydantic schemas for Task CRUD operations."""
+from datetime import datetime
+from typing import Optional
+from pydantic import BaseModel, Field, ConfigDict
+
+
+class TaskCreate(BaseModel):
+    """Schema for creating a new task."""
+    title: str = Field(..., min_length=1, max_length=200, description="Task title")
+    description: Optional[str] = Field(None, max_length=1000, description="Task description")
+
+    model_config = ConfigDict(
+        json_schema_extra={
+            "example": {
+                "title": "Buy groceries",
+                "description": "Milk, eggs, bread"
+            }
+        }
+    )
+
+
+class TaskResponse(BaseModel):
+    """Schema for task response."""
+    id: int = Field(..., description="Task ID")
+    user_id: int = Field(..., description="User ID who owns the task")
+    title: str = Field(..., description="Task title")
+    description: Optional[str] = Field(None, description="Task description")
+    completed: bool = Field(..., description="Task completion status")
+    created_at: datetime = Field(..., description="Task creation timestamp")
+    updated_at: datetime = Field(..., description="Task last update timestamp")
+
+    model_config = ConfigDict(
+        from_attributes=True,
+        json_schema_extra={
+            "example": {
+                "id": 1,
+                "user_id": 1,
+                "title": "Buy groceries",
+                "description": "Milk, eggs, bread",
+                "completed": False,
+                "created_at": "2026-01-08T10:00:00Z",
+                "updated_at": "2026-01-08T10:00:00Z"
+            }
+        }
+    )
+
+
+class TaskUpdate(BaseModel):
+    """Schema for updating a task (PUT - replaces all fields)."""
+    title: str = Field(..., min_length=1, max_length=200, description="Task title")
+    description: Optional[str] = Field(None, max_length=1000, description="Task description")
+    completed: bool = Field(..., description="Task completion status")
+
+    model_config = ConfigDict(
+        json_schema_extra={
+            "example": {
+                "title": "Buy groceries",
+                "description": "Milk, eggs, bread, cheese",
+                "completed": False
+            }
+        }
+    )
+
+
+class TaskPatch(BaseModel):
+    """Schema for partially updating a task (PATCH - updates only provided fields)."""
+    title: Optional[str] = Field(None, min_length=1, max_length=200, description="Task title")
+    description: Optional[str] = Field(None, max_length=1000, description="Task description")
+    completed: Optional[bool] = Field(None, description="Task completion status")
+
+    model_config = ConfigDict(
+        json_schema_extra={
+            "example": {
+                "completed": True
+            }
+        }
+    )
+
+
+class TaskListResponse(BaseModel):
+    """Schema for list of tasks response."""
+    tasks: list[TaskResponse] = Field(..., description="List of tasks")
+    total: int = Field(..., description="Total number of tasks")
+
+    model_config = ConfigDict(
+        json_schema_extra={
+            "example": {
+                "tasks": [
+                    {
+                        "id": 1,
+                        "user_id": 1,
+                        "title": "Buy groceries",
+                        "description": "Milk, eggs, bread",
+                        "completed": False,
+                        "created_at": "2026-01-08T10:00:00Z",
+                        "updated_at": "2026-01-08T10:00:00Z"
+                    }
+                ],
+                "total": 1
+            }
+        }
+    )

src/services/__init__.py

@@ -0,0 +1 @@
+"""Business logic services."""