Architecture

Understanding Azu's architecture is key to building effective applications. This guide covers the core architectural patterns, request lifecycle, and design principles that make Azu powerful and type-safe.

Core Architecture Principles

Type Safety First

Azu is built around Crystal's powerful type system, providing compile-time guarantees for:

• Request Validation: All incoming data is validated at compile time

• Response Structure: Response objects are type-safe and consistent

• Route Parameters: URL parameters are typed and validated

• WebSocket Messages: Real-time communication is type-safe

Component-Based Design

Azu follows a modular, component-based architecture:

• Endpoints: Self-contained request handlers

• Request Contracts: Type-safe input validation

• Response Objects: Structured output handling

• Channels: Real-time communication handlers

• Components: Reusable UI components

Performance by Design

Built for high performance:

• Compile-time Optimization: Crystal's compiler optimizes your code

• Memory Efficiency: Predictable memory usage with no GC pauses

• Concurrent Processing: Handle thousands of connections efficiently

• Minimal Overhead: Framework adds minimal runtime cost

Request-Response Lifecycle

1. Request Processing

When a request arrives:

1. HTTP Server: Crystal's built-in HTTP server receives the request

2. Middleware Chain: Request passes through configured middleware

3. Router: Routes the request to the appropriate endpoint

4. Endpoint: Type-safe endpoint processes the request

2. Request Validation

struct UserRequest
  include Azu::Request

  @name : String
  @email : String

  validate name, presence: true, length: {min: 2, max: 50}
  validate email, presence: true, format: /\A[\w+\-.]+@[a-z\d\-]+(\.[a-z\d\-]+)*\.[a-z]+\z/i
end

Request contracts automatically:

• Parse and validate incoming data

• Provide type-safe access to parameters

• Generate detailed error messages

• Ensure data integrity

3. Business Logic

struct UserEndpoint
  include Azu::Endpoint(UserRequest, UserResponse)

  post "/users"

  def call : UserResponse
    # Type-safe access to validated data
    user = create_user(user_request.name, user_request.email)
    UserResponse.new(user)
  end
end

4. Response Generation

struct UserResponse
  include Azu::Response

  def initialize(@user : User)
  end

  def render
    {
      id: @user.id,
      name: @user.name,
      email: @user.email,
      created_at: @user.created_at.to_rfc3339
    }.to_json
  end
end

Middleware Architecture

Azu uses a middleware chain pattern for request processing:

Built-in Middleware

• RequestId: Adds unique request identifiers

• Logger: Request/response logging

• CORS: Cross-origin resource sharing

• Static: Static file serving

• Rescuer: Error handling and recovery

Custom Middleware

class CustomMiddleware
  include HTTP::Handler

  def call(context : HTTP::Server::Context)
    # Pre-processing
    Log.info { "Processing request: #{context.request.path}" }

    # Call next middleware
    call_next(context)

    # Post-processing
    Log.info { "Request completed: #{context.response.status_code}" }
  end
end

Routing System

Azu uses a high-performance routing tree based on Radix:

router do
  root :web, HomeEndpoint

  routes :web, "/api" do
    get "/users", ListUsersEndpoint
    get "/users/:id", ShowUserEndpoint
    post "/users", CreateUserEndpoint
    put "/users/:id", UpdateUserEndpoint
    delete "/users/:id", DeleteUserEndpoint
  end

  routes :web, "/admin" do
    get "/dashboard", AdminDashboardEndpoint
  end
end

Route Features

• HTTP Methods: Support for all standard HTTP methods

• Path Parameters: Typed URL parameters (:id, :slug)

• Route Groups: Organize related routes

• Nested Routes: Hierarchical route organization

• Route Constraints: Additional validation rules

WebSocket Architecture

Real-time communication in Azu:

Channel Pattern

class NotificationChannel < Azu::Channel
  CONNECTIONS = Set(HTTP::WebSocket).new

  ws "/notifications"

  def on_connect
    CONNECTIONS << socket.not_nil!
    send_welcome_message
  end

  def on_message(message : String)
    handle_message(JSON.parse(message))
  end

  def on_close(code, message)
    CONNECTIONS.delete(socket)
  end

  def self.broadcast_to_all(data)
    CONNECTIONS.each { |socket| socket.send(data.to_json) }
  end
end

Component System

Live components for interactive UI:

class CounterComponent
  include Azu::Component

  @count = 0

  def content
    div do
      text "Count: #{@count}"
      button "Increment", onclick: "increment"
    end
  end

  def on_event("increment", data)
    @count += 1
    update!
  end
end

Component Lifecycle

1. Mount: Component is created and registered

2. Render: Initial HTML is generated

3. Event Handling: Client events are processed

4. Update: Component state changes trigger re-renders

5. Unmount: Component is cleaned up

Template System

Azu includes a powerful template engine based on Jinja2:

Template Features

• Variable Interpolation: {{ variable }}

• Control Structures: {% if %} loops and conditionals

• Template Inheritance: Extend base templates

• Hot Reload: Automatic template reloading in development

• Markup DSL: Programmatic HTML generation

Template Rendering

struct UserPage
  include Azu::Response
  include Azu::Templates::Renderable

  def initialize(@user : User)
  end

  def render
    view "users/show.html", {
      user: @user,
      title: "User Profile"
    }
  end
end

Configuration System

Centralized configuration with environment support:

module MyApp
  include Azu

  configure do |config|
    # Server configuration
    config.host = "0.0.0.0"
    config.port = 3000
    config.env = "development"

    # Template configuration
    config.templates.path = ["templates"]
    config.template_hot_reload = config.env.development?

    # Upload configuration
    config.upload.max_file_size = 10.megabytes
    config.upload.temp_dir = "/tmp/uploads"

    # Logging configuration
    config.log.level = config.env.development? ? Log::Severity::DEBUG : Log::Severity::INFO
  end
end

Error Handling

Comprehensive error handling system:

Error Types

• ValidationError: Request validation failures

• NotFound: Resource not found (404)

• Unauthorized: Authentication failures (401)

• Forbidden: Authorization failures (403)

• InternalServerError: Server errors (500)

Error Response Format

{
  "Status": "Unprocessable Entity",
  "Title": "Validation Error",
  "Detail": "The request could not be processed due to validation errors.",
  "FieldErrors": {
    "name": ["Name must be between 2 and 50 characters"],
    "email": ["Email must be a valid email address"]
  },
  "ErrorId": "err_abc123",
  "Fingerprint": "validation_error_abc",
  "Timestamp": "2023-12-04T15:35:12Z"
}

Performance Characteristics

Compile-time Optimizations

• Type Elimination: Unused code is eliminated at compile time

• Method Inlining: Small methods are inlined for performance

• Dead Code Elimination: Unreachable code is removed

• Constant Folding: Compile-time constant evaluation

Runtime Performance

• Zero-cost Abstractions: Framework abstractions have minimal overhead

• Memory Efficiency: Predictable memory usage patterns

• Concurrent Processing: Efficient handling of multiple requests

• Connection Pooling: Optimized database and external service connections

Benchmarking

Azu is designed for high performance:

• Request Throughput: Handle thousands of requests per second

• Memory Usage: Low memory footprint with predictable patterns

• Latency: Sub-millisecond request processing overhead

• Scalability: Efficient resource usage for horizontal scaling

Security Architecture

Built-in Security Features

• CSRF Protection: Cross-site request forgery prevention

• Input Validation: Comprehensive request validation

• XSS Prevention: Automatic output escaping

• SQL Injection Prevention: Type-safe database queries

• Secure Headers: Security-focused HTTP headers

Security Best Practices

• Input Sanitization: All user input is validated and sanitized

• Output Encoding: Automatic HTML/XML encoding

• Authentication: Secure session management

• Authorization: Role-based access control

• HTTPS Enforcement: Secure communication protocols

Development vs Production

Development Mode

• Hot Reload: Automatic code and template reloading

• Debug Logging: Detailed request/response logging

• Error Pages: Comprehensive error information

• Performance Monitoring: Development-time metrics

Production Mode

• Optimized Compilation: Release-mode optimizations

• Minimal Logging: Production-appropriate logging levels

• Error Handling: User-friendly error responses

• Performance Monitoring: Production metrics and alerting

Next Steps

Now that you understand Azu's architecture:

1. Endpoints - Learn about endpoint patterns and best practices

2. Request Contracts - Master request validation and type safety

3. Response Objects - Structure your API responses

4. Routing - Organize your application routes

5. Middleware - Customize request processing

6. WebSocket Channels - Build real-time features

7. Components - Create interactive UI components

---

Understanding Azu's architecture gives you the foundation to build robust, type-safe, and performant web applications with confidence.