# Aventara Framework

> A typed API and frontend client from your Prisma schema.

Version: 1.0.0-rc.12. Release candidate; breaking changes are possible before a stable release. Links are relative to this deployment.

## Complete documentation

- [Full Markdown](/framework/llms-full.txt): All published Framework pages.

## Start building

- [Introduction](/framework/markdown/introduction): What Aventara is, how its pieces fit together, its current status and requirements.
- [Why Aventara](/framework/markdown/why-aventara): What you write with plain NestJS, GraphQL, tRPC and Aventara for the same API, and where Aventara does more, less or something different.
- [Installation](/framework/markdown/installation): Requirements, which package goes where (server or frontend, dev or runtime), and notes on Node, npm and pnpm.
- [Getting started](/framework/markdown/getting-started): Create an Aventara API, run it, generate a typed frontend client and make your first call.
- [Add to an existing project](/framework/markdown/existing-project): Use `aventara init` to add Aventara to an existing NestJS 12 project, with or without Prisma.

## Core concepts

- [Concepts](/framework/markdown/concepts): The mental model in one page - contracts and layers, Resources, operations, results and the contract hash - with links to the detailed pages.
- [Contract layers](/framework/markdown/contract-layers): The core, application and client contracts compiled from one schema, how the root and its two overlays combine, and why the frontend only ever sees the client layer.
- [Resources and operations](/framework/markdown/resources-and-operations): Every operation family and variant Aventara offers on a Resource, what each selects by and returns, which are not offered, with an example of each.
- [Results and typing](/framework/markdown/results-and-typing): How the generated client types results exactly from select, include and $count, why results are readonly, and how first misses, counts and errors behave.
- [Contract hash](/framework/markdown/contract-hash): What the client contract hash covers, how ETag and 304 use it, what the A2005 refusal means, and the regenerate workflow that keeps client and server in step.

## Shaping the API

- [Configuration](/framework/markdown/configuration): Configure the framework in src/aventara.config.ts - the root-only keys, the six layer keys, the resources tree, exposure, pipelines, limits, transactions, and the agent layer for MCP.
- [Exposure](/framework/markdown/exposure): Decide what each layer exposes with exposed and exemptions - hide Resources, fields, operations, capabilities and single operators, in Omit or Pick style, with overlays that only narrow.
- [Exposing and hiding fields](/framework/markdown/exposing-and-hiding-fields): Hide fields, make them write-only or read-only, narrow their filters, and set different rules for your server code and for remote callers.
- [Computed fields](/framework/markdown/computed-fields): Add virtual fields and compute values on read, create and update with compute stages - chained across layers, with a read-only ctx - and accept write-only input such as a password that is hashed before it is stored.
- [Field validators](/framework/markdown/field-validators): Declarative checks on a field's value with AvZ - lengths, ranges, patterns and formats - checked by the server and, before anything is sent, by the generated client.
- [Enums and scalar types](/framework/markdown/enums-and-scalars): How Prisma enums appear in the generated client, and how DateTime, BigInt, Decimal, Bytes and Json travel over the wire and come back as real values.
- [JSON fields](/framework/markdown/json-fields): Give a Json field a type with AvZ - declare the shape in the configuration, add checks to its parts, get it checked on every write and typed in server code and in the generated client.

## Querying & writing

- [Querying](/framework/markdown/querying): Filters, select and include, ordering, pagination, counts, nested writes and readonly results - from the frontend client or from server-side code.
- [Filtering, sorting and paging](/framework/markdown/filtering-sorting-paging): The where operators, equality shorthand, AND/OR/NOT, relation filters, orderBy including relations, and limit, offset and cursor paging.
- [Relations and nested writes](/framework/markdown/relations-and-nested-writes): Read related records with select and include, and create, link, update and unlink them in one call with nested directives.
- [Counting](/framework/markdown/counting): Count matching rows with find.count, count what a bulk write touched, and count or page related rows with the $count reducer.
- [Transactions](/framework/markdown/transactions): Run several operations atomically with $ref between steps, on the server and from the frontend; SQL steps, rollback behavior, cascade refusal and what runs inside a transaction.
- [Transactions with $ref](/framework/markdown/transactions-with-ref): Recipes for atomic multi-step writes - parent and child, preconditions, conditional steps, rollback, client versus server transactions, and cascade refusal.

## Security & behavior

- [Authentication and guards](/framework/markdown/authentication-and-guards): Require a signed-in caller with a pipeline guard that reads the request headers, answer A4000, A4001 and A4002, and send credentials from the generated client.
- [Pipelines](/framework/markdown/pipelines): Run your own code around every operation with guards, pipes, hooks, interceptors and filters, at the layer, Resource, family, variant and field levels, in a fixed order, inside transactions when you need it.
- [The pipeline context (ctx)](/framework/markdown/pipeline-context): What a stage's ctx tells it, the request's state (ctx.$state), and how a stage calls the framework through ctx - other Resources, ctx.$sql and ctx.$transaction - with an outbox and a likes-counter recipe.
- [Which stage do I use?](/framework/markdown/which-stage): Common tasks mapped to the pipeline stage that fits them (guards, pipes, validators, compute, hooks, interceptors, filters, Resource transaction stages and ctx.$state), with the order the stages run in and the rules people trip over.
- [Limits and safety](/framework/markdown/limits-and-safety): The limits that bound what a caller can ask for, how to change them per layer, and what the framework refuses before your database ever sees a request.
- [Request IDs and diagnostics](/framework/markdown/request-ids-and-diagnostics): How a request id is adopted or generated and where it appears, and how to receive the real error behind every unplanned failure.
- [Caching reads](/framework/markdown/caching-reads): Let a browser or a CDN keep a read's answer with the cache({ for, maxAge }) stage. The three audiences, where the stage goes and which one wins, the GET URL, the headers, and what to set on a CDN.

## Running in production

- [Server-side usage](/framework/markdown/server-side-usage): Call operations from your own NestJS services with framework.application and framework.client, catch the typed errors they throw, and pass a request id.
- [Deploying](/framework/markdown/deploying): Build and run an Aventara server in production - environment variables, the build, PostgreSQL, schema changes with db push or migrate, CORS, and generating and committing the frontend client.
- [Upgrading](/framework/markdown/upgrading): Move from 1.0.0-rc.11 to 1.0.0-rc.12 (lookup keys need filter, the scaffold's String ids), from 1.0.0-rc.8 to 1.0.0-rc.11 (Node and Prisma floors, stricter policy checks, grouped client calls, regenerate clients), from 1.0.0-rc.4 to 1.0.0-rc.8 (rebuild after a discovery change, policy additions, request type names), from 1.0.0-rc.3 to 1.0.0-rc.4 (build-time Contracts, the policy seam), from 1.0.0-rc.2 to 1.0.0-rc.3, from 1.0.0-rc.1 to 1.0.0-rc.2, from 1.0.0-rc.0 to 1.0.0-rc.1 (the new configuration shape, Av names, the $ ctx members) and from earlier pilots step by step, and the general flow for upgrading Aventara packages.

## Frontend client

- [Frontend client](/framework/markdown/frontend-client): Overview of the generated, typed TypeScript client - what it is, how it fits your frontend, and where to read more.
- [Client setup](/framework/markdown/client-setup): Set up a frontend with avclient init - flags, framework.client.ts, env variable or literal entrypoint, generateAt, how to import the client in Vite, Next.js and Node projects, and CORS.
- [Typed calls](/framework/markdown/typed-calls): How avClient.User.find.many and friends are typed - one property per Resource, named types, readonly results, enums, and helpers to name a result type.
- [Client errors](/framework/markdown/client-errors): The generated client's error classes, how to branch on them with instanceof, what cause and issues carry, AvTransportError versus AvError, and AvContractMismatchError.
- [Client options](/framework/markdown/client-options): Configure the generated client - new AvClient with entrypoint and fetch, per-call signal, headers and requestId, authentication through a custom fetch, and aborting.
- [Keeping in sync](/framework/markdown/keeping-in-sync): Regenerate the client when the server changes - what triggers it, the up-to-date check, running it in CI, and how a stale client behaves.
- [Several operations in one round trip](/framework/markdown/operation-sets): Calls made together go out as one POST /_all. avClient.all with strict and settle modes, aborting one call or a whole group, streamed answers, grouping false, avLazy, how /_all differs from /_transactions, and avClient.all on the server.
- [TanStack Query and SWR with Next.js](/framework/markdown/tanstack-query-and-swr): Prefetch Aventara data in a Server Component and hydrate it in the browser with TanStack Query or SWR - one shared query module on @/aventara/universal, avDehydrate on the server and avHydrate in the browser.

## Hosting

- [NestJS host](/framework/markdown/nestjs-host): Mount Aventara in NestJS with AventaraModule, inject the framework, and understand the mount path (`api`), startup log and what runs on Aventara routes.
- [MCP](/framework/markdown/mcp): Serve your API to AI agents over the Model Context Protocol - turn on mcp, choose what the agent layer exposes, the tools and the contract resource, OAuth with a verify function, and connecting Claude Code or Claude Desktop.
- [Express and Fastify](/framework/markdown/express-and-fastify): Run Aventara on Nest's Express or Fastify platform - what is the same, what differs, middleware exclusion on Fastify, global prefix and CORS.
- [Custom host](/framework/markdown/custom-host): Host an Aventara framework on any HTTP server by adapting it to @aventara/core/protocol - complete Express and plain node:http examples.
- [Testing and conformance](/framework/markdown/testing-and-conformance): @aventara/testing - a fake adapter, and the protocol corpus for holding a host or a client written by you to Aventara's HTTP answers: run it in-process, serve it, or read it as plain JSON.
- [Next.js host](/framework/markdown/nextjs-host): Serve Aventara from a Next.js App Router app with @aventara/next - scaffold or init, the src/aventara folder, Aventara() and its four members, request state, the three clients, serverExternalPackages and MCP.

## Examples

- [Example: blog API](/framework/markdown/example-blog-api): An end-to-end blog - Prisma schema with Users, Posts and Categories, configuration with a hidden field, client exemptions and a guard, the server, and frontend calls including a transaction.
- [Example: admin vs public](/framework/markdown/example-admin-vs-public): One API, two layers - server code gets the application layer with full access, remote callers get the narrower client layer; a Nest service and a frontend side by side.
- [Example: recipes](/framework/markdown/example-recipes): Short copy-paste recipes for the generated client - a pagination loop, a search box, create with a relation, an optimistic update and a counting badge.

## Reference

- [Configuration reference](/framework/markdown/config-reference): Every AvConfig key (adapter, prebuilt, policy included) and the createPrismaAdapter, describePrismaAdapter and aventara-build options, with type, default, the layers it applies to and an example.
- [Operations reference](/framework/markdown/operations-reference): Every operation family and variant with its accepted arguments, result shape, success code, HTTP status and the errors it can return.
- [Error codes](/framework/markdown/error-codes): The complete A-code and V-code tables - HTTP status, meaning, typical cause, fix and the generated client's error class for each.
- [HTTP protocol](/framework/markdown/http-protocol): Routes, headers, the response envelope, A- and V-codes with HTTP statuses, ETag and 304, a curl walkthrough, Operation Sets (/_all) and their streamed answer, cached reads as GET, and writing a custom host with @aventara/core/protocol.
- [Protocol API reference](/framework/markdown/protocol-api-reference): The @aventara/core/protocol entry point - AvProtocol.bind and its members, request and response types, headers, httpStatus, scalarFormats, isOperationResponse and normalizeEntrypoint.
- [Client API reference](/framework/markdown/client-api-reference): The generated client's surface - AvClient, AvClientOptions, AvCallOptions, AvFetch, error classes, named types, and the defineClientConfig / env / avclient generator.
- [NestJS API reference](/framework/markdown/nest-api-reference): AventaraModule.forRoot and forRootAsync, AventaraModuleOptions and AsyncOptions, the AVENTARA_FRAMEWORK token, @InjectFramework, startup errors and platform limits.
- [CLI reference](/framework/markdown/cli-reference): Flags, behavior and exit codes of the aventara and avclient commands, and the supported Node versions.
- [Troubleshooting](/framework/markdown/troubleshooting): Upgrading between releases, first-run warnings, and fixes for version refusals, stale clients, stale artifacts, CORS and common setup errors.
- [Next.js API reference](/framework/markdown/next-api-reference): Every export of @aventara/next, the generated @/aventara/client and @/aventara/universal entries, Aventara() options and members, and the errors the Next.js host raises.

## About

- [Changelog](/framework/markdown/changelog): User-facing changes in each Aventara release, newest first.
- [Roadmap](/framework/markdown/roadmap): Where Aventara stands today and what is planned publicly - the path to 1.0, more ORMs and hosts, and how the work is measured.
- [FAQ](/framework/markdown/faq): Common questions - how Aventara compares with tRPC and GraphQL, using it without Nest, hiding fields, the generated client and the license in plain terms.
- [Glossary](/framework/markdown/glossary): The terms Aventara uses - Resource, contract, layer, family, variant, envelope, A and V codes, ETag, api, entrypoint, generateAt, adapter and host.
- [License](/framework/markdown/license): Aventara is licensed under PolyForm Shield 1.0.0 with an additional permission - free to use, including in commercial applications - plus a naming policy.

## For AI agents

- [Working with AI agents](/framework/markdown/ai-agents): How Aventara keeps an AI coding agent on track - the agent skill and AGENTS.md section the CLI writes (shown in full, to copy), precise types, an error catalog with a docs link per code, one way per task, the generated client, and a local MCP endpoint for your coding agent.