> For the complete documentation index, see [llms.txt](https://azutopia.gitbook.io/azu/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://azutopia.gitbook.io/azu/readme.md).

# Overview

Azu is a web framework for Crystal built on typed contracts and real-time. These pages are organized by what you are trying to do. Not sure where to start? Read [Getting started](/azu/start-here/getting-started.md), then skim [Everything in the box](/azu/start-here/features.md).

## Start here

* [Getting started](/azu/start-here/getting-started.md): an endpoint with a validated contract, a page, a test and the dev dashboard, in about 15 minutes.
* [Everything in the box](/azu/start-here/features.md): every feature Azu ships, with a link to its guide.
* [FAQ and troubleshooting](/azu/start-here/faq.md): common questions and the errors you are likely to meet.
* [Migrate to 0.6](/azu/start-here/migrate-to-0.6.md): moving from the global `configure` style to `Azu::App`.

## Tutorials

Lessons that take you from zero to a working feature. Do them mostly in order.

* [Getting started](/azu/start-here/getting-started.md): your first app.
* [Building a user API](/azu/tutorials/building-a-user-api.md): a complete JSON CRUD API.
* [Working with databases](/azu/tutorials/working-with-databases.md): CQL models, migrations and queries.
* [Adding WebSockets](/azu/tutorials/adding-websockets.md): a chat channel with pub/sub.
* [Building live components](/azu/tutorials/building-live-components.md): server-rendered views that update in place.
* [Testing your app](/azu/tutorials/testing-your-app.md): endpoints, contracts, channels and components.
* [Deploying to production](/azu/tutorials/deploying-to-production.md): configuration, secrets and a running service.

## How-to guides

Short recipes for one task each.

**Endpoints and validation**

* [Create an endpoint](/azu/endpoints-and-validation/create-endpoint.md)
* [Handle parameters](/azu/endpoints-and-validation/handle-parameters.md): path, query, form and JSON.
* [Return different formats](/azu/endpoints-and-validation/return-different-formats.md): JSON, HTML, text, XML.
* [Validate requests](/azu/endpoints-and-validation/validate-requests.md)
* [Validate models](/azu/endpoints-and-validation/validate-models.md)
* [Handle validation errors](/azu/endpoints-and-validation/handle-validation-errors.md)
* [Handle file uploads](/azu/endpoints-and-validation/handle-file-uploads.md) and [validate file types](https://github.com/azutoolkit/azu/tree/master/docs/how-to/file-handling/validate-file-types.md)

**Errors and middleware**

* [Handle errors gracefully](/azu/errors-and-middleware/handle-errors-gracefully.md) and [create custom errors](https://github.com/azutoolkit/azu/tree/master/docs/how-to/errors/create-custom-errors.md)
* [Create custom middleware](/azu/errors-and-middleware/create-custom-middleware.md)
* [Add logging](/azu/errors-and-middleware/add-logging.md)
* [Use sessions](/azu/errors-and-middleware/use-sessions.md)

**Templates**

* [Render HTML templates](/azu/templates/render-html-templates.md)
* [Use template helpers](/azu/templates/use-template-helpers.md)
* [Enable hot reload](/azu/templates/enable-hot-reload.md)

**Real-time**

* [Create a WebSocket channel](/azu/real-time/create-websocket-channel.md)
* [Broadcast messages](/azu/real-time/broadcast-messages.md)
* [Build a live component](/azu/real-time/build-live-component.md)

**Data and caching**

* [Define a schema](/azu/data-and-caching/define-schema.md), [create models](https://github.com/azutoolkit/azu/tree/master/docs/how-to/database/create-models.md), [run migrations](https://github.com/azutoolkit/azu/tree/master/docs/how-to/database/run-migrations.md)
* [Query data](/azu/data-and-caching/query-data.md) and [handle transactions](https://github.com/azutoolkit/azu/tree/master/docs/how-to/database/handle-transactions.md)
* [Set up a memory cache](/azu/data-and-caching/setup-memory-cache.md) and [a Redis cache](https://github.com/azutoolkit/azu/tree/master/docs/how-to/caching/setup-redis-cache.md)
* [Run background jobs](/azu/data-and-caching/background-jobs.md)

**Testing**

* [Test endpoints](/azu/testing/test-endpoints.md)
* [Test WebSockets](/azu/testing/test-websockets.md)

**Performance**

* [Optimize endpoints](/azu/performance/optimize-endpoints.md)
* [Optimize database queries](/azu/performance/optimize-database-queries.md)
* [Monitor performance in development](/azu/performance/monitor-performance.md)

**Deployment**

* [Configure production](/azu/deployment/configure-production.md)
* [Deploy with Docker](/azu/deployment/deploy-with-docker.md)
* [Scale horizontally](/azu/deployment/scale-horizontally.md)
* [Scale real-time features out](/azu/deployment/scale-out-realtime.md)
* [Shut down gracefully](/azu/deployment/graceful-shutdown.md)

## Reference

Exact behavior, options and signatures.

**Core API**

* [Core module](/azu/core-api/core.md), [App](https://github.com/azutoolkit/azu/tree/master/docs/reference/api/app.md), [Router](https://github.com/azutoolkit/azu/tree/master/docs/reference/api/router.md)
* [Endpoint](/azu/core-api/endpoint.md), [Request](https://github.com/azutoolkit/azu/tree/master/docs/reference/api/request.md), [Response](https://github.com/azutoolkit/azu/tree/master/docs/reference/api/response.md)
* [Content negotiation](/azu/core-api/content-negotiation.md), [Streaming and SSE](https://github.com/azutoolkit/azu/tree/master/docs/reference/api/streaming.md)
* [OpenAPI](/azu/core-api/openapi.md), [Testing](https://github.com/azutoolkit/azu/tree/master/docs/reference/api/testing.md)
* [Cache](/azu/core-api/cache.md), [Redis](https://github.com/azutoolkit/azu/tree/master/docs/reference/api/redis.md)
* [Error types](/azu/core-api/error-types.md)

**Real-time**

* [Channel](/azu/real-time-1/channel.md), [Presence](https://github.com/azutoolkit/azu/tree/master/docs/reference/api/presence.md), [Component](https://github.com/azutoolkit/azu/tree/master/docs/reference/api/component.md)
* [Spark client and reconnects](/azu/real-time-1/spark-client.md), [Spark benchmarks](https://github.com/azutoolkit/azu/tree/master/docs/reference/spark-benchmarks.md)

**Handlers, configuration and templates**

* [Built-in handlers](/azu/handlers-configuration-and-templates/built-in.md)
* [Configuration options](/azu/handlers-configuration-and-templates/options.md), [environments](https://github.com/azutoolkit/azu/tree/master/docs/reference/configuration/environments.md), [`Azu::Env`](https://github.com/azutoolkit/azu/tree/master/docs/reference/configuration/env.md)
* [Template engine](/azu/handlers-configuration-and-templates/engine.md), [template helpers](https://github.com/azutoolkit/azu/tree/master/docs/reference/templates/helpers.md)

**Database**

* [CQL bridge](/azu/database/cql-bridge.md), [database dashboard](https://github.com/azutoolkit/azu/tree/master/docs/reference/database-dashboard.md)
* [CQL API](/azu/database/cql-api.md), [query methods](https://github.com/azutoolkit/azu/tree/master/docs/reference/database/query-methods.md), [validations](https://github.com/azutoolkit/azu/tree/master/docs/reference/database/validations.md)

**Releases**

* [Breaking changes](/azu/releases/breaking-changes.md): what changed in each version and how to adapt.

## Explanation

Why Azu works the way it does.

* [Everything in the box](/azu/start-here/features.md)
* [Architecture overview](/azu/explanation/overview.md), [request lifecycle](https://github.com/azutoolkit/azu/tree/master/docs/explanation/architecture/request-lifecycle.md), [type safety](https://github.com/azutoolkit/azu/tree/master/docs/explanation/architecture/type-safety.md), [performance design](https://github.com/azutoolkit/azu/tree/master/docs/explanation/architecture/performance-design.md)
* [Endpoints](/azu/explanation/endpoints.md), [contracts](https://github.com/azutoolkit/azu/tree/master/docs/explanation/concepts/contracts.md), [middleware](https://github.com/azutoolkit/azu/tree/master/docs/explanation/concepts/middleware.md), [real-time](https://github.com/azutoolkit/azu/tree/master/docs/explanation/concepts/real-time.md), [components](https://github.com/azutoolkit/azu/tree/master/docs/explanation/concepts/components.md), [Spark live views](https://github.com/azutoolkit/azu/tree/master/docs/explanation/spark-live-views.md)
* [Why contracts?](/azu/explanation/why-contracts.md) and [why type safety?](https://github.com/azutoolkit/azu/tree/master/docs/explanation/design-decisions/why-type-safety.md)

## Contributing

* [Development setup](/azu/contributing/setup.md), [code standards](https://github.com/azutoolkit/azu/tree/master/docs/contributing/standards.md), [roadmap](https://github.com/azutoolkit/azu/tree/master/docs/contributing/roadmap.md)
* [Benchmarks](/azu/contributing/benchmark.md): how Azu is measured against other frameworks.
* Design plans: [Azu 0.6, apps as values](https://github.com/azutoolkit/azu/tree/master/docs/plans/0.6-architecture.md), [unified JoobQ and Dashforge DSL](https://github.com/azutoolkit/azu/tree/master/docs/plans/joobq-dashforge-dsl.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.