# 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](https://azutopia.gitbook.io/azu/tutorials/getting-started) - Install and create your first app
* [Building a User API](https://azutopia.gitbook.io/azu/tutorials/building-a-user-api) - Complete CRUD API tutorial
* [Adding WebSockets](https://azutopia.gitbook.io/azu/tutorials/adding-websockets) - Real-time features
* [Working with Databases](https://azutopia.gitbook.io/azu/tutorials/working-with-databases) - CQL integration
* [Testing Your App](https://azutopia.gitbook.io/azu/tutorials/testing-your-app) - Write comprehensive tests
* [Deploying to Production](https://azutopia.gitbook.io/azu/tutorials/deploying-to-production) - 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](https://azutopia.gitbook.io/azu/handlers/built-in) - Built-in middleware handlers
* [Configuration](https://azutopia.gitbook.io/azu/configuration/options) - All configuration options
* [Database](https://github.com/azutoolkit/azu/blob/master/docs/reference/database/README.md) - CQL API, validations, query methods
* [Error Types](https://azutopia.gitbook.io/azu/errors/error-types) - HTTP error classes

### Explanation

Conceptual understanding of Azu:

* [Architecture](https://azutopia.gitbook.io/azu/architecture/overview) - How Azu works
* [Request Lifecycle](https://azutopia.gitbook.io/azu/architecture/request-lifecycle) - Request flow
* [Type Safety](https://azutopia.gitbook.io/azu/architecture/type-safety) - 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](https://azutopia.gitbook.io/azu/resources/faq) - Common questions and troubleshooting
* [Contributing](https://azutopia.gitbook.io/azu/resources/setup) - Development setup and guidelines