Overview

Azu is a modern, high-performance web framework for Crystal that emphasizes type safety, modularity, and real-time capabilities. Built on Crystal's powerful static type system and compile-time optimizations, Azu provides a contract-driven architecture that enables developers to build robust, scalable web applications with strong guarantees about correctness.

Framework Philosophy

Azu follows three core principles:

1. Type Safety First: Leverage Crystal's static type system to catch errors at compile time

2. Contract-Driven Design: Every request and response is governed by explicit contracts

3. Performance by Design: Built for speed with compile-time optimizations and efficient routing

Architecture Overview

Azu applications are built around endpoints - self-contained handlers that process incoming requests. Each endpoint:

• Defines a Request Contract that validates and types incoming data

• Returns a Response Object that handles content rendering

• Operates within a middleware chain for cross-cutting concerns

• Can handle both HTTP requests and WebSocket connections

Key Features

Type-Safe Request Contracts

Every endpoint works with strongly-typed request objects that validate input:

struct UserRequest
  include Azu::Request

  @name : String
  @email : String
  @age : Int32?

  validate :name, presence: true, size: 2..50
  validate :email, format: /@/
  validate :age, range: 13..120, if: ->(user : UserRequest) { !user.age.nil? }
end

Performance-Optimized Routing

Built on the high-performance Radix routing tree with path caching:

struct UserEndpoint
  include Endpoint(UserRequest, UserResponse)

  post "/users"           # Create user
  get "/users/:id"        # Get user by ID
  put "/users/:id"        # Update user
  delete "/users/:id"     # Delete user
end

Real-Time WebSocket Support

Native WebSocket channels with built-in connection management:

class ChatChannel < Azu::Channel
  ws "/chat/:room_id"

  def on_connect
    join_room(params["room_id"])
  end

  def on_message(message)
    broadcast_to_room(message)
  end
end

Development Tools & Performance Monitoring

Comprehensive built-in tools for optimization and debugging:

# Built-in profiler for code analysis
result = Azu::DevelopmentTools.profile("database_query") do
  User.where(active: true).limit(100).to_a
end

# Memory leak detection
detector = Azu::DevelopmentTools.memory_detector
detector.start_monitoring(30.seconds)

# Load testing and benchmarking
results = Azu::DevelopmentTools::Benchmark.load_test(
  url: "http://localhost:4000/api/users",
  concurrent: 10,
  requests: 1000
)

Beautiful Terminal Logging

Stunning, colorful performance reports that make monitoring delightful:

# Generate beautiful performance reports
Azu::PerformanceReporter.log_beautiful_report

# Compact performance summaries
Azu::PerformanceReporter.log_summary

# Real-time health monitoring
Azu::PerformanceReporter.log_health_check

Advanced Caching System

Multi-layered caching with automatic metrics and invalidation:

# Distributed Redis caching
cache = Azu::Cache::Manager.new(
  store: Azu::Cache::Redis.new(redis_client),
  ttl: 1.hour
)

# Automatic cache metrics tracking
cache.with_metrics("user_data") do |store|
  store.fetch("user:#{id}") { User.find(id) }
end

Flexible Response System

Multiple response formats with content negotiation:

struct UserResponse
  include Azu::Response

  def initialize(@user : User)
  end

  def render
    case content_type
    when "application/json"
      @user.to_json
    when "text/html"
      render_template("user.html", user: @user)
    when "application/xml"
      @user.to_xml
    end
  end
end

Comprehensive Middleware System

Production-ready middleware for security, logging, and optimization:

MyApp.start [
  Azu::Handler::PerformanceMonitor.new,  # Automatic performance tracking
  Azu::Handler::CORS.new,                # Cross-origin support
  Azu::Handler::CSRF.new,                # CSRF protection
  Azu::Handler::Throttle.new,            # Rate limiting
  Azu::Handler::Logger.new,              # Structured logging
  Azu::Handler::Static.new,              # Static file serving
  Azu::Handler::Rescuer.new              # Error handling
]

Performance Characteristics

Azu is designed for high-performance applications:

• Zero-overhead abstractions: Compile-time type checking and optimization

• Efficient routing: Radix tree with O(log n) lookup and path caching

• Memory efficient: Struct-based endpoints avoid unnecessary allocations

• Concurrent by default: Crystal's fiber-based concurrency model

Benchmark Results

Framework	Requests/sec	Memory Usage	Startup Time
Azu	85,000	12MB	150ms
Kemal	82,000	15MB	200ms
Lucky	78,000	18MB	300ms

Benchmarks run on: Intel i7-10700K, 32GB RAM, Crystal 1.16.0

Framework Components

Core Modules

• Router: High-performance request routing with method override support

• Endpoint: Type-safe request handlers with contract validation

• Request: Serializable request contracts with built-in validation

• Response: Flexible response objects supporting multiple formats

• Channel: WebSocket connection management and real-time communication

• Component: Server-side components with client synchronization

Middleware System

• CORS: Cross-origin resource sharing with configurable policies

• CSRF: Cross-site request forgery protection

• Logger: Structured logging with configurable formats

• Static: Efficient static file serving with caching

• Throttle: Rate limiting with configurable strategies

• Rescuer: Centralized error handling and reporting

Template Engine

• Crinja: Jinja2-compatible templating with Crystal integration

• Markup DSL: Type-safe HTML generation

• Hot Reload: Development-time template reloading

Development Experience

Azu prioritizes developer experience through:

1. Compile-time Error Detection: Catch bugs before deployment

2. IDE Integration: Full Crystal language server support

3. Hot Reloading: Instant template updates in development

4. Comprehensive Error Pages: Detailed exception information

5. Built-in Testing Support: Test-friendly architecture

Getting Started

The fastest way to start with Azu is to create a minimal application:

require "azu"

module MyApp
  include Azu

  configure do
    port = 3000
    host = "localhost"
  end
end

struct HelloEndpoint
  include Endpoint(EmptyRequest, TextResponse)

  get "/"

  def call : TextResponse
    TextResponse.new("Hello, Azu!")
  end
end

MyApp.start([
  Azu::Handler::Logger.new,
  Azu::Handler::Rescuer.new
])

Use Cases

Azu excels in scenarios requiring:

• API Development: Type-safe REST and GraphQL APIs

• Real-time Applications: Chat systems, live dashboards, gaming

• High-Performance Services: Microservices, data processing

• Full-Stack Applications: Server-rendered applications with real-time features

Community and Ecosystem

• Documentation: Comprehensive guides and API reference

• Examples: Real-world application examples

• Community: Active Discord community and GitHub discussions

• Plugins: Growing ecosystem of extensions and integrations

---

Next Steps:

• Introduction - What is Azu and why use it?

• Quickstart - Get up and running in 5 minutes

• Installation - Install Azu and set up your development environment

• Tutorial - Build a complete user management API

Documentation Structure

Getting Started

• Introduction - What is Azu and why use it?

• Quickstart - Get up and running in 5 minutes

• Installation - Install Azu and set up your development environment

• Tutorial - Build a complete user management API

Fundamentals

• Architecture - Understanding Azu's architecture

• Endpoints - Type-safe HTTP endpoints

• Requests - Structured request handling

• Responses - Structured response handling

• Routing - URL routing and path parameters

• Middleware - Middleware and request processing

Features

• Templates - Template rendering and hot reloading

• WebSockets - Real-time communication

• Components - Interactive UI components

• Caching - Application caching

• File Uploads - File upload handling

• Validation - Request validation

Advanced

• Performance - Performance optimization

• Monitoring - Application monitoring

• Async Logging - Asynchronous logging

• Content Negotiation - Content type handling

• Environments - Environment configuration

API Reference

• Core - Core Azu modules and classes

• Handlers - Middleware handlers

• Configuration - Configuration options

• Errors - Error handling and types

Deployment

• Production - Production deployment guide

• Docker - Containerized deployment

• Scaling - Scaling strategies

Testing

• Unit Testing - Unit testing strategies

• Integration Testing - Integration testing

• WebSocket Testing - WebSocket testing

Migration & Compatibility

• Version Upgrades - Upgrading Azu versions

• Breaking Changes - Breaking change documentation

FAQ & Troubleshooting

• Frequently Asked Questions - Common questions and answers

Contributing

• Development Setup - Setting up development environment

• Code Standards - Coding standards and guidelines

• Roadmap - Development roadmap