# Overview

**Azu** is a high-performance web framework for Crystal emphasizing type safety, modularity, and real-time capabilities.

## Quick Example

```crystal
require "azu"

module MyApp
  include Azu

  configure do
    port = 3000
  end
end

struct HelloRequest
  include Azu::Request
  getter name : String = "World"
end

struct HelloResponse
  include Azu::Response
  def initialize(@name : String); end
  def render
    "Hello, #{@name}!"
  end
end

struct HelloEndpoint
  include Azu::Endpoint(HelloRequest, HelloResponse)
  get "/"
  def call : HelloResponse
    HelloResponse.new(hello_request.name)
  end
end

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

## Architecture

```
HTTP Request → Router → Middleware Chain → Endpoint → Response
                                              ↓
                                    Request Contract (validation)
```

**Endpoints** are type-safe handlers with:

* **Request Contract**: Validates and types incoming data
* **Response Object**: Handles content rendering
* **Middleware**: Cross-cutting concerns (auth, logging, etc.)

## Core Features

| Feature                 | Description                                |
| ----------------------- | ------------------------------------------ |
| **Type-Safe Contracts** | Compile-time validation via `Azu::Request` |
| **Radix Routing**       | O(log n) lookup with path caching          |
| **WebSocket Channels**  | Real-time bidirectional communication      |
| **Live Components**     | Server-rendered with client sync (Spark)   |
| **Multi-Store Cache**   | Memory and Redis with auto-metrics         |
| **Middleware Stack**    | CORS, CSRF, Rate Limiting, Logging         |

## Documentation

| New to Azu?                                                                         | Need to do something?                                                                | Looking for API?                                                                    | Want to understand?                                                                     |
| ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| [Tutorials](https://github.com/azutoolkit/azu/blob/master/docs/tutorials/README.md) | [How-To Guides](https://github.com/azutoolkit/azu/blob/master/docs/how-to/README.md) | [Reference](https://github.com/azutoolkit/azu/blob/master/docs/reference/README.md) | [Explanation](https://github.com/azutoolkit/azu/blob/master/docs/explanation/README.md) |

### Tutorials

Step-by-step lessons to learn Azu:

* [Getting Started](/azu/tutorials/getting-started.md) - Install and create your first app
* [Building a User API](/azu/tutorials/building-a-user-api.md) - Complete CRUD API tutorial
* [Adding WebSockets](/azu/tutorials/adding-websockets.md) - Real-time features
* [Working with Databases](/azu/tutorials/working-with-databases.md) - CQL integration
* [Testing Your App](/azu/tutorials/testing-your-app.md) - Write comprehensive tests
* [Deploying to Production](/azu/tutorials/deploying-to-production.md) - Production deployment

### How-To Guides

Task-oriented guides for specific goals:

* [Endpoints](https://github.com/azutoolkit/azu/blob/master/docs/how-to/endpoints/README.md) - Create endpoints, handle parameters, return formats
* [Validation](https://github.com/azutoolkit/azu/blob/master/docs/how-to/validation/README.md) - Validate requests and models
* [Real-Time](https://github.com/azutoolkit/azu/blob/master/docs/how-to/real-time/README.md) - WebSocket channels and live components
* [Database](https://github.com/azutoolkit/azu/blob/master/docs/how-to/database/README.md) - Schema, models, queries, transactions
* [Caching](https://github.com/azutoolkit/azu/blob/master/docs/how-to/caching/README.md) - Memory and Redis caching
* [Middleware](https://github.com/azutoolkit/azu/blob/master/docs/how-to/middleware/README.md) - Custom handlers and logging
* [Deployment](https://github.com/azutoolkit/azu/blob/master/docs/how-to/deployment/README.md) - Production, Docker, scaling
* [Performance](https://github.com/azutoolkit/azu/blob/master/docs/how-to/performance/README.md) - Optimize endpoints and queries

### Reference

Technical specifications and API documentation:

* [Core API](https://github.com/azutoolkit/azu/blob/master/docs/reference/api/README.md) - Endpoint, Request, Response, Channel, Component
* [Handlers](/azu/handlers/built-in.md) - Built-in middleware handlers
* [Configuration](/azu/configuration/options.md) - All configuration options
* [Database](https://github.com/azutoolkit/azu/blob/master/docs/reference/database/README.md) - CQL API, validations, query methods
* [Error Types](/azu/errors/error-types.md) - HTTP error classes

### Explanation

Conceptual understanding of Azu:

* [Architecture](/azu/architecture/overview.md) - How Azu works
* [Request Lifecycle](/azu/architecture/request-lifecycle.md) - Request flow
* [Type Safety](/azu/architecture/type-safety.md) - Compile-time guarantees
* [Design Decisions](https://github.com/azutoolkit/azu/blob/master/docs/explanation/design-decisions/README.md) - Why Azu is built this way

### Resources

* [FAQ](/azu/resources/faq.md) - Common questions and troubleshooting
* [Contributing](/azu/resources/setup.md) - Development setup and guidelines


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://azutopia.gitbook.io/azu/readme.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.