diff --git a/docs/configuration.md b/docs/configuration.md
index 0e80d87..5cb3d35 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -6,6 +6,7 @@ JsWeb applications are configured using a `config.py` file in your project's roo
 
 - [Config File Structure](#config-file-structure)
 - [Core Configuration Options](#core-configuration-options)
+- [OpenAPI & API Documentation Configuration](#openapi--api-documentation-configuration)
 - [Database Configuration](#database-configuration)
 - [Security Settings](#security-settings)
 - [Development vs Production](#development-vs-production)
@@ -22,7 +23,11 @@ import os
 # Get the base directory of the project
 BASE_DIR = os.path.abspath(os.path.dirname(__file__))
 
-# Secret key for signing sessions and other security-related things
+# Application info
+APP_NAME = "myproject"
+VERSION = "0.1.0"
+
+# Security
 SECRET_KEY = "your-secret-key"
 
 # Database configuration
@@ -35,6 +40,19 @@ STATIC_DIR = os.path.join(BASE_DIR, "static")
 
 # Template files configuration
 TEMPLATE_FOLDER = "templates"
+
+# Server configuration
+HOST = "127.0.0.1"
+PORT = 8000
+
+# OpenAPI / API Documentation (Automatic!)
+ENABLE_OPENAPI_DOCS = True
+API_TITLE = "myproject API"
+API_VERSION = "1.0.0"
+API_DESCRIPTION = "API documentation"
+OPENAPI_DOCS_URL = "/docs"
+OPENAPI_REDOC_URL = "/redoc"
+OPENAPI_JSON_URL = "/openapi.json"
 ```
 
 ## Core Configuration Options
@@ -52,6 +70,108 @@ Here are the most important configuration options:
 | `STATIC_DIR` | String | Directory path for static files |
 | `TEMPLATE_FOLDER` | String | Directory for templates |
 | `MAX_CONTENT_LENGTH` | Integer | Maximum upload file size in bytes |
+| `BASE_DIR` | String | Absolute path to project root directory |
+| `HOST` | String | Server host address (default: `127.0.0.1`) |
+| `PORT` | Integer | Server port (default: `8000`) |
+| `APP_NAME` | String | Application name |
+| `VERSION` | String | Application version |
+
+## OpenAPI & API Documentation Configuration
+
+JsWeb automatically generates OpenAPI documentation with Swagger UI and ReDoc. Configure these settings to customize your API documentation:
+
+```python
+# OpenAPI / Swagger Documentation Configuration
+ENABLE_OPENAPI_DOCS = True              # Enable/disable automatic API documentation
+API_TITLE = "My App API"                # API title shown in documentation
+API_VERSION = "1.0.0"                   # API version
+API_DESCRIPTION = "API for my app"      # API description (supports Markdown!)
+OPENAPI_DOCS_URL = "/docs"              # Swagger UI endpoint
+OPENAPI_REDOC_URL = "/redoc"            # ReDoc UI endpoint  
+OPENAPI_JSON_URL = "/openapi.json"      # OpenAPI specification JSON endpoint
+```
+
+### API Documentation Settings
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `ENABLE_OPENAPI_DOCS` | Boolean | `True` | Enable/disable automatic OpenAPI documentation |
+| `API_TITLE` | String | `"jsweb API"` | Title displayed in API documentation |
+| `API_VERSION` | String | `"1.0.0"` | Version of your API |
+| `API_DESCRIPTION` | String | `""` | Description of your API (supports Markdown) |
+| `OPENAPI_DOCS_URL` | String | `"/docs"` | URL endpoint for Swagger UI |
+| `OPENAPI_REDOC_URL` | String | `"/redoc"` | URL endpoint for ReDoc UI |
+| `OPENAPI_JSON_URL` | String | `"/openapi.json"` | URL endpoint for OpenAPI JSON specification |
+
+### Using Markdown in API Description
+
+The `API_DESCRIPTION` supports Markdown formatting for rich documentation:
+
+```python
+API_DESCRIPTION = """
+# My Awesome API
+
+This is a **production-ready** API built with JsWeb.
+
+## Features
+
+- Fast ASGI framework
+- Automatic OpenAPI documentation
+- Built-in authentication
+- Database ORM support
+
+## Base URL
+
+`https://api.example.com`
+"""
+```
+
+### Example: Complete API Documentation Setup
+
+```python
+# config.py
+import os
+
+# Core settings
+APP_NAME = "Task Manager"
+VERSION = "2.1.0"
+SECRET_KEY = os.getenv('SECRET_KEY', 'dev-key')
+DEBUG = os.getenv('DEBUG', False)
+
+# Database
+SQLALCHEMY_DATABASE_URI = "sqlite:///app.db"
+
+# API Documentation
+ENABLE_OPENAPI_DOCS = True
+API_TITLE = "Task Manager API"
+API_VERSION = "2.1.0"
+API_DESCRIPTION = """
+# Task Manager API
+
+A powerful REST API for managing tasks and projects.
+
+## Authentication
+
+All endpoints require Bearer token authentication.
+
+## Error Handling
+
+Errors are returned as JSON with appropriate HTTP status codes.
+"""
+OPENAPI_DOCS_URL = "/api/docs"
+OPENAPI_REDOC_URL = "/api/redoc"
+OPENAPI_JSON_URL = "/api/spec.json"
+```
+
+### Disabling Documentation
+
+To disable automatic API documentation:
+
+```python
+ENABLE_OPENAPI_DOCS = False
+```
+
+When disabled, the documentation endpoints will not be registered.
 
 ## Database Configuration
 
diff --git a/docs/database.md b/docs/database.md
index dfbf9d0..6cb9d2d 100644
--- a/docs/database.md
+++ b/docs/database.md
@@ -7,6 +7,7 @@ JsWeb provides a simple and powerful way to work with databases using [SQLAlchem
 - [Configuration](#configuration)
 - [Defining Models](#defining-models)
 - [Model Fields](#model-fields)
+- [Return Types](#return-types)
 - [Querying the Database](#querying-the-database)
 - [Database Migrations](#database-migrations)
 - [Relationships](#relationships)
@@ -98,78 +99,148 @@ class Product(ModelBase):
     category = Column(String(50), index=True)
 ```
 
+## Return Types
+
+ModelBase provides CRUD (Create, Read, Update, Delete) operations with the following return types:
+
+### ModelBase Methods Return Types
+
+| Method | Return Type | Description |
+|--------|------------|-------------|
+| `Model.create(**kwargs)` | `Model` | Creates and saves instance |
+| `instance.save()` | `None` | Saves changes to database |
+| `instance.update(**kwargs)` | `None` | Updates fields and saves |
+| `instance.delete()` | `None` | Deletes instance from database |
+| `Model.query.get(id)` | `Optional[Model]` | Get by primary key or None |
+| `Model.query.first()` | `Optional[Model]` | Get first result or None |
+| `Model.query.all()` | `List[Model]` | Get all results as list |
+| `Model.query.filter_by()` | `Query` | Query builder |
+
+### Example with Type Hints
+
+```python
+from typing import Optional, List
+from jsweb.database import ModelBase
+
+class User(ModelBase):
+    __tablename__ = 'users'
+    id = Column(Integer, primary_key=True)
+    username = Column(String(80), unique=True)
+    email = Column(String(120))
+
+# Create - returns User instance
+user: User = User.create(username="alice", email="alice@example.com")
+
+# Read - returns Optional[User]
+user: Optional[User] = User.query.get(1)
+user: Optional[User] = User.query.filter_by(username="bob").first()
+users: List[User] = User.query.all()
+
+# Update - returns None
+user.email = "newemail@example.com"
+user.save()  # -> None
+
+# Update with update() - returns None
+user.update(email="another@example.com")  # -> None
+
+# Delete - returns None
+user.delete()  # -> None
+```
+
 ## Querying the Database
 
 ### Get All Records
 
 ```python
+from typing import List
 from .models import User
+from jsweb.response import render, HTMLResponse
 
 @app.route("/users")
-async def user_list(req):
-    users = User.query.all()
+async def user_list(req) -> HTMLResponse:
+    users: List[User] = User.query.all()
     return render(req, "users.html", {"users": users})
 ```
 
 ### Get a Single Record by ID
 
 ```python
+from typing import Optional
+from jsweb.response import render, json, HTMLResponse, JSONResponse
+
 @app.route("/user/<int:user_id>")
-async def user_detail(req, user_id):
-    user = User.query.get(user_id)
+async def user_detail(req, user_id: int) -> HTMLResponse:
+    user: Optional[User] = User.query.get(user_id)
     if user is None:
-        return "User not found", 404
+        return render(req, "404.html", {}), 404
     return render(req, "user.html", {"user": user})
+
+# JSON API version
+@app.route("/api/user/<int:user_id>")
+async def api_user_detail(req, user_id: int) -> JSONResponse:
+    user: Optional[User] = User.query.get(user_id)
+    if user is None:
+        return json({"error": "User not found"}, status_code=404)
+    return json(user.to_dict())
 ```
 
 ### Filter Records
 
 ```python
-# Get user by username
-user = User.query.filter_by(username="alice").first()
+from typing import List, Optional
+from sqlalchemy import or_
 
-# Get all admin users
-admins = User.query.filter_by(role="admin").all()
+# Get user by username - returns Optional[User]
+user: Optional[User] = User.query.filter_by(username="alice").first()
 
-# Using filter() for more complex conditions
-from sqlalchemy import or_
+# Get all admin users - returns List[User]
+admins: List[User] = User.query.filter_by(role="admin").all()
 
-users = User.query.filter(
+# Using filter() for more complex conditions - returns List[User]
+users: List[User] = User.query.filter(
     or_(User.username == "alice", User.email == "alice@example.com")
 ).all()
 ```
 
 !!! tip "first() vs all()"
-    - `first()` returns the first result or `None`
-    - `all()` returns a list of all results
-    - `get(id)` returns the record with that primary key or `None`
+    - `first()` returns `Optional[Model]` (first result or `None`)
+    - `all()` returns `List[Model]` (all results)
+    - `get(id)` returns `Optional[Model]` (by primary key or `None`)
 
 ### Creating Records
 
 ```python
-# Method 1: Using create()
-new_user = User.create(username="john", email="john@example.com")
+# Method 1: Using create() - returns Model instance
+new_user: User = User.create(username="john", email="john@example.com")
 
-# Method 2: Creating and saving manually
+# Method 2: Creating and saving manually - returns None
 user = User(username="jane", email="jane@example.com")
-db.session.add(user)
-db.session.commit()
+user.save()  # -> None
 ```
 
 ### Updating Records
 
 ```python
-user = User.query.get(1)
-user.email = "newemail@example.com"
-db.session.commit()
+# Method 1: Manual update - returns None
+user: Optional[User] = User.query.get(1)
+if user:
+    user.email = "newemail@example.com"
+    user.save()  # -> None
+
+# Method 2: Using update() - returns None
+user.update(email="another@example.com")  # -> None
 ```
 
 ### Deleting Records
 
 ```python
-user = User.query.get(1)
-db.session.delete(user)
-db.session.commit()
+# Method 1: Delete instance - returns None
+user: Optional[User] = User.query.get(1)
+if user:
+    user.delete()  # -> None
+
+# Method 2: Query and delete
+User.query.filter_by(username="inactive").delete()
 ```
 
 ## Database Migrations
diff --git a/docs/dto-models.md b/docs/dto-models.md
new file mode 100644
index 0000000..7ae5447
--- /dev/null
+++ b/docs/dto-models.md
@@ -0,0 +1,562 @@
+# DTOs & Data Models
+
+JsWeb provides a powerful Data Transfer Object (DTO) system built on Pydantic v2 for automatic validation, serialization, and API documentation. DTOs are essential for building robust APIs with proper data validation.
+
+## Table of Contents
+
+- [What are DTOs?](#what-are-dtos)
+- [JswebBaseModel](#jswebbasemodel)
+- [Defining DTOs](#defining-dtos)
+- [Field Types](#field-types)
+- [Validation](#validation)
+- [Serialization](#serialization)
+- [OpenAPI Integration](#openapi-integration)
+- [Practical Examples](#practical-examples)
+- [Best Practices](#best-practices)
+
+## What are DTOs?
+
+Data Transfer Objects (DTOs) are lightweight classes that define the structure and validation rules for data flowing in and out of your API. They provide:
+
+- **Type Safety**: Explicit type definitions
+- **Validation**: Automatic validation of input data
+- **Documentation**: Auto-generated API schemas
+- **Serialization**: Easy conversion to/from JSON
+- **IDE Support**: Full autocomplete and type checking
+
+## JswebBaseModel
+
+The `JswebBaseModel` is the base class for all DTOs in JsWeb. It's built on Pydantic v2 and provides a clean API for data handling.
+
+```python
+from jsweb.dto import JswebBaseModel, Field
+
+class UserDto(JswebBaseModel):
+    """DTO for user data"""
+    name: str = Field(description="User's full name", max_length=100)
+    email: str = Field(description="Email address")
+    age: int = Field(ge=0, le=150, description="User age")
+```
+
+### Return Type: `Type[JswebBaseModel]`
+
+When you define a DTO class, it becomes a subclass of `JswebBaseModel` with all the inherited methods.
+
+## Defining DTOs
+
+### Basic DTO
+
+```python
+from jsweb.dto import JswebBaseModel, Field
+from typing import Optional
+
+class CreateUserRequest(JswebBaseModel):
+    """Request DTO for creating a user"""
+    username: str = Field(min_length=3, max_length=50)
+    email: str = Field(pattern=r'^[\w\.-]+@[\w\.-]+\.\w+$')
+    password: str = Field(min_length=8)
+    full_name: Optional[str] = None
+```
+
+### With Defaults
+
+```python
+from jsweb.dto import JswebBaseModel, Field
+from datetime import datetime
+
+class BlogPostDto(JswebBaseModel):
+    title: str = Field(min_length=1, max_length=200)
+    content: str
+    published: bool = False
+    created_at: datetime = Field(default_factory=datetime.now)
+    tags: list[str] = Field(default_factory=list)
+```
+
+### Nested DTOs
+
+```python
+from jsweb.dto import JswebBaseModel, Field
+from typing import List
+
+class AddressDto(JswebBaseModel):
+    street: str
+    city: str
+    country: str
+    postal_code: str
+
+class UserWithAddressDto(JswebBaseModel):
+    name: str
+    email: str
+    address: AddressDto  # Nested DTO
+```
+
+## Field Types
+
+JsWeb supports all Python type annotations with Pydantic validation:
+
+### Basic Types
+
+```python
+from jsweb.dto import JswebBaseModel, Field
+from typing import Optional
+
+class BasicTypesDto(JswebBaseModel):
+    # String
+    name: str = Field(min_length=1, max_length=100)
+    
+    # Integer
+    age: int = Field(ge=0, le=150)
+    
+    # Float
+    price: float = Field(gt=0)
+    
+    # Boolean
+    active: bool = True
+    
+    # Optional (can be None)
+    nickname: Optional[str] = None
+```
+
+### Complex Types
+
+```python
+from jsweb.dto import JswebBaseModel, Field
+from datetime import datetime, date
+from typing import List, Dict
+
+class ComplexTypesDto(JswebBaseModel):
+    # Lists
+    tags: List[str] = Field(default_factory=list)
+    scores: List[int]
+    
+    # Dictionary
+    metadata: Dict[str, str] = Field(default_factory=dict)
+    
+    # Date/Time
+    birth_date: date
+    created_at: datetime
+    updated_at: Optional[datetime] = None
+```
+
+### Field Constraints
+
+```python
+from jsweb.dto import JswebBaseModel, Field
+
+class ConstrainedFieldsDto(JswebBaseModel):
+    # String constraints
+    username: str = Field(min_length=3, max_length=20, pattern=r'^[a-zA-Z0-9_]+$')
+    
+    # Numeric constraints
+    age: int = Field(ge=0, le=150)
+    rating: float = Field(ge=0, le=5)
+    
+    # List constraints
+    tags: list[str] = Field(min_length=1, max_length=10)
+    
+    # With description (for OpenAPI)
+    email: str = Field(description="User's email address")
+```
+
+## Validation
+
+### Automatic Validation
+
+Validation happens automatically when creating instances:
+
+```python
+from jsweb.dto import JswebBaseModel, Field
+from pydantic import ValidationError
+
+class UserDto(JswebBaseModel):
+    name: str = Field(min_length=1)
+    age: int = Field(ge=0, le=150)
+
+# ✓ Valid
+user = UserDto(name="Alice", age=30)
+
+# ✗ Raises ValidationError
+try:
+    invalid = UserDto(name="", age=200)  # Empty name, age out of range
+except ValidationError as e:
+    print(e.errors())
+```
+
+### Custom Validators
+
+```python
+from jsweb.dto import JswebBaseModel, Field, validator
+from datetime import date
+
+class PersonDto(JswebBaseModel):
+    name: str
+    birth_date: date
+    
+    @validator('name')
+    def name_must_not_be_empty(cls, v):
+        if not v or not v.strip():
+            raise ValueError('Name cannot be empty')
+        return v.strip()
+    
+    @validator('birth_date')
+    def birth_date_must_be_past(cls, v):
+        if v > date.today():
+            raise ValueError('Birth date cannot be in the future')
+        return v
+```
+
+### Root Validators
+
+Validate multiple fields together:
+
+```python
+from jsweb.dto import JswebBaseModel, root_validator
+
+class PasswordChangeDto(JswebBaseModel):
+    old_password: str
+    new_password: str
+    confirm_password: str
+    
+    @root_validator()
+    def passwords_match(cls, values):
+        new_pass = values.get('new_password')
+        confirm_pass = values.get('confirm_password')
+        
+        if new_pass != confirm_pass:
+            raise ValueError('Passwords do not match')
+        
+        return values
+```
+
+## Serialization
+
+### `to_dict()` → `Dict[str, Any]`
+
+Convert DTO instance to dictionary:
+
+```python
+user = UserDto(name="Alice", email="alice@example.com", age=30)
+
+# Basic conversion
+user_dict = user.to_dict()
+# Output: {'name': 'Alice', 'email': 'alice@example.com', 'age': 30}
+
+# Exclude None values
+user_dict = user.to_dict(exclude_none=True)
+
+# Use field aliases
+user_dict = user.to_dict(by_alias=True)
+```
+
+### `to_json()` → `str`
+
+Convert DTO instance to JSON string:
+
+```python
+user = UserDto(name="Alice", email="alice@example.com", age=30)
+
+# Basic conversion
+json_str = user.to_json()
+# Output: '{"name":"Alice","email":"alice@example.com","age":30}'
+
+# Pretty-printed
+json_str = user.to_json(indent=2)
+
+# Exclude None values
+json_str = user.to_json(exclude_none=True)
+```
+
+### `from_dict()` → `Type[JswebBaseModel]`
+
+Create DTO instance from dictionary:
+
+```python
+data = {
+    "name": "Bob",
+    "email": "bob@example.com",
+    "age": 25
+}
+
+user = UserDto.from_dict(data)
+# Automatically validates!
+```
+
+### `model_validate()` → `Type[JswebBaseModel]`
+
+Parse and validate data:
+
+```python
+json_data = '{"name": "Alice", "email": "alice@example.com", "age": 30}'
+
+# From JSON string
+import json
+data = json.loads(json_data)
+user = UserDto.model_validate(data)
+
+# With validation errors
+try:
+    invalid = UserDto.model_validate({"name": "", "age": 200})
+except ValidationError as e:
+    print(e)
+```
+
+## OpenAPI Integration
+
+### `openapi_schema()` → `Dict[str, Any]`
+
+Generate OpenAPI 3.0 schema automatically:
+
+```python
+class UserDto(JswebBaseModel):
+    """A user in the system"""
+    name: str = Field(description="User's full name")
+    email: str = Field(description="Email address")
+    age: int = Field(ge=0, le=150, description="User age")
+
+# Generate schema
+schema = UserDto.openapi_schema()
+
+# Output:
+# {
+#   "type": "object",
+#   "properties": {
+#     "name": {"type": "string", "description": "User's full name"},
+#     "email": {"type": "string", "description": "Email address"},
+#     "age": {"type": "integer", "minimum": 0, "maximum": 150, ...}
+#   },
+#   "required": ["name", "email", "age"]
+# }
+```
+
+### Using in API Documentation
+
+```python
+from jsweb import JsWebApp
+from jsweb.response import json
+from jsweb.dto import JswebBaseModel, Field
+
+class CreateUserRequest(JswebBaseModel):
+    """Request body for creating a user"""
+    username: str = Field(min_length=3, description="Username")
+    email: str = Field(description="Email address")
+    password: str = Field(min_length=8, description="Password")
+
+class UserResponse(JswebBaseModel):
+    """User response DTO"""
+    id: int
+    username: str
+    email: str
+
+@app.route("/api/users", methods=["POST"])
+async def create_user(req) -> json:
+    """
+    Create a new user
+    
+    Request body schema:
+    {schema}
+    
+    Response schema:
+    {response_schema}
+    """
+    # Schema is auto-documented in API
+    return json({
+        "id": 1,
+        "username": "john",
+        "email": "john@example.com"
+    })
+```
+
+## Practical Examples
+
+### User Registration
+
+```python
+from jsweb.dto import JswebBaseModel, Field, validator
+from jsweb.response import json, JSONResponse
+import re
+
+class RegisterRequest(JswebBaseModel):
+    """User registration request"""
+    username: str = Field(min_length=3, max_length=50)
+    email: str
+    password: str = Field(min_length=8)
+    password_confirm: str
+    
+    @validator('username')
+    def username_alphanumeric(cls, v):
+        if not re.match(r'^[a-zA-Z0-9_]+$', v):
+            raise ValueError('Username must be alphanumeric')
+        return v
+    
+    @validator('email')
+    def email_valid(cls, v):
+        if '@' not in v:
+            raise ValueError('Invalid email')
+        return v
+
+class UserResponse(JswebBaseModel):
+    """Registered user response"""
+    id: int
+    username: str
+    email: str
+
+@app.route("/api/register", methods=["POST"])
+async def register(req) -> JSONResponse:
+    try:
+        # Parse and validate request
+        req_data = await req.json()
+        register_req = RegisterRequest.from_dict(req_data)
+        
+        # Check password confirmation
+        if register_req.password != register_req.password_confirm:
+            return json(
+                {"error": "Passwords don't match"},
+                status_code=400
+            )
+        
+        # Create user
+        user = User.create(
+            username=register_req.username,
+            email=register_req.email,
+            password_hash=hash_password(register_req.password)
+        )
+        
+        # Return response
+        response = UserResponse(id=user.id, username=user.username, email=user.email)
+        return json(response.to_dict(), status_code=201)
+        
+    except ValidationError as e:
+        return json(
+            {"errors": e.errors()},
+            status_code=422
+        )
+```
+
+### API Response Wrapper
+
+```python
+from jsweb.dto import JswebBaseModel, Field
+from typing import Generic, TypeVar, Optional
+
+T = TypeVar('T')
+
+class ApiResponse(JswebBaseModel, Generic[T]):
+    """Standard API response wrapper"""
+    success: bool
+    data: Optional[dict] = None
+    error: Optional[str] = None
+    status_code: int = 200
+
+@app.route("/api/data")
+async def get_data(req) -> json:
+    try:
+        data = fetch_data()
+        response = ApiResponse(
+            success=True,
+            data=data,
+            status_code=200
+        )
+        return json(response.to_dict())
+    except Exception as e:
+        response = ApiResponse(
+            success=False,
+            error=str(e),
+            status_code=500
+        )
+        return json(response.to_dict(), status_code=500)
+```
+
+## Best Practices
+
+### 1. Use Type Hints Consistently
+
+```python
+# ✓ Good
+class UserDto(JswebBaseModel):
+    name: str = Field(min_length=1)
+    age: int = Field(ge=0)
+    email: str
+
+# ✗ Bad
+class UserDto(JswebBaseModel):
+    name = Field(min_length=1)
+    age = Field(ge=0)
+```
+
+### 2. Provide Field Descriptions
+
+```python
+# ✓ Good - helps with API documentation
+class ProductDto(JswebBaseModel):
+    name: str = Field(description="Product name")
+    price: float = Field(gt=0, description="Product price in USD")
+    stock: int = Field(ge=0, description="Available stock count")
+
+# ✗ Less helpful
+class ProductDto(JswebBaseModel):
+    name: str
+    price: float
+    stock: int
+```
+
+### 3. Separate Request and Response DTOs
+
+```python
+# ✓ Good
+class CreateUserRequest(JswebBaseModel):
+    username: str
+    email: str
+    password: str
+
+class UserResponse(JswebBaseModel):
+    id: int
+    username: str
+    email: str
+    created_at: datetime
+
+# ✗ Less clear
+class UserDto(JswebBaseModel):
+    username: str
+    email: str
+    password: Optional[str] = None
+    id: Optional[int] = None
+    created_at: Optional[datetime] = None
+```
+
+### 4. Validate Business Logic
+
+```python
+# ✓ Good
+class TransferRequest(JswebBaseModel):
+    from_account: int
+    to_account: int
+    amount: float = Field(gt=0)
+    
+    @root_validator()
+    def accounts_different(cls, values):
+        if values.get('from_account') == values.get('to_account'):
+            raise ValueError('Cannot transfer to the same account')
+        return values
+
+# ✗ Less safe
+class TransferRequest(JswebBaseModel):
+    from_account: int
+    to_account: int
+    amount: float
+```
+
+### 5. Use Optional for Nullable Fields
+
+```python
+# ✓ Good
+from typing import Optional
+
+class UpdateUserRequest(JswebBaseModel):
+    name: Optional[str] = None
+    email: Optional[str] = None
+
+# ✗ Wrong
+class UpdateUserRequest(JswebBaseModel):
+    name: str = None  # Missing type hint
+    email: str = None
+```
diff --git a/docs/forms.md b/docs/forms.md
index 40491b7..16883f4 100644
--- a/docs/forms.md
+++ b/docs/forms.md
@@ -6,6 +6,7 @@ JsWeb provides a powerful and easy-to-use form library that simplifies the proce
 
 - [Creating a Form](#creating-a-form)
 - [Form Fields](#form-fields)
+- [Return Types](#return-types)
 - [Validators](#validators)
 - [Rendering Forms](#rendering-forms)
 - [Form Validation](#form-validation)
@@ -30,44 +31,83 @@ class LoginForm(Form):
 
 ## Form Fields
 
-JsWeb provides a variety of form fields for different input types:
+JsWeb provides a variety of form fields for different input types.
+
+### Return Types for Field Operations
+
+| Operation | Return Type | Description |
+|-----------|------------|-------------|
+| `field()` or `field.render()` | `Markup` (str) | HTML rendering of field |
+| `field.label` | `Label` | Form label object |
+| `field.validate(form)` | `bool` | Validation result |
+| `field.data` | `Any` | Field's current value |
+| `field.errors` | `List[str]` | List of validation errors |
 
 ### Text Fields
 
-| Field | Description | Example |
-|-------|-------------|---------|
-| `StringField` | Single-line text input | `StringField("Name")` |
-| `PasswordField` | Password input (hidden) | `PasswordField("Password")` |
-| `TextAreaField` | Multi-line text input | `TextAreaField("Comments")` |
-| `EmailField` | Email input | `EmailField("Email")` |
-| `URLField` | URL input | `URLField("Website")` |
-| `SearchField` | Search input | `SearchField("Search")` |
+| Field | Description | Example | Renders As |
+|-------|-------------|---------|-----------|
+| `StringField` | Single-line text input | `StringField("Name")` | `<input type="text">` |
+| `PasswordField` | Password input (hidden) | `PasswordField("Password")` | `<input type="password">` |
+| `TextAreaField` | Multi-line text input | `TextAreaField("Comments")` | `<textarea>` |
+| `EmailField` | Email input | `EmailField("Email")` | `<input type="email">` |
+| `URLField` | URL input | `URLField("Website")` | `<input type="url">` |
+| `SearchField` | Search input | `SearchField("Search")` | `<input type="search">` |
 
 ### Number & Boolean Fields
 
-| Field | Description | Example |
-|-------|-------------|---------|
-| `IntegerField` | Integer input | `IntegerField("Age")` |
-| `FloatField` | Decimal number input | `FloatField("Price")` |
-| `DecimalField` | High-precision decimal | `DecimalField("Amount")` |
-| `BooleanField` | Checkbox | `BooleanField("Agree to terms")` |
+| Field | Description | Example | Renders As |
+|-------|-------------|---------|-----------|
+| `IntegerField` | Integer input | `IntegerField("Age")` | `<input type="number">` |
+| `FloatField` | Decimal number input | `FloatField("Price")` | `<input type="number" step="any">` |
+| `DecimalField` | High-precision decimal | `DecimalField("Amount")` | `<input type="text">` |
+| `BooleanField` | Checkbox | `BooleanField("Agree to terms")` | `<input type="checkbox">` |
 
 ### Date & Time Fields
 
-| Field | Description | Example |
-|-------|-------------|---------|
-| `DateField` | Date picker | `DateField("Birth Date")` |
-| `TimeField` | Time picker | `TimeField("Start Time")` |
-| `DateTimeField` | Date & time picker | `DateTimeField("Appointment")` |
+| Field | Description | Example | Renders As |
+|-------|-------------|---------|-----------|
+| `DateField` | Date picker | `DateField("Birth Date")` | `<input type="date">` |
+| `TimeField` | Time picker | `TimeField("Start Time")` | `<input type="time">` |
+| `DateTimeField` | Date & time picker | `DateTimeField("Appointment")` | `<input type="datetime-local">` |
 
 ### Selection Fields
 
-| Field | Description | Example |
-|-------|-------------|---------|
-| `SelectField` | Dropdown list | `SelectField("Country", choices=[...])` |
-| `RadioField` | Radio button group | `RadioField("Gender", choices=[...])` |
-| `FileField` | File upload | `FileField("Upload")` |
-| `HiddenField` | Hidden field (CSRF token) | `HiddenField()` |
+| Field | Description | Example | Renders As |
+|-------|-------------|---------|-----------|
+| `SelectField` | Dropdown list | `SelectField("Country", choices=[...])` | `<select>` |
+| `RadioField` | Radio button group | `RadioField("Gender", choices=[...])` | `<input type="radio">` |
+| `FileField` | File upload | `FileField("Upload")` | `<input type="file">` |
+| `HiddenField` | Hidden field (CSRF token) | `HiddenField()` | `<input type="hidden">` |
+
+### Field Rendering Example
+
+```python
+from jsweb.forms import Form, StringField
+from markupsafe import Markup
+
+class MyForm(Form):
+    name = StringField("Your Name")
+
+@app.route("/form")
+async def form_page(req) -> HTMLResponse:
+    form = MyForm()
+    
+    # Render field - returns Markup (str-like)
+    html_input: Markup = form.name()      # <input type="text" id="name" name="name">
+    label_html: Markup = form.name.label  # <label for="name">Your Name</label>
+    
+    # Get field data
+    field_value = form.name.data          # type: Optional[str]
+    
+    # Validate field
+    is_valid: bool = form.name.validate(form)
+    
+    # Get validation errors
+    errors: List[str] = form.name.errors
+    
+    return html(f"{label_html} {html_input}")
+```
 
 ### Complete Example
 
@@ -89,7 +129,7 @@ class UserRegistrationForm(Form):
     csrf_token = HiddenField()
 ```
 
-## Validators
+## Return Types
 
 Validators check that submitted data is valid. Pass a list of validators to the `validators` argument:
 
@@ -158,19 +198,23 @@ class SignUpForm(Form):
 
 ## Rendering Forms
 
-Use the `render` function to pass the form to your template:
+Use the `render` function to pass the form to your template. The `render()` function returns `HTMLResponse`:
 
 ```python
-from jsweb.response import render
+from jsweb.response import render, HTMLResponse
 from .forms import LoginForm
 
 @app.route("/login", methods=["GET", "POST"])
-async def login(req):
+async def login(req) -> HTMLResponse:
     form = LoginForm(await req.form(), await req.files())
+    
+    # validate() returns bool
     if req.method == "POST" and form.validate():
         # Handle the login
-        username = form.username.data
+        username: str = form.username.data
         # ... authentication logic ...
+    
+    # render() returns HTMLResponse
     return render(req, "login.html", {"form": form})
 ```
 
@@ -178,28 +222,43 @@ async def login(req):
 
 ### Checking if Form is Valid
 
+The `validate()` method returns a `bool` indicating if all fields passed validation.
+
 ```python
-if form.validate():
+from typing import List, Dict, Any
+
+# Check if form is valid - returns bool
+is_valid: bool = form.validate()
+
+if is_valid:
     # Process form data
-    data = form.data  # All form data as dictionary
-    username = form.username.data
+    data: Dict[str, Any] = form.data  # All form data as dictionary
+    username: str = form.username.data
 else:
     # Form has errors
-    errors = form.errors  # Dictionary of field errors
+    errors: Dict[str, List[str]] = form.errors  # Dictionary of field errors
+    for field, error_list in errors.items():
+        print(f"{field}: {error_list}")
 ```
 
 ### Accessing Field Data
 
 ```python
+from typing import Any, List
+
 # Get specific field value
-username = form.username.data
+username: str = form.username.data
+
+# Get all form data - returns dict
+all_data: dict[str, Any] = form.data
 
-# Get all form data
-all_data = form.data  # Returns dict
+# Check if field has errors - returns bool
+has_errors: bool = bool(form.username.errors)
 
-# Check if field has errors
-if form.username.errors:
-    print(form.username.errors)  # List of error messages
+# Get error messages - returns List[str]
+error_messages: List[str] = form.username.errors
+for error in error_messages:
+    print(error)
 ```
 
 ### Rendering in Template
diff --git a/docs/getting-started.md b/docs/getting-started.md
index b7142f6..066e2f5 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -93,16 +93,54 @@ myproject/
 
 ### Key Files Explained
 
-| File          | Purpose                                                    |
-|---------------|-------------------------------------------------------------|
-| `app.py`      | Creates and configures your JsWeb application instance     |
-| `config.py`   | Stores application configuration (database, secret key, etc) |
-| `models.py`   | Define your database models/tables                          |
-| `views.py`    | Define your routes and request handlers                     |
-| `forms.py`    | Define your HTML forms and validation rules                |
-| `auth.py`     | Handle user authentication and authorization                |
-| `templates/`  | Store your HTML templates                                  |
-| `static/`     | Store CSS, JavaScript, and image files                      |
+| File          | Purpose                                                    | Returns/Type |
+|---------------|--------------------------------------------------------------|-------------|
+| `app.py`      | Creates and configures your JsWeb application instance     | `JsWebApp` |
+| `config.py`   | Stores application configuration (database, secret key, etc) | Config class |
+| `models.py`   | Define your database models/tables                          | Model classes |
+| `views.py`    | Define your routes and request handlers                     | Route handlers return `Response` or `str` |
+| `forms.py`    | Define your HTML forms and validation rules                 | Form classes |
+| `auth.py`     | Handle user authentication and authorization                | Auth utilities |
+| `templates/`  | Store your HTML templates                                   | Rendered by `render()` → `HTMLResponse` |
+| `static/`     | Store CSS, JavaScript, and image files                      | Served as static content |
+
+## Return Types in Your Project
+
+Here's a quick reference for common return types you'll see in your JsWeb handlers:
+
+```python
+from jsweb.response import render, html, json, HTMLResponse, JSONResponse
+from jsweb.database import ModelBase
+
+# Route handlers can return strings (auto-converted to HTMLResponse)
+@app.route("/")
+async def home(req) -> str:
+    return "Hello, World!"
+
+# Or explicitly return Response objects
+@app.route("/page")
+async def page(req) -> HTMLResponse:
+    return html("<h1>Welcome</h1>")
+
+# Render templates - always returns HTMLResponse
+@app.route("/about")
+async def about(req) -> HTMLResponse:
+    return render(req, "about.html", {})
+
+# JSON responses for APIs
+@app.route("/api/data")
+async def get_data(req) -> JSONResponse:
+    return json({"message": "success"})
+
+# Database queries return models or None
+from models import User
+user: Optional[User] = User.query.get(1)
+users: List[User] = User.query.all()
+
+# Database operations return None
+user.save()  # -> None
+user.delete()  # -> None
+```
 
 ## Running the Development Server
 
diff --git a/docs/response-types.md b/docs/response-types.md
new file mode 100644
index 0000000..cef77c7
--- /dev/null
+++ b/docs/response-types.md
@@ -0,0 +1,425 @@
+# Response Types
+
+JsWeb provides a comprehensive set of response classes for handling different types of HTTP responses. All response types inherit from the base `Response` class and support both synchronous and asynchronous handlers.
+
+## Table of Contents
+
+- [Response Base Class](#response-base-class)
+- [HTML Responses](#html-responses)
+- [JSON Responses](#json-responses)
+- [Redirects](#redirects)
+- [Error Responses](#error-responses)
+- [Helper Functions](#helper-functions)
+- [Cookie Management](#cookie-management)
+- [Auto-Conversion](#auto-conversion)
+- [Best Practices](#best-practices)
+
+## Response Base Class
+
+The `Response` class is the foundation for all response types. It encapsulates the HTTP response body, status code, and headers.
+
+```python
+from jsweb.response import Response
+
+@app.route("/")
+async def home(req) -> Response:
+    response = Response(
+        body="Hello, World!",
+        status_code=200,
+        headers={"X-Custom-Header": "value"},
+        content_type="text/plain"
+    )
+    return response
+```
+
+### Response Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `body` | `Union[str, bytes]` | Required | The response body content |
+| `status_code` | `int` | 200 | HTTP status code |
+| `headers` | `dict` | None | Dictionary of response headers |
+| `content_type` | `str` | Depends on subclass | MIME type of the response |
+
+### Response Methods
+
+#### `set_cookie()` → `None`
+
+Sets a cookie in the response.
+
+```python
+@app.route("/set-cookie")
+async def set_cookie_example(req) -> Response:
+    response = Response("Cookie set!")
+    response.set_cookie(
+        key="user_id",
+        value="12345",
+        max_age=3600,           # 1 hour
+        path="/",
+        secure=True,            # HTTPS only
+        httponly=True,          # JavaScript cannot access
+        samesite='Strict'       # CSRF protection
+    )
+    return response
+```
+
+**Parameters:**
+- `key` (str): Cookie name
+- `value` (str): Cookie value
+- `max_age` (int, optional): Lifetime in seconds
+- `expires` (datetime, optional): Expiration datetime
+- `path` (str): Path scope (default: "/")
+- `domain` (str, optional): Domain scope
+- `secure` (bool): HTTPS only (default: False)
+- `httponly` (bool): Accessible via HTTP only (default: False)
+- `samesite` (str): 'Strict', 'Lax', or 'None' (default: 'Lax')
+
+#### `delete_cookie()` → `None`
+
+Deletes a cookie by setting its expiration to the past.
+
+```python
+@app.route("/logout")
+async def logout(req) -> Response:
+    response = Response("Logged out")
+    response.delete_cookie("session_id")
+    return response
+```
+
+## HTML Responses
+
+`HTMLResponse` automatically sets the correct content type and injects the JsWeb JavaScript library for seamless AJAX functionality.
+
+**Return Type:** `HTMLResponse`
+
+```python
+from jsweb.response import HTMLResponse
+
+@app.route("/page")
+async def page(req) -> HTMLResponse:
+    html_content = """
+    <html>
+        <head><title>My Page</title></head>
+        <body><h1>Hello!</h1></body>
+    </html>
+    """
+    return HTMLResponse(html_content)
+```
+
+### Features
+
+- Automatically injects `jsweb.js` for AJAX support
+- Sets `Content-Type: text/html`
+- Supports AJAX partial templates
+
+### AJAX Template Partials
+
+For AJAX requests (requests with `X-Requested-With: XMLHttpRequest`), JsWeb looks for partial templates:
+
+```python
+# Project structure
+templates/
+  page.html           # Full page template
+  partials/page.html  # Partial for AJAX requests
+
+@app.route("/content")
+async def get_content(req) -> HTMLResponse:
+    # AJAX requests will load partials/content.html
+    # Regular requests will load content.html
+    return render(req, "content.html", {})
+```
+
+## JSON Responses
+
+`JSONResponse` automatically serializes Python objects to JSON and sets the appropriate content type.
+
+**Return Type:** `JSONResponse`
+
+```python
+from jsweb.response import JSONResponse
+
+@app.route("/api/users")
+async def list_users(req) -> JSONResponse:
+    users = [
+        {"id": 1, "name": "Alice"},
+        {"id": 2, "name": "Bob"}
+    ]
+    return JSONResponse(users)
+```
+
+### Features
+
+- Automatic JSON serialization
+- Sets `Content-Type: application/json`
+- Supports custom status codes
+
+### JSON with Status Codes
+
+```python
+@app.route("/api/create", methods=["POST"])
+async def create_item(req) -> JSONResponse:
+    # Return 201 Created status
+    return JSONResponse(
+        {"id": 1, "message": "Item created"},
+        status_code=201
+    )
+```
+
+## Redirects
+
+`RedirectResponse` handles HTTP redirects with proper status codes.
+
+**Return Type:** `RedirectResponse`
+
+```python
+from jsweb.response import RedirectResponse
+
+@app.route("/old-page")
+async def old_page(req) -> RedirectResponse:
+    # 302 temporary redirect (default)
+    return RedirectResponse("/new-page")
+
+@app.route("/moved")
+async def moved(req) -> RedirectResponse:
+    # 301 permanent redirect
+    return RedirectResponse("/new-location", status_code=301)
+```
+
+### Status Codes for Redirects
+
+| Code | Type | Use Case |
+|------|------|----------|
+| 301 | Permanent | Resource moved permanently |
+| 302 | Temporary | Temporary redirect (default) |
+| 303 | See Other | Redirect after POST (POST→GET) |
+| 307 | Temporary | Like 302 but preserves HTTP method |
+| 308 | Permanent | Like 301 but preserves HTTP method |
+
+## Error Responses
+
+### Forbidden (403)
+
+`Forbidden` provides a convenient response for authorization failures.
+
+**Return Type:** `Forbidden`
+
+```python
+from jsweb.response import Forbidden
+from jsweb.auth import get_current_user
+
+@app.route("/admin")
+async def admin_panel(req) -> Union[HTMLResponse, Forbidden]:
+    user = get_current_user(req)
+    if not user or not user.is_admin:
+        return Forbidden("You don't have permission to access this page")
+    
+    return render(req, "admin.html", {})
+```
+
+### Custom Error Responses
+
+```python
+@app.route("/api/user/<int:user_id>")
+async def get_user(req, user_id) -> Union[JSONResponse, Response]:
+    user = User.query.get(user_id)
+    if not user:
+        return JSONResponse(
+            {"error": "User not found"},
+            status_code=404
+        )
+    return JSONResponse(user.to_dict())
+```
+
+## Helper Functions
+
+JsWeb provides convenient shortcut functions for creating responses.
+
+### `html()` → `HTMLResponse`
+
+Creates an HTML response with a single function call.
+
+```python
+from jsweb.response import html
+
+@app.route("/")
+async def home(req) -> HTMLResponse:
+    return html("<h1>Welcome!</h1>")
+
+# With custom status code
+@app.route("/created")
+async def created(req) -> HTMLResponse:
+    return html("<p>Page created</p>", status_code=201)
+```
+
+### `json()` → `JSONResponse`
+
+Creates a JSON response with a single function call.
+
+```python
+from jsweb.response import json
+
+@app.route("/api/data")
+async def get_data(req) -> JSONResponse:
+    return json({"status": "ok", "data": [1, 2, 3]})
+
+# With custom status code
+@app.route("/api/error")
+async def error_endpoint(req) -> JSONResponse:
+    return json(
+        {"error": "Invalid request"},
+        status_code=400
+    )
+```
+
+### `redirect()` → `RedirectResponse`
+
+Creates a redirect response with a single function call.
+
+```python
+from jsweb.response import redirect
+
+@app.route("/go")
+async def go(req) -> RedirectResponse:
+    return redirect("/home")
+
+# With custom status code
+@app.route("/moved-permanently")
+async def moved(req) -> RedirectResponse:
+    return redirect("/new-home", status_code=301)
+```
+
+## Auto-Conversion
+
+JsWeb automatically converts string responses to `HTMLResponse` for convenience.
+
+```python
+@app.route("/")
+async def home(req):  # No explicit return type needed
+    return "Hello, World!"  # Automatically converted to HTMLResponse
+```
+
+However, explicitly typing your responses is recommended for clarity:
+
+```python
+@app.route("/")
+async def home(req) -> HTMLResponse:
+    return "Hello, World!"
+```
+
+## Cookie Management
+
+### Secure Cookie Settings
+
+```python
+@app.route("/login")
+async def login(req) -> Response:
+    response = Response("Logged in")
+    response.set_cookie(
+        key="session",
+        value=generate_session_token(),
+        max_age=86400,      # 24 hours
+        path="/",
+        secure=True,        # Only send over HTTPS
+        httponly=True,      # Prevent JavaScript access
+        samesite='Strict'   # Prevent CSRF
+    )
+    return response
+```
+
+### Cookie Security Best Practices
+
+| Setting | Recommendation | Purpose |
+|---------|----------------|---------|
+| `secure=True` | For production | Only send over HTTPS |
+| `httponly=True` | For sensitive data | Prevent XSS attacks |
+| `samesite='Strict'` | For login/session | Prevent CSRF attacks |
+| `max_age` | Set appropriate TTL | Limit session duration |
+
+### Multiple Cookies
+
+```python
+@app.route("/auth")
+async def authenticate(req) -> Response:
+    response = Response("Authenticated")
+    
+    # Set multiple cookies
+    response.set_cookie("user_id", "12345")
+    response.set_cookie("preferences", "dark_mode")
+    response.set_cookie("auth_token", token, httponly=True)
+    
+    return response
+```
+
+## Best Practices
+
+### 1. Use Type Hints
+
+Always specify return types for clarity and IDE support:
+
+```python
+@app.route("/page")
+async def page(req) -> HTMLResponse:
+    return render(req, "page.html", {})
+```
+
+### 2. Handle Errors Gracefully
+
+```python
+@app.route("/api/users/<int:user_id>")
+async def get_user(req, user_id) -> Union[JSONResponse, Response]:
+    try:
+        user = User.query.get(user_id)
+        if not user:
+            return JSONResponse(
+                {"error": "Not found"},
+                status_code=404
+            )
+        return JSONResponse(user.to_dict())
+    except Exception as e:
+        return JSONResponse(
+            {"error": "Server error"},
+            status_code=500
+        )
+```
+
+### 3. Use Helper Functions for Simplicity
+
+```python
+# ✓ Good
+return json({"status": "ok"})
+return html("<h1>Title</h1>")
+return redirect("/home")
+
+# ✗ Less clear
+return JSONResponse({"status": "ok"})
+return HTMLResponse("<h1>Title</h1>")
+return RedirectResponse("/home")
+```
+
+### 4. Secure Cookies in Production
+
+```python
+# ✓ Production-ready
+response.set_cookie(
+    "session",
+    token,
+    max_age=3600,
+    secure=True,        # HTTPS only
+    httponly=True,      # No JavaScript access
+    samesite='Strict'   # CSRF protection
+)
+
+# ✗ Insecure
+response.set_cookie("session", token)
+```
+
+### 5. Set Appropriate Status Codes
+
+```python
+# ✓ Correct
+return JSONResponse({"error": "Not found"}, status_code=404)
+return JSONResponse({"data": user}, status_code=200)
+
+# ✗ Less explicit
+return JSONResponse({"error": "Not found"})  # Defaults to 200
+```
diff --git a/docs/routing.md b/docs/routing.md
index cd59578..7a64f8f 100644
--- a/docs/routing.md
+++ b/docs/routing.md
@@ -5,6 +5,7 @@ Routing is the process of mapping URLs to the functions that handle them. In JsW
 ## Table of Contents
 
 - [Basic Routing](#basic-routing)
+- [Return Types](#return-types)
 - [HTTP Methods](#http-methods)
 - [URL Parameters](#url-parameters)
 - [Type Converters](#type-converters)
@@ -32,6 +33,66 @@ In this example, we're mapping the root URL (`/`) to the `home` function. When a
 !!! note "Async Functions"
     JsWeb routes are always async functions. This allows your application to handle multiple concurrent requests efficiently.
 
+## Return Types
+
+All route handlers must return a **Response object** or a **string** (which is auto-converted to `HTMLResponse`).
+
+### Valid Return Types
+
+```python
+from jsweb.response import Response, HTMLResponse, JSONResponse, RedirectResponse, html, json, redirect
+
+# String - automatically converted to HTMLResponse
+@app.route("/")
+async def home(req):  # No explicit return type
+    return "Hello, World!"
+
+# HTMLResponse explicitly typed
+@app.route("/page")
+async def page(req) -> HTMLResponse:
+    return html("<h1>Welcome</h1>")
+
+# JSONResponse
+@app.route("/api/data")
+async def get_data(req) -> JSONResponse:
+    return json({"status": "ok"})
+
+# RedirectResponse
+@app.route("/go")
+async def go(req) -> RedirectResponse:
+    return redirect("/home")
+
+# Base Response class
+@app.route("/custom")
+async def custom(req) -> Response:
+    return Response("Custom content", status_code=200)
+```
+
+### Return Type Reference
+
+| Return Type | Usage | Example |
+|------------|-------|---------|
+| `str` | Simple HTML | `return "Hello"` |
+| `HTMLResponse` | Rendered HTML | `return render(req, "template.html", {})` |
+| `JSONResponse` | JSON API responses | `return json({"data": [1,2,3]})` |
+| `RedirectResponse` | HTTP redirects | `return redirect("/page")` |
+| `Response` | Custom responses | `return Response(body, status_code=200)` |
+
+!!! warning "Type Mismatch"
+    Ensure your return type matches the actual value returned. This helps with IDE autocomplete and catches bugs early:
+    
+    ```python
+    # ✓ Correct
+    @app.route("/api")
+    async def api(req) -> JSONResponse:
+        return json({"data": "value"})
+    
+    # ✗ Incorrect type hint
+    @app.route("/page")
+    async def page(req) -> JSONResponse:
+        return "HTML content"  # Mismatch!
+    ```
+
 ## HTTP Methods
 
 By default, a route only responds to `GET` requests. You can specify the HTTP methods that a route should handle using the `methods` argument.
@@ -100,28 +161,28 @@ async def profile_by_id(req, user_id):
 ```python
 # String (default)
 @app.route("/search/<query>")
-async def search(req, query):
+async def search(req, query) -> str:
     return f"Searching for: {query}"
 
 # Integer
 @app.route("/post/<int:post_id>")
-async def get_post(req, post_id):
+async def get_post(req, post_id) -> str:
     return f"Viewing post {post_id}"
 
 # Float
 @app.route("/temperature/<float:celsius>")
-async def convert_temp(req, celsius):
+async def convert_temp(req, celsius) -> str:
     fahrenheit = (celsius * 9/5) + 32
     return f"{celsius}°C is {fahrenheit}°F"
 
 # Path (allows slashes)
 @app.route("/files/<path:filepath>")
-async def serve_file(req, filepath):
+async def serve_file(req, filepath) -> str:
     return f"Serving: {filepath}"
 
 # UUID
 @app.route("/item/<uuid:item_id>")
-async def get_item(req, item_id):
+async def get_item(req, item_id) -> str:
     return f"Item: {item_id}"
 ```
 
@@ -130,8 +191,11 @@ async def get_item(req, item_id):
     
     ```python
     @app.route("/post/<int:post_id>/comment/<int:comment_id>")
-    async def get_comment(req, post_id, comment_id):
-        return f"Post {post_id}, Comment {comment_id}"
+    async def get_comment(req, post_id, comment_id) -> JSONResponse:
+        return json({
+            "post_id": post_id,
+            "comment_id": comment_id
+        })
     ```
 
 ## Route Organization with Blueprints
@@ -145,12 +209,12 @@ from jsweb import Blueprint
 user_bp = Blueprint('users', url_prefix='/users')
 
 @user_bp.route('/')
-async def user_list(req):
-    return "All users"
+async def user_list(req) -> JSONResponse:
+    return json({"users": []})
 
 @user_bp.route('/<int:user_id>')
-async def user_detail(req, user_id):
-    return f"User {user_id}"
+async def user_detail(req, user_id) -> JSONResponse:
+    return json({"user_id": user_id})
 
 # Register in app.py
 from views import user_bp
@@ -168,20 +232,20 @@ See [Blueprints](blueprints.md) for more details.
 ```python
 @app.route("/api/items")
 @app.route("/api/items/<int:item_id>")
-async def get_items(req, item_id=None):
+async def get_items(req, item_id: Optional[int] = None) -> JSONResponse:
     if item_id:
-        return f"Item {item_id}"
-    return "All items"
+        return json({"item_id": item_id})
+    return json({"items": []})
 ```
 
 ### Query Parameters
 
 ```python
 @app.route("/search")
-async def search(req):
-    query = req.query_params.get('q', '')
-    page = req.query_params.get('page', '1')
-    return f"Searching for: {query} (page {page})"
+async def search(req) -> HTMLResponse:
+    query = req.query.get('q', '')
+    page = req.query.get('page', '1')
+    return html(f"<p>Searching for: {query} (page {page})</p>")
 ```
 
 Usage: `/search?q=python&page=2`
@@ -189,14 +253,16 @@ Usage: `/search?q=python&page=2`
 ### Dynamic Responses
 
 ```python
+from jsweb.response import JSONResponse
+
 @app.route("/api/users/<int:user_id>", methods=["GET", "PUT", "DELETE"])
-async def manage_user(req, user_id):
+async def manage_user(req, user_id) -> JSONResponse:
     if req.method == "GET":
-        return {"user_id": user_id, "action": "retrieve"}
+        return json({"user_id": user_id, "action": "retrieve"})
     elif req.method == "PUT":
-        return {"user_id": user_id, "action": "update"}
+        return json({"user_id": user_id, "action": "update"})
     elif req.method == "DELETE":
-        return {"user_id": user_id, "action": "delete"}
+        return json({"user_id": user_id, "action": "delete"})
 ```
 
 ## Best Practices
diff --git a/docs/templating.md b/docs/templating.md
index 9ca2baa..3024b2d 100644
--- a/docs/templating.md
+++ b/docs/templating.md
@@ -5,6 +5,7 @@ JsWeb uses the [Jinja2](https://jinja.palletsprojects.com/) templating engine to
 ## Table of Contents
 
 - [Rendering Templates](#rendering-templates)
+- [Return Types](#return-types)
 - [Template Variables](#template-variables)
 - [Control Structures](#control-structures)
 - [Template Filters](#template-filters)
@@ -17,19 +18,69 @@ JsWeb uses the [Jinja2](https://jinja.palletsprojects.com/) templating engine to
 
 To render a template, use the `render` function from the `jsweb.response` module:
 
+**Return Type:** `HTMLResponse`
+
 ```python
-from jsweb.response import render
+from jsweb.response import render, HTMLResponse
 
 @app.route("/")
-async def home(req):
+async def home(req) -> HTMLResponse:
     return render(req, "index.html", {"name": "World"})
 ```
 
 In this example, we're rendering the `index.html` template and passing a context dictionary with a `name` variable. The `render` function automatically looks for templates in the `templates` folder of your project.
 
+### render() Function Signature
+
+```python
+def render(
+    req: Request,
+    template_name: str,
+    context: dict = None
+) -> HTMLResponse:
+    """
+    Renders a Jinja2 template into an HTMLResponse.
+    
+    Args:
+        req: The request object
+        template_name: Name of the template file
+        context: Dictionary of context variables
+        
+    Returns:
+        HTMLResponse: The rendered HTML response
+    """
+```
+
 !!! tip "Template Location"
     Templates must be in a `templates` folder in your project root. JsWeb automatically discovers and serves them.
 
+## Return Types
+
+All templating functions return `HTMLResponse` objects:
+
+### Helper Functions
+
+```python
+from jsweb.response import render, html, HTMLResponse
+
+# render() returns HTMLResponse
+@app.route("/page")
+async def page(req) -> HTMLResponse:
+    return render(req, "page.html", {"title": "My Page"})
+
+# html() helper returns HTMLResponse
+@app.route("/simple")
+async def simple(req) -> HTMLResponse:
+    return html("<h1>Hello</h1>")
+```
+
+### Return Type Reference
+
+| Function | Return Type | Usage |
+|----------|------------|-------|
+| `render()` | `HTMLResponse` | Load and render template files |
+| `html()` | `HTMLResponse` | Quick HTML response |
+
 ## Template Variables
 
 You can use variables in your templates by enclosing them in double curly braces (`{{ ... }}`).
@@ -41,16 +92,25 @@ You can use variables in your templates by enclosing them in double curly braces
 <p>Items count: {{ items | length }}</p>
 ```
 
-### Variable Examples
+### Variable Examples with Type Hints
 
 ```python
-# Python
-context = {
-    "name": "Alice",
-    "user": {"username": "alice", "email": "alice@example.com"},
-    "items": [1, 2, 3, 4, 5],
-    "count": 42
-}
+from jsweb.response import render, HTMLResponse
+from typing import List, Dict, Any
+
+@app.route("/")
+async def home(req) -> HTMLResponse:
+    # Context with various types
+    context: Dict[str, Any] = {
+        "name": "Alice",              # str
+        "user": {                     # dict
+            "username": "alice",
+            "email": "alice@example.com"
+        },
+        "items": [1, 2, 3, 4, 5],    # list
+        "count": 42                   # int
+    }
+    return render(req, "index.html", context)
 ```
 
 ```html
@@ -268,25 +328,31 @@ Macros are reusable template functions. They help eliminate code duplication for
 
 ## Custom Filters
 
-Create custom filters to extend Jinja2's functionality:
+Create custom filters to extend Jinja2's functionality. Filters always return a value (typically `str` or modified value):
 
 ```python
+from typing import str, Any
+
 # app.py
 @app.filter("markdown")
-def markdown_filter(text):
+def markdown_filter(text: str) -> str:
+    """Convert markdown text to HTML"""
     import markdown
     return markdown.markdown(text)
 
 @app.filter("slugify")
-def slugify_filter(text):
+def slugify_filter(text: str) -> str:
+    """Convert text to URL-safe slug"""
     return text.lower().replace(' ', '-')
 
 @app.filter("currency")
-def currency_filter(value):
+def currency_filter(value: float) -> str:
+    """Format number as currency"""
     return f"${value:.2f}"
 
 @app.filter("ordinal")
-def ordinal_filter(n):
+def ordinal_filter(n: int) -> str:
+    """Convert number to ordinal (1st, 2nd, etc)"""
     if n % 10 == 1 and n % 100 != 11:
         return f"{n}st"
     elif n % 10 == 2 and n % 100 != 12:
@@ -297,6 +363,15 @@ def ordinal_filter(n):
         return f"{n}th"
 ```
 
+### Filter Return Types
+
+| Filter | Input Type | Output Type |
+|--------|-----------|-------------|
+| markdown | `str` | `str` (HTML) |
+| slugify | `str` | `str` |
+| currency | `float` | `str` |
+| ordinal | `int` | `str` |
+
 ### Using Custom Filters
 
 ```html
@@ -308,25 +383,6 @@ def ordinal_filter(n):
 
 !!! tip "Filter Naming"
     Use lowercase, descriptive names for your filters. Always test them before using in production.
-
-## Best Practices
-
-!!! warning "Security: XSS Prevention"
-    By default, Jinja2 does NOT auto-escape HTML. Be careful with user input:
-    
-    ```html
-    {# Good: escapes HTML #}
-    {{ user_input | escape }}
-    
-    {# Or use auto-escaping in Python #}
-    from markupsafe import escape
-    escaped = escape(user_input)
-    ```
-
-!!! tip "Keep Logic Simple"
-    Keep complex logic in Python, not templates:
-    
-    ```html
     {# Bad: Complex logic in template #}
     {% if user and user.is_active and user.role == 'admin' and user.permissions.can_edit %}
     
diff --git a/mkdocs.yml b/mkdocs.yml
index 2d426fb..2659baf 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -52,6 +52,9 @@ nav:
         - 'Database': 'database.md'
         - 'Blueprints': 'blueprints.md'
         - 'Admin': 'admin.md'
+    - 'API Reference':
+        - 'Response Types': 'response-types.md'
+        - 'DTOs & Data Models': 'dto-models.md'
     - 'Command-Line Interface': 'cli.md'
     - 'OpenAPI Guide': 'JSWEB_OPENAPI_GUIDE.md'